From b3ea6ad384cdf83f858626b346f58cecb7bf0df2 Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Sun, 21 Sep 2025 11:02:36 -0400 Subject: [PATCH] docs: update OAuth and OIDC proxy documentation (#1880) --- docs/servers/auth/oauth-proxy.mdx | 93 +++++++++++++++++++------------ docs/servers/auth/oidc-proxy.mdx | 45 ++++++++++----- 2 files changed, 89 insertions(+), 49 deletions(-) diff --git a/docs/servers/auth/oauth-proxy.mdx b/docs/servers/auth/oauth-proxy.mdx index d532a8108..1922b199f 100644 --- a/docs/servers/auth/oauth-proxy.mdx +++ b/docs/servers/auth/oauth-proxy.mdx @@ -16,6 +16,14 @@ MCP clients expect to register automatically and obtain credentials on the fly, This approach enables any MCP client (whether using random localhost ports or fixed URLs like Claude.ai) to authenticate with any traditional OAuth provider, all while maintaining full OAuth 2.1 and PKCE security. + + For providers that support OIDC discovery (Auth0, Google with OIDC + configuration, Azure AD), consider using [`OIDC + Proxy`](/servers/auth/oidc-proxy) for automatic configuration. OIDC Proxy + extends OAuth Proxy to automatically discover endpoints from the provider's + `/.well-known/openid-configuration` URL, simplifying setup. + + ## Implementation ### Provider Setup Requirements @@ -24,7 +32,7 @@ Before using OAuth Proxy, you need to register your application with your OAuth 1. **Register your application** in the provider's developer console (GitHub Settings, Google Cloud Console, Azure Portal, etc.) 2. **Configure the redirect URI** as your FastMCP server URL plus your chosen callback path: - - Default: `https://your-server.com/auth/callback` + - Default: `https://your-server.com/auth/callback` - Custom: `https://your-server.com/your/custom/path` (if you set `redirect_path`) - Development: `http://localhost:8000/auth/callback` 3. **Obtain your credentials**: Client ID and Client Secret @@ -68,7 +76,7 @@ auth = OAuthProxy( # Your FastMCP server's public URL base_url="https://your-server.com", - + # Optional: customize the callback path (default is "/auth/callback") # redirect_path="/custom/callback", ) @@ -84,7 +92,8 @@ mcp = FastMCP(name="My Server", auth=auth) - URL of your OAuth provider's token endpoint (e.g., `https://github.com/login/oauth/access_token`) + URL of your OAuth provider's token endpoint (e.g., + `https://github.com/login/oauth/access_token`) @@ -96,7 +105,8 @@ mcp = FastMCP(name="My Server", auth=auth) - A [`TokenVerifier`](/servers/auth/token-verification) instance to validate the provider's tokens + A [`TokenVerifier`](/servers/auth/token-verification) instance to validate the + provider's tokens @@ -104,7 +114,8 @@ mcp = FastMCP(name="My Server", auth=auth) - Path for OAuth callbacks. Must match the redirect URI configured in your OAuth application + Path for OAuth callbacks. Must match the redirect URI configured in your OAuth + application @@ -120,32 +131,39 @@ mcp = FastMCP(name="My Server", auth=auth) - Whether to forward PKCE (Proof Key for Code Exchange) to the upstream OAuth provider. When enabled and the client uses PKCE, the proxy generates its own PKCE parameters to send upstream while separately validating the client's PKCE. This ensures end-to-end PKCE security at both layers (client-to-proxy and proxy-to-upstream). - - `True` (default): Forward PKCE for providers that support it (Google, Azure, GitHub, etc.) - - `False`: Disable only if upstream provider doesn't support PKCE + Whether to forward PKCE (Proof Key for Code Exchange) to the upstream OAuth + provider. When enabled and the client uses PKCE, the proxy generates its own + PKCE parameters to send upstream while separately validating the client's + PKCE. This ensures end-to-end PKCE security at both layers (client-to-proxy + and proxy-to-upstream). - `True` (default): Forward PKCE for providers that + support it (Google, Azure, GitHub, etc.) - `False`: Disable only if upstream + provider doesn't support PKCE - 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): Uses authlib's default (typically `"client_secret_basic"`) - - Set this if your provider requires a specific authentication method and the default doesn't work. + 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): Uses authlib's default + (typically `"client_secret_basic"`) Set this if your provider requires a + specific authentication method and the default doesn't work. - List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`). - - `None` (default): All redirect URIs allowed (for MCP/DCR compatibility) - - Empty list `[]`: No redirect URIs allowed - - Custom list: Only matching patterns allowed - - These patterns apply to MCP client loopback redirects, NOT the upstream OAuth app redirect URI. + List of allowed redirect URI patterns for MCP clients. Patterns support + wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`). - + `None` (default): All redirect URIs allowed (for MCP/DCR compatibility) - + Empty list `[]`: No redirect URIs allowed - Custom list: Only matching + patterns allowed These patterns apply to MCP client loopback redirects, NOT + the upstream OAuth app redirect URI. - List of all possible valid scopes for the OAuth provider. These are advertised to clients through the `/.well-known` endpoints. Defaults to `required_scopes` from your TokenVerifier if not specified. + List of all possible valid scopes for the OAuth provider. These are advertised + to clients through the `/.well-known` endpoints. Defaults to `required_scopes` + from your TokenVerifier if not specified. @@ -162,23 +180,26 @@ mcp = FastMCP(name="My Server", auth=auth) Additional parameters to forward to the upstream token endpoint during code exchange and token refresh. Useful for provider-specific requirements during token operations. - For example, some providers require additional context during token exchange: - ```python - extra_token_params={"audience": "https://api.example.com"} - ``` +For example, some providers require additional context during token exchange: + +```python +extra_token_params={"audience": "https://api.example.com"} +``` + +These parameters are included in all token requests to the upstream provider. - These parameters are included in all token requests to the upstream provider. Storage backend for persisting OAuth client registrations. By default, clients are automatically persisted to disk in `~/.config/fastmcp/oauth-proxy-clients/`, 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 after your server restarts. - ```python - from fastmcp.utilities.storage import InMemoryStorage +```python +from fastmcp.utilities.storage import InMemoryStorage + +# Use in-memory storage for testing (clients lost on restart) +auth = OAuthProxy(..., client_storage=InMemoryStorage()) +``` - # Use in-memory storage for testing (clients lost on restart) - auth = OAuthProxy(..., client_storage=InMemoryStorage()) - ``` @@ -196,21 +217,21 @@ auth = OAuthProxy( upstream_token_endpoint="https://your-domain.auth0.com/oauth/token", upstream_client_id="your-auth0-client-id", upstream_client_secret="your-auth0-client-secret", - + # Auth0 requires audience for JWT tokens extra_authorize_params={ "audience": "https://your-api-identifier.com" }, extra_token_params={ - "audience": "https://your-api-identifier.com" + "audience": "https://your-api-identifier.com" }, - + token_verifier=JWTVerifier( jwks_uri="https://your-domain.auth0.com/.well-known/jwks.json", issuer="https://your-domain.auth0.com/", audience="https://your-api-identifier.com" ), - + base_url="https://your-server.com" ) ``` diff --git a/docs/servers/auth/oidc-proxy.mdx b/docs/servers/auth/oidc-proxy.mdx index 9b7b29ad7..86fac6821 100644 --- a/docs/servers/auth/oidc-proxy.mdx +++ b/docs/servers/auth/oidc-proxy.mdx @@ -79,28 +79,33 @@ mcp = FastMCP(name="My Server", auth=auth) Public URL of your FastMCP server (e.g., `https://your-server.com`) - - Strict flag for configuration validation + + Strict flag for configuration validation. When True, requires all OIDC + mandatory fields. - - Audience from your registered OAuth application + + Audience parameter for OIDC providers that require it (e.g., Auth0). This is + typically your API identifier. - - HTTP request timeout in seconds + + HTTP request timeout in seconds for fetching OIDC configuration - - The algorithm for the token verifier + + JWT algorithm to use for token verification (e.g., "RS256"). If not specified, + uses the provider's default. - - The required scopes for the token verifier + + List of OAuth scopes to request from the provider. These are automatically + included in authorization requests. - Path for OAuth callbacks. Must match the redirect URI configured in your OAuth application + Path for OAuth callbacks. Must match the redirect URI configured in your OAuth + application @@ -109,7 +114,8 @@ mcp = FastMCP(name="My Server", auth=auth) - Empty list `[]`: No redirect URIs allowed - Custom list: Only matching patterns allowed - These patterns apply to MCP client loopback redirects, NOT the upstream OAuth app redirect URI. +These patterns apply to MCP client loopback redirects, NOT the upstream OAuth app redirect URI. + @@ -119,7 +125,20 @@ mcp = FastMCP(name="My Server", auth=auth) - `"none"`: No authentication (for public clients) - `None` (default): Uses authlib's default (typically `"client_secret_basic"`) - Set this if your provider requires a specific authentication method and the default doesn't work. +Set this if your provider requires a specific authentication method and the default doesn't work. + + + + + Storage backend for persisting OAuth client registrations. By default, clients are automatically persisted to disk in `~/.config/fastmcp/oidc-proxy-clients/`, 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 after your server restarts. + +```python +from fastmcp.utilities.storage import InMemoryStorage + +# Use in-memory storage for testing (clients lost on restart) +auth = OIDCProxy(..., client_storage=InMemoryStorage()) +``` +