Operations
Production checklist
What to change before the first real user signs in: stores, locks, secrets, URLs, logout, logging and dependencies.
The quick start and the example app use in-memory stores so that they run with no setup. Work through this list before deploying.
Storage
-
SessionStoreon your database.MemorySessionStoreloses every session on restart and cannot be shared. Indexuser_idand the provider session id, and purge expired rows. See Implement the stores. -
GrantStoreon your database, encrypted at rest. It holds one long-lived refresh token per user. - A distributed
GrantLockwhen you run several replicas (or several worker processes), so two of them never rotate the same grant at once. The default lock only covers one process. - A shared
ReplayStorewhen you run several replicas (for example RedisSET NX PX), so a logout token replayed on another instance is refused.
Secrets
- Cookie secret of at least 32 random characters (
openssl rand -base64 48), from your secret manager or environment. Shorter secrets are refused withCFG_001. Rotating it only invalidates sign-ins in progress: the session cookie is an opaque random id and is not sealed with it. - Client secret from the environment. Without
client_secretthe SDK acts as a public client and the machine API is unavailable, so fail at startup on a missing variable rather than passingNone. - Nothing secret in source control, logs or error responses.
URLs and registration
-
redirect_uriis<origin><base_path>/callback, over HTTPS, and registered identically in auth-service.AuthHandlersrefuses a mismatch. -
post_logout_redirect_uriis registered if you set it. - Back-channel logout URI
<origin><base_path>/backchannel-logoutis registered in auth-service: HTTPS and reachable from auth-service. auth-service waits for these deliveries when a user signs out, so keep the endpoint fast. - End-session or the back-channel URI is enabled, so the ID token carries
sid. Keeprequire_provider_sessionat its default (True). - LiteLLM support is on and
gateway_urlmatches the gateway URL exactly (no trailing slash), when you use the gateway. - Machine scopes
billing:read,consumption:read,consumption:writeare granted, when you use the machine API. - Your reverse proxy forwards the
/auth/*paths, theCookie,OriginandSec-Fetch-Siteheaders and the request body of the back-channel route unchanged, and terminates TLS (consider HSTS).
Application behaviour
- Entitlements are enforced on the server, in each route, not only hidden in the UI.
- Your own
POST,PUT,PATCHandDELETEroutes checkOrigin, as the SDK does for/auth/logout. - The back-channel route stays outside session and CSRF protection: it is called without cookies.
-
on_sessions_endedcloses sockets or drops caches of the users whose sessions ended. - Tune
session_ttl_seconds(8 hours by default) andclaims_renew_seconds(15 minutes by default) to how quickly role and plan changes must reach users. -
await auth.aclose()runs when the application stops (a FastAPIlifespan, for example), unless you passed your ownhttp_client, which the SDK never closes.
Logging and errors
-
on_erroris set and logserror.to_json()forAuthAiErrors: it is the only place the real cause of a failed sign-in appears. - Query strings are not logged: the callback URL carries the authorization code. uvicorn's access log prints them by default: see Keep the authorization code out of the logs.
- Responses use
to_public_json(), nevermessageordetails.
Dependencies and runtime
- Python 3.12 or later.
- Server clocks are synchronised (token verification allows
clock_tolerance_seconds, 5 by default). - Dependency audit in CI (
pip-audit).
Verify end to end
Run the example app against your auth-service and click Self-test: it exercises sign-in, claims renewal, per-audience tokens, introspection, the wallet, the gateway, billing and consumption, and writes a report free of any token or secret to the server log.