2.12.4
The OIDC proxy enables FastMCP servers to authenticate with OIDC providers that don’t support Dynamic Client Registration (DCR) out of the box. This includes OAuth providers like: Auth0, Google, Azure, AWS, etc. For providers that do support DCR (like WorkOS AuthKit), use RemoteAuthProvider instead.
The OIDC proxy is built upon OAuthProxy so it has all the same functionality under the covers.
Implementation
Provider Setup Requirements
Before using the OIDC proxy, you need to register your application with your OAuth provider:- Register your application in the provider’s developer console (Auth0 Applications, Google Cloud Console, Azure Portal, etc.)
- Configure the redirect URI as your FastMCP server URL plus your chosen callback path:
- Default:
https://your-server.com/auth/callback - Custom:
https://your-server.com/your/custom/path(if you setredirect_path) - Development:
http://localhost:8000/auth/callback
- Default:
- Obtain your credentials: Client ID and Client Secret
Basic Setup
Here’s how to implement the OIDC proxy with any provider:Configuration Parameters
OIDCProxy Parameters
Client secret from your registered OAuth application. Optional for PKCE public
clients. When omitted,
jwt_signing_key must be provided.Optional public base URL for the protected resource metadata and token audience.Use this when your OAuth callbacks and operational endpoints need to live under one public URL, but the protected MCP resource should be advertised under another. FastMCP will still append the MCP mount path (for example,
/mcp) to this base URL.Audience parameter for OIDC providers that require it (e.g., Auth0). This is
typically your API identifier.
New in version
2.13.1Custom token verifier for validating tokens. When provided, FastMCP uses your custom verifier instead of creating a default JWTVerifier.Cannot be used with algorithm or required_scopes parameters - configure these on your verifier instead. The verifier’s required_scopes are automatically loaded and advertised.JWT algorithm to use for token verification (e.g., “ES256”). Defaults to
RS256. Only used when token_verifier is not provided.List of OAuth scopes for token validation. These are automatically
included in authorization requests. Only used when
token_verifier is not provided.New in version
3.0.1Verify the upstream OIDC id_token instead of the access token. Use this for
providers that issue opaque access tokens but standard JWT ID tokens. The
default verifier then checks the ID token’s audience against client_id, and
required_scopes is enforced on FastMCP-issued tokens instead of the upstream
token, since ID tokens carry no scope claim. The upstream access token is
still stored for calls to the provider’s APIs.Path for OAuth callbacks. Must match the redirect URI configured in your OAuth
application
List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g.,
"http://localhost:*", "https://*.example.com/*").None(default): DCR clients use registered redirect URIs, with loopback ports allowed to vary for MCP compatibility. Unsafe browser schemes such asjavascript:,data:,file:, andvbscript:are rejected.- Empty list
[]: No redirect URIs allowed - Custom list: Only matching patterns allowed
redirect_path.The complete set of scopes clients are allowed to request — the full set of
available scopes (a superset of
required_scopes). These are advertised to
clients through the /.well-known endpoints (as scopes_supported) and
enforced at Dynamic Client Registration: a client registering with a scope
outside this set is rejected. Defaults to required_scopes from your token
verifier if not specified.Token endpoint authentication method for the upstream OAuth server. Controls how the proxy authenticates when exchanging authorization codes and refresh tokens with the upstream provider.
"client_secret_basic": Send credentials in Authorization header (most common)"client_secret_post": Send credentials in request body (required by some providers)"none": No authentication (for public clients)None(default):"client_secret_basic"when a client secret is configured,"none"otherwise
New in version
2.13.0Secret used to sign FastMCP JWT tokens issued to clients. bytes are used as-is, with no stretching, so supply at least 32 bytes of high-entropy key material. With the default file-backed client storage, the bytes must also decode as UTF-8; use secrets.token_urlsafe(32).encode() instead of raw secrets.token_bytes(), or configure client_storage explicitly. A string is stretched into a 32-byte key with PBKDF2 (1,000,000 iterations), since a supplied string may be low-entropy.Default behavior (None):
The key is deterministically derived from client_secret using HKDF, on every platform. Because the derivation is deterministic, the same key is produced across restarts as long as client_secret doesn’t change, so tokens remain valid without any extra configuration. This convenience makes it only suitable for development and local testing.For production:
Provide an explicit jwt_signing_key (e.g., from an environment variable) rather than relying on the auto-derived key.New in version Production with encrypted Redis storage:
2.13.0Storage backend for persisting OAuth client registrations and upstream tokens.Default behavior:
Encrypted disk store in your platform’s data directory (derived from platformdirs), on every platform including Linux. The encryption key is itself derived from jwt_signing_key.By default, clients are automatically persisted to encrypted disk storage, allowing them to survive server restarts as long as the filesystem remains accessible. This means MCP clients only need to register once and can reconnect seamlessly.For production deployments with multiple servers or cloud deployments, use a network-accessible storage backend rather than local disk storage. Wrap your storage in FernetEncryptionWrapper to encrypt sensitive OAuth tokens at rest. See Storage Backends for available options.Testing with in-memory storage (unencrypted):Consent screen behavior for authorization requests. Accepts
True (default; always prompt — strongest protection), "remember" (silent consent on return visits via signed cookie, gated by Sec-Fetch-Site to block AS-in-the-middle attacks), "external" (same authorization path as False, but the warning is suppressed because the operator asserts that equivalent protections are enforced externally), or False (disable entirely; local/testing only). See the OAuthProxy documentation for full details on each mode and the security trade-offs.False and "external" disable FastMCP’s consent and browser-binding checks, reducing protection against confused deputy and AS-in-the-middle attacks unless equivalent checks are enforced elsewhere. FastMCP does not provide or verify external enforcement. "remember" is also weaker than the default True, since its cross-site detection is a browser heuristic.Content Security Policy for the consent page.Disabling or weakening this policy reduces browser protections against content injection unless your deployment supplies an equivalent CSP header; FastMCP does not verify that header.
None(default): Uses the built-in CSP policy with appropriate directives for form submission- Empty string
"": Disables CSP entirely (no meta tag rendered) - Custom string: Uses the provided value as the CSP policy
OIDCProxy also accepts issuer_url, forward_resource, extra_authorize_params, extra_token_params, the token expiry options, and identity_assertion, with the same meaning as on OAuthProxy. When you set audience, it is added to both the authorization and token requests; an audience key in extra_authorize_params or extra_token_params takes precedence.
Using Built-in Providers
FastMCP includes pre-configured OIDC providers for common services:Auth0Provider, AWSCognitoProvider, and OCIProvider.
Scope Configuration
OAuth scopes are configured withrequired_scopes to automatically request the permissions your application needs.
Dynamic clients created by the proxy will automatically include these scopes in their authorization requests.
CIMD Support
New in version3.0.0
The OIDC proxy inherits full CIMD (Client ID Metadata Document) support from OAuthProxy. Clients can use HTTPS URLs as their client_id instead of registering dynamically, and the proxy will fetch and validate their metadata document.
See the OAuth Proxy CIMD documentation for complete details on how CIMD works, including private key JWT authentication and security considerations.
The CIMD-related parameters available on OIDCProxy are: