From 909b02a90cd0212fc611e39eb29f15f45eb3a442 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:12:24 +0400 Subject: [PATCH 1/2] Document which Auth0 tenant issues each API v1 token Add a section to the Cloud Run reference listing the four Auth0 tenants, the tokens each issues in staging and production, how API v1 tells them apart, and where each setting comes from. Correct the Stage 12A document, which said every environment uses a custom domain: only production does, and staging's issuer is the tenant's own domain. Co-Authored-By: Claude Opus 5.5 --- .../auth0-tenant-token-issuers.changed.md | 1 + docs/migration/cloud-run-operations.md | 82 +++++++++++++++++++ docs/migration/stage-12a-user-login.md | 26 ++++-- 3 files changed, 100 insertions(+), 9 deletions(-) create mode 100644 changelog.d/auth0-tenant-token-issuers.changed.md diff --git a/changelog.d/auth0-tenant-token-issuers.changed.md b/changelog.d/auth0-tenant-token-issuers.changed.md new file mode 100644 index 000000000..2a5e3c205 --- /dev/null +++ b/changelog.d/auth0-tenant-token-issuers.changed.md @@ -0,0 +1 @@ +Document which Auth0 tenant issues each token API v1 accepts or requests in staging and production. diff --git a/docs/migration/cloud-run-operations.md b/docs/migration/cloud-run-operations.md index 6b4355dae..c3260769a 100644 --- a/docs/migration/cloud-run-operations.md +++ b/docs/migration/cloud-run-operations.md @@ -282,6 +282,88 @@ 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). 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 diff --git a/docs/migration/stage-12a-user-login.md b/docs/migration/stage-12a-user-login.md index d93eec83a..b7465a3aa 100644 --- a/docs/migration/stage-12a-user-login.md +++ b/docs/migration/stage-12a-user-login.md @@ -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 | @@ -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. @@ -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. From 1fee9468722b8001b26edb1ff89091496471d2b1 Mon Sep 17 00:00:00 2001 From: Anthony Volk <14987227+anth-volk@users.noreply.github.com> Date: Wed, 18 Nov 2026 22:13:30 +0400 Subject: [PATCH 2/2] State that user sign-in stays on the users' tenants Co-Authored-By: Claude Opus 5.5 --- docs/migration/cloud-run-operations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/migration/cloud-run-operations.md b/docs/migration/cloud-run-operations.md index c3260769a..9d26f6ea8 100644 --- a/docs/migration/cloud-run-operations.md +++ b/docs/migration/cloud-run-operations.md @@ -286,7 +286,9 @@ so `old_gateway_direct` is not checked. 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). The settings named +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.