Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/auth0-tenant-token-issuers.changed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Document which Auth0 tenant issues each token API v1 accepts or requests in staging and production.
84 changes: 84 additions & 0 deletions docs/migration/cloud-run-operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,90 @@ tests therefore run against the staging simulation service and staging Modal
workers. The old gateway is one shared Modal app that reports no environment,
so `old_gateway_direct` is not checked.

## Auth0 tenants and tokens

Four Auth0 tenants issue the tokens API v1 accepts or requests. Each
environment signs users in through one tenant and gives PolicyEngine's servers
their tokens from another (decisions 1.1 · 5 and 6.1 · 1). User sign-in stays
on `policyengine` and `policyengine-dev`; it doesn't move to API v1's own
tenants. The settings named
below hold the live values. This section records them as of 2026-11-18,
because the repository alone can't show which tenant issues what.

| Tenant | Used by | What it issues | Issuer (`iss`) |
| --- | --- | --- | --- |
| `policyengine` | Production, and Simulation API tokens for both environments | Signed-in users' tokens for app v3; Management API tokens for API v1; Simulation API tokens; Household API tokens for partner clients and the developer portal, which API v1 doesn't accept | `https://auth.policyengine.org/` for user sign-in, `https://policyengine.uk.auth0.com/` for the rest |
| `policyengine-dev` | Staging, app v3 previews and local development | Signed-in users' tokens, the staging test user's tokens, and Management API tokens for API v1 | `https://policyengine-dev.uk.auth0.com/` |
| `policyengine-api` | Production | Client-credentials tokens for API v1's production server clients | `https://policyengine-api.uk.auth0.com/` |
| `policyengine-api-staging` | Staging | Client-credentials tokens for API v1's staging server clients | `https://policyengine-api-staging.uk.auth0.com/` |

A token's issuer is the address it was requested from, so `policyengine` has
two: its custom domain and its own `*.auth0.com` domain. Only `policyengine`
has a custom domain.

### Tokens in each environment

| Token | Requested by | Production tenant and audience | Staging tenant and audience | Settings |
| --- | --- | --- | --- | --- |
| Signed-in user, sent to API v1 | App v3; a PolicyEngine server may forward it in `PolicyEngine-User-Authorization` | `policyengine` through `auth.policyengine.org`, `https://api.policyengine.org/` | `policyengine-dev`, `https://staging-api.policyengine.org/` | `PUBLIC_API_AUTH_ISSUER`, `PUBLIC_API_AUTH_AUDIENCE` |
| Server, sent to API v1 | PolicyEngine's servers | `policyengine-api`, `https://api.policyengine.org/` | `policyengine-api-staging`, `https://staging-api.policyengine.org/` | `PUBLIC_API_SERVER_AUTH_ISSUER`, `PUBLIC_API_AUTH_AUDIENCE`, `PUBLIC_API_SERVER_CLIENT_IDS` |
| CI server, sent to API v1 | Deployed-API test jobs in `push.yml` | `policyengine-api`, `https://api.policyengine.org/` | `policyengine-api-staging`, `https://staging-api.policyengine.org/` | `CI_SERVER_AUTH0_*` |
| CI test user, sent to API v1 | Staging live tests, by the password-realm grant on the `policyengine-staging-ci` connection | None | `policyengine-dev`, `https://staging-api.policyengine.org/` | `STAGING_AUTH0_TEST_*` |
| Simulation API, sent by API v1 | API v1 | `policyengine`, `https://simulation-api.policyengine.org` | `policyengine`, `https://simulation-api.policyengine.org` | `GATEWAY_AUTH_*` |
| Management API, to delete Auth0 users (`delete:users`) | API v1 | `policyengine`, `https://policyengine.uk.auth0.com/api/v2/` | None | `AUTH0_MANAGEMENT_*` |
| Management API, to read users' profiles (`read:users`) | API v1 | `policyengine`, `https://policyengine.uk.auth0.com/api/v2/` | `policyengine-dev`, `https://policyengine-dev.uk.auth0.com/api/v2/` | `AUTH0_USER_PROFILES_*` |

### How API v1 tells the tenants apart

