mcp-auth-adapter: Instructions file for Codex

AGENTS.md

Project overview

mcp-auth-adapter is a thin, stateless OAuth/OIDC auth adapter for MCP clients. It sits in front of upstream IdP (Keycloak-style) so MCP servers can advertise this adapter as the authorization server instead of the raw IdP URL. It does not issue tokens — all real auth/token work stays on the upstream IdP.

Key responsibilities

• Discovery — Serves /.well-known/openid-configuration and /.well-known/oauth-authorization-server as a filtered, MCP-oriented view of upstream OIDC metadata (with optional injection of this app's DCR, authorization, and token proxy URLs).
• Dynamic Client Registration (DCR) — POST /register returns an upstream client_id (RFC 7591 style, public client). Supports per-MCP-client IdP client mapping via MCP_PROXY_DCR_CLIENT_NAME_MAP (pattern-based client_name matching with optional per-client allowed_redirect_uris enforced at /authorize and /token time, not at DCR time — the adapter is stateless). Falls back to MCP_PROXY_DCR_CLIENT_ID for unmatched names. Validates redirect_uris format (parseable URI, no fragments per RFC 6749 §3.1.2; any scheme including custom/private-use per RFC 8252 §7.1) and type-checks grant_types/response_types (must be arrays of strings). Invalid input returns RFC 7591 invalid_client_metadata errors. Access logs include idpClient, matchedMapping, clientName (truncated to 200 chars), and redirect_uris count for audit. Auto-enables when MCP_PROXY_DCR_CLIENT_ID or MCP_PROXY_DCR_CLIENT_NAME_MAP is set.
• Authorization adapter — GET /authorize validates redirect_uri against configured patterns, wraps original redirect_uri + state into a signed HMAC state blob, rewrites redirect_uri to the adapter's callback, and redirects to upstream. Supports scope filtering, optional CIMD client_id substitution, and RFC 8707 resource parameter validation (format check always active; optional require + allowlist enforcement via config). Auto-enables when scope filtering, CIMD, or MCP_PROXY_AUTH_STATE_SECRET is configured.
• Authorization callback (RFC 9207 iss interception) — GET /authorize/callback receives the upstream redirect, verifies the signed state blob (HMAC + expiry), validates upstream iss parameter using two-tier logic, then redirects to the original MCP client redirect_uri with the adapter's iss value. Prevents OAuth mix-up attacks per RFC 9207.
• Token proxy — POST /token proxies token requests to the upstream IdP. For authorization_code grants, validates redirect_uri against allowed patterns and rewrites it to the adapter's callback URL. For refresh_token grants, passes through without redirect_uri modification. For client_credentials and urn:ietf:params:oauth:grant-type:jwt-bearer grants, passes all parameters through without redirect_uri logic (covers both the Client Credentials extension and the Enterprise-Managed Authorization extension). RFC 8707 resource parameter validation is applied to all grant types except refresh_token. Forwards the Authorization header to upstream for non-CIMD requests (supports client_secret_basic per RFC 6749 §2.3.1; skipped for CIMD because client_id is rewritten). Always forwards DPoP / DPoP-Nonce request headers and relays DPoP-Nonce responses. Always active when the authorize proxy is active.
• PAR proxy (RFC 9126) — POST /par applies the same authorize-time transforms (scopes, CIMD, redirect_uri/state wrapping, resource) and proxies to the upstream PAR endpoint, returning the upstream request_uri (IdP holds PAR state; adapter stays stateless). Forwards Authorization / DPoP / DPoP-Nonce like /token. GET /authorize with request_uri forwards only client_id + request_uri (CIMD rewrite only). Auto-enables when the authorize proxy is active and upstream advertises pushed_authorization_request_endpoint — discovery is rewritten to {MCP_BASE_URL}/par; never invented if upstream omits PAR.
• CIMD adapter (EXPERIMENTAL) — Accepts CIMD-style client_id URLs from MCP clients, validates metadata documents, maps them to upstream IdP client_ids, and proxies /authorize, /par, and /token with client_id substitution. Auto-enables when MCP_PROXY_CIMD_MAP or MCP_PROXY_CIMD_DEFAULT_CLIENT_ID is set.