Phoenix OAuth2 Authorization Server#

Overview#

Phoenix v19.0.0 adds a built-in OAuth2 authorization server — Phoenix now issues tokens to clients, not just delegates to external identity providers 1. The primary consumers are the Phoenix CLI (px auth login) and MCP clients, which can now obtain bearer tokens through a standards-compliant flow instead of manually provisioned API keys.

RFCs implemented:

This feature is separate from Phoenix's existing relying-party OAuth2 (external IdP sign-in via PHOENIX_OAUTH2_* env vars). Both coexist: the existing IdP login lives in src/phoenix/server/api/routers/oauth2.py and src/phoenix/server/oauth2.py; the new authorization server lives in src/phoenix/server/api/routers/oauth2_authorization_server.py and src/phoenix/server/oauth2_authorization_server.py 1.

Endpoints#

All endpoints are mounted only when PHOENIX_ENABLE_OAUTH2_AUTHORIZATION_SERVER=true (default). A disabled server returns 404 rather than falling through to the SPA, which is the signal the CLI uses to detect "no OAuth support" 2.

Metadata document advertises: response_types_supported: ["code"], grant_types_supported: ["authorization_code", "refresh_token"], code_challenge_methods_supported: ["S256"], token_endpoint_auth_methods_supported: ["none"], and registration_endpoint when DCR is enabled 2.

Rate limits: /oauth2/token and /oauth2/revoke share a limiter (0.2 req/s per IP, 60-second window). /oauth2/register has its own limiter configurable via PHOENIX_OAUTH2_DCR_RATE_LIMIT_PER_HOUR (default 10/hour) 2.

Authorization Code + PKCE Flow#

Client → GET /oauth2/authorize?client_id=…&code_challenge=…&code_challenge_method=S256&…
       ← 302 → consent page (SPA)
User approves consent
Client → POST /oauth2/authorize/decision {approved: true, code_challenge, …}
       ← {redirect_to: "…?code=…"}
Client → POST /oauth2/token {grant_type=authorization_code, code=…, code_verifier=…}
       ← {access_token, refresh_token, expires_in}

PKCE: S256 only — no plain support 3. The verifier pattern enforces ^[A-Za-z0-9._~-]{43,128}$. The S256 challenge is computed as base64url(sha256(verifier)) and verified with hmac.compare_digest to prevent timing attacks 3.

Authorization code security: Codes are stored as SHA-256 hashes (hash_authorization_code) so a DB leak yields no redeemable codes 3. Codes expire in 5 minutes and are atomically claimed via conditional DELETE … RETURNING; concurrent redemptions have exactly one winner 2.

Grants are database rows (oauth2_grants) created at code redemption, not at browser approval — abandoned consent flows leave no grant behind 1. Grant lifetime defaults to 90 days (PHOENIX_OAUTH2_GRANT_EXPIRY_DAYS); both access and refresh token lifetimes are clamped to the grant's remaining expiry at mint time 1.

Refresh token rotation + replay detection: Spending a refresh token mints a new token pair and marks the old refresh token as consumed (not deleted). Presenting a consumed token signals that two parties hold it, triggering full grant revocation per RFC 9700 §4.14.2 1.

Public clients only: token_endpoint_auth_method: none across all clients — no client secrets or client_credentials grant 1.

Resource indicators (RFC 8707): The resource parameter is accepted at /authorize and /token, persisted through the authorization code and grant, and embedded in token claims. This allows per-resource enforcement to be added later without a schema migration 1.

Dynamic Client Registration#

POST /oauth2/register (RFC 7591) is governed by a three-position policy dial: PHOENIX_OAUTH2_DYNAMIC_CLIENT_REGISTRATION = disabled | local_only | enabled (default: enabled for out-of-the-box MCP client compatibility) 1.

Redirect URI classes — validated differently per dial position 3:

HTTPS redirect hosts can be further pinned with PHOENIX_OAUTH2_ALLOWED_REDIRECT_HOSTS (comma-separated, unset = all hosts) 1.

Abuse controls: Cap of 50 unconsumed clients per IP per day; rate limited by PHOENIX_OAUTH2_DCR_RATE_LIMIT_PER_HOUR (default 10/hour). Dynamically registered client IDs are prefixed px_dcr_ 2. Abandoned DCR clients (no grant ever created) are cleaned up automatically 2.

Key Files and Configuration#

Primary Implementation Files#

Environment Variables#

Database#

Migration 132d988c5bef_add_oauth2_authorization_server_tables adds the oauth2_clients, oauth2_authorization_codes, and oauth2_grants tables 1.

CLI and MCP Integration#

px auth login (Authorization Code + PKCE)#

The CLI implements the full authorization code + PKCE flow 1:

1. Binds an ephemeral http://127.0.0.1:<port>/callback listener to receive the authorization code.
2. Opens the authorization URL in a browser; falls back to printing the URL for --no-browser / SSH use.
3. Validates state (minimum 22 characters) to prevent CSRF.
4. Persists access and refresh tokens into the active profile under a settings lock.
5. Subsequent commands silently refresh when within 60 seconds of expiry, with rotation awareness.

px auth logout revokes the refresh token (ending the whole grant). px auth status reports the authenticated user and token expiry 1.

The CLI pre-flights /.well-known/oauth-authorization-server before starting the browser flow, failing fast if the server has the authorization server disabled 4.

MCP Server#

The MCP server mounts at /mcp when PHOENIX_ENABLE_MCP_SERVER=true (default). It uses Phoenix bearer-token authentication and serves as the reference end-to-end proof of the OAuth2 chain 5. Clients (e.g., Cursor) register via DCR at /oauth2/register, then complete the authorization code + PKCE flow to obtain tokens scoped to the /mcp resource indicator 5.