- API v1 verifies a bearer token with the signing keys, issuer and audience of
the issuer the token names, and refuses any other issuer.
- From `PUBLIC_API_AUTH_ISSUER` it accepts signed-in users' tokens only. A
client-credentials token from that issuer is refused, even when its client
ID is in `PUBLIC_API_SERVER_CLIENT_IDS`.
- From `PUBLIC_API_SERVER_AUTH_ISSUER` it accepts only client-credentials
tokens of clients in `PUBLIC_API_SERVER_CLIENT_IDS`.
- Deploy validation requires the two issuers to differ.
- Staging and production differ in both issuer and audience, so a token from
one environment is refused in the other.
- `policyengine-api` and `policyengine-api-staging` refuse user access to their
API definitions (`deny_all`) and have no sign-in connections.
- `policyengine` grants no client access to `https://api.policyengine.org/`, so
it issues no client-credentials token for API v1.

Don't change `PUBLIC_API_AUTH_ISSUER` in an environment where users have signed
in: accounts are keyed by issuer and subject, so every user would get a new,
empty account (see "Settings" in
[`stage-12a-user-login.md`](stage-12a-user-login.md#settings)).

### Where the settings come from

| Provider | Settings |
| --- | --- |
| GitHub `staging` and `production` environment variables | `PUBLIC_API_AUTH_*`, `PUBLIC_API_SERVER_AUTH_ISSUER`, `PUBLIC_API_SERVER_CLIENT_IDS`, `CI_SERVER_AUTH0_DOMAIN`, `CI_SERVER_AUTH0_CLIENT_ID`, `CI_SERVER_AUTH0_AUDIENCE`, `AUTH0_USER_PROFILES_DOMAIN`, `AUTH0_USER_PROFILES_CLIENT_ID` |
| GitHub `production` environment variables | `AUTH0_MANAGEMENT_DOMAIN`, `AUTH0_MANAGEMENT_CLIENT_ID` |
| GitHub `staging` environment variables | `STAGING_AUTH0_TEST_DOMAIN`, `STAGING_AUTH0_TEST_AUDIENCE`, `STAGING_AUTH0_TEST_REALM` |
| GitHub environment secrets | `CI_SERVER_AUTH0_CLIENT_SECRET`, and in `staging`, `STAGING_AUTH0_TEST_CLIENT_ID`, `STAGING_AUTH0_TEST_CLIENT_SECRET`, `STAGING_AUTH0_TEST_USERNAME`, `STAGING_AUTH0_TEST_PASSWORD` |
| GitHub environment secrets naming Secret Manager versions | `AUTH0_MANAGEMENT_CLIENT_SECRET_RESOURCE`, `AUTH0_USER_PROFILES_CLIENT_SECRET_RESOURCE` |
| GitHub organization secrets, shared by both environments | `GATEWAY_AUTH_ISSUER`, `GATEWAY_AUTH_AUDIENCE`, `GATEWAY_AUTH_CLIENT_ID`, and `GATEWAY_AUTH_CLIENT_SECRET_RESOURCE`, which names a Secret Manager version |

To compare this section with what is deployed:

```bash
# The GitHub settings of one environment
gh variable list --repo PolicyEngine/policyengine-api --env production

# The issuers and audiences on the service's latest revision
gcloud run services describe policyengine-api \
--project policyengine-api --region us-central1 --format=json \
| jq -r '.spec.template.spec.containers[0].env[]
| select(.name | test("^(PUBLIC_API_(AUTH_ISSUER|AUTH_AUDIENCE|SERVER_AUTH_ISSUER)|GATEWAY_AUTH_(ISSUER|AUDIENCE))$"))
| "\(.name)=\(.value)"'

# The issuer a tenant publishes
curl -s https://policyengine-api.uk.auth0.com/.well-known/openid-configuration \
| jq -r .issuer
```

## IAM and bootstrap constraints

- The GitHub deploy service account holds `roles/run.developer`: it can deploy to
Expand Down
26 changes: 17 additions & 9 deletions docs/migration/stage-12a-user-login.md
Original file line number Diff line number Diff line change
Expand Up @@ -822,10 +822,13 @@ No setting is new for signed-out saving: the unauthenticated-user header works
whether or not the Auth0 settings below are present. Without them, bearer
requests keep their 401/503 behavior, and signed-out requests still work.

[Auth0 tenants and tokens](cloud-run-operations.md#auth0-tenants-and-tokens)
lists which tenant issues each token in each environment.

| Setting | Source | Meaning |
| --- | --- | --- |
| `PUBLIC_API_AUTH_REQUIRED` | GitHub variable (`staging`, `production`) | `1` requires issuer and audience; `0` allows them to be absent, so bearer requests answer 401 or 503 |
| `PUBLIC_API_AUTH_ISSUER` | GitHub variable | Auth0 issuer URL, normalized to a trailing `/` (the custom domain, for example `https://auth.policyengine.org/`) |
| `PUBLIC_API_AUTH_ISSUER` | GitHub variable | Issuer URL of the users' Auth0 tenant, normalized to a trailing `/`: the custom domain `https://auth.policyengine.org/` in production, the tenant's own domain `https://policyengine-dev.uk.auth0.com/` in staging |
| `PUBLIC_API_AUTH_AUDIENCE` | GitHub variable | The Public API resource-server identifier |
| `PUBLIC_API_SERVER_CREDENTIAL_REQUIRED` | GitHub variable (optional) | `1` refuses every request without a server credential outside the public routes; unset, empty or `0` (what deploys write by default) serves them. `1` needs `PUBLIC_API_SERVER_CLIENT_IDS` |
| `PUBLIC_API_SERVER_AUTH_ISSUER` | GitHub variable (optional) | Issuer of server tokens: the Public API's own Auth0 tenant (decision 1.1 · 5), for example `https://policyengine-api.uk.auth0.com/` in production and `https://policyengine-api-staging.uk.auth0.com/` in staging. Normalized to a trailing `/`; HTTPS; needs `PUBLIC_API_AUTH_AUDIENCE` and must differ from `PUBLIC_API_AUTH_ISSUER`. Set it to the new tenant's issuer exactly as its OpenID configuration publishes it: the check can't tell that another domain of the users' tenant, such as `policyengine.uk.auth0.com`, names the same tenant. Unset accepts no server token |
Expand All @@ -842,10 +845,11 @@ requests keep their 401/503 behavior, and signed-out requests still work.

> **Set the final issuer before the first sign-in.** `user_identities` is
> keyed by `(issuer, subject)`, so `PUBLIC_API_AUTH_ISSUER` must hold its
> final value, the custom domain (for example
> `https://auth.policyengine.org/`) rather than the tenant's `*.auth0.com`
> domain, before anyone signs in to that environment. Changing it later
> makes every existing user look new: their next sign-in provisions a new,
> final value before anyone signs in to that environment. In production that
> is the custom domain `https://auth.policyengine.org/`, not the tenant's
> `*.auth0.com` domain. Staging's users' tenant has no custom domain, so its
> final value is `https://policyengine-dev.uk.auth0.com/`. Changing the value
> later makes every existing user look new: their next sign-in provisions a new,
> empty account, and their old account and its saved work are orphaned,
> with no sign-in that can read, export, or delete them. Nothing re-keys
> identities automatically.
Expand Down Expand Up @@ -976,11 +980,15 @@ may have it.

## Auth0 prerequisites (operator)

Configure staging first, then production:
Configure staging's users' tenant (`policyengine-dev`) first, then
production's (`policyengine`).
[Auth0 tenants and tokens](cloud-run-operations.md#auth0-tenants-and-tokens)
lists every tenant and the tokens it issues.

1. **Custom domain** (for example `auth.policyengine.org`). Tokens then carry
that issuer. Finish this before setting `PUBLIC_API_AUTH_ISSUER`, which
must not change once a user has signed in (see "Settings").
1. **Custom domain, production only** (`auth.policyengine.org`). Tokens
requested through it carry that issuer. Finish this before setting
production's `PUBLIC_API_AUTH_ISSUER`, which must not change once a user
has signed in (see "Settings"). Staging uses its tenant's own domain.
2. **Public API resource server** (RS256), whose identifier becomes
`PUBLIC_API_AUTH_AUDIENCE`.
3. **Social connections and SPA applications** for app v3.
Expand Down
Loading