Skip to content

Authorization deployment runbook

Audience: internalStatus: reference

Internal — how ESZ issues and rotates the credentials behind the platform's authorization. The partner-facing view of the same mechanisms (the four auth hops) is Authentication.

  1. Apply auth and integrations migrations before starting resource services.
  2. For Entra-managed access, record the groups' immutable object IDs, set MICROSOFT_GROUP_PERMISSIONS, and verify every configured bundle exists.
  3. For locally managed access, create an AccessGroup in the auth admin, select a permission bundle, and assign users. Entra and local access are merged at the user's next login.
  4. Create one OAuth client per machine caller, including logging and e-mail ingress senders. Grant only the required scopes and set the shortest practical token lifetime.
  5. Deliver each client secret through the deployment secret store. Callers exchange it at POST /auth/oauth/token; never place it in a repository or image.
  6. A fixed-header caller that cannot perform an OAuth exchange may receive a long-lived Bearer token from the OAuth client's Issue direct token action in the auth admin. The equivalent CLI is issue_client_token <client-id> --scope <scope> --ttl-days <days>. Configure the caller to send it directly as Authorization: Bearer <token>; it must not call the OAuth token endpoint. Record its jti, owner and expiry. It cannot be individually revoked, so this is an exception requiring an explicit rotation plan.
  7. INTEGRATIONS_EMAIL_TOKEN is a compatibility credential for the nginx mail ingress only. Every request carrying it is attributed to the single INTEGRATIONS_EMAIL_CLIENT_NAME sender policy, so per-submitter attribution and per-submitter sender allowlists ended with the SMTP relay. This holds while the ingress has effectively one external submitter; onboard additional submitters as OAuth clients with their own sender policies instead. Prefer an OAuth client and remove the static token when the ingress can exchange credentials itself.
  8. For signing-key rotation, publish the new key with a new OIDC_KEY_ID and keep the previous public key and OIDC_PREVIOUS_KEY_ID configured until every short- and long-lived token signed by it has expired.
  9. Remove the previous key only after the latest recorded token expiry.