ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-23 14:04:18 +02:00
Code Issues Projects Releases Packages Wiki Activity

OAuth proxy PKCE forwarding (#1733)

Browse source
This commit is contained in:
Jeremiah Lowin 2025-09-03 12:11:38 -04:00 • committed by GitHub
commit 1045eb47c2
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 375 additions and 240 deletions
Download patch file Download diff file Expand all files Collapse all files

423
docs/servers/auth/oauth-proxy.mdx
View file

@ -1,123 +1,84 @@
---
title: OAuth Proxy
sidebarTitle: OAuth Proxy
description: Enable authentication with OAuth providers that don't support Dynamic Client Registration.
description: Bridge traditional OAuth providers to work seamlessly with MCP's authentication flow.
icon: share
tag: NEW
---
import { VersionBadge } from "/snippets/version-badge.mdx"
import { VersionBadge } from "/snippets/version-badge.mdx";
<VersionBadge version="2.12.0" />
OAuth Proxy enables your FastMCP server to authenticate with OAuth providers that **don't support Dynamic Client Registration (DCR)**. This includes virtually all traditional OAuth providers: GitHub, Google, Azure, Facebook, Discord, and most enterprise identity systems.
OAuth Proxy enables FastMCP servers to authenticate with OAuth providers that **don't support Dynamic Client Registration (DCR)**. This includes virtually all traditional OAuth providers: GitHub, Google, Azure, Discord, Facebook, and most enterprise identity systems. For providers that do support DCR (like WorkOS AuthKit), use [`RemoteAuthProvider`](/servers/auth/remote-oauth) instead.
While MCP clients expect to dynamically register and obtain credentials, these providers require manual app registration through their developer consoles. OAuth Proxy bridges this gap by presenting a DCR-compliant interface to MCP clients while using your pre-registered credentials with the upstream provider.
MCP clients expect to register automatically and obtain credentials on the fly, but traditional providers require manual app registration through their developer consoles. OAuth Proxy bridges this gap by presenting a DCR-compliant interface to MCP clients while using your pre-registered credentials with the upstream provider. When a client attempts to register, the proxy returns your fixed credentials. When a client initiates authorization, the proxy handles the complexity of callback forwarding—storing the client's dynamic callback URL, using its own fixed callback with the provider, then forwarding back to the client after token exchange.
<Tip>
**When to use OAuth Proxy vs RemoteAuthProvider:**
- **OAuth Proxy**: For providers WITHOUT Dynamic Client Registration (GitHub, Google, Azure, etc.)
- **RemoteAuthProvider**: For providers WITH Dynamic Client Registration (WorkOS AuthKit, etc.)
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.
OAuth Proxy makes traditional OAuth providers work seamlessly with MCP's automated authentication flow.
</Tip>
## Implementation
## DCR vs Non-DCR Providers
### Provider Setup Requirements
The key distinction in MCP authentication is whether your OAuth provider supports **Dynamic Client Registration (DCR)**:
Before using OAuth Proxy, you need to register your application with your OAuth provider:
- **Providers WITH DCR** (WorkOS, some OIDC providers): Use [`RemoteAuthProvider`](/servers/auth/remote-oauth)
- Clients can register themselves automatically
- No manual app registration needed
- True dynamic authentication flow
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`
- 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
4. **Note the OAuth endpoints**: Authorization URL and Token URL (usually found in the provider's OAuth documentation)
- **Providers WITHOUT DCR** (GitHub, Google, Azure, Discord, etc.): Use `OAuthProxy` (this guide)
- Requires manual app registration in provider's console
- You obtain fixed client ID and secret
- OAuth Proxy bridges the gap for MCP compatibility
<Warning>
The redirect URI you configure with your provider must exactly match your
FastMCP server's URL plus the callback path. If you customize `redirect_path`
in OAuth Proxy, update your provider's redirect URI accordingly.
</Warning>
OAuth Proxy makes non-DCR providers work seamlessly with MCP by implementing a local DCR interface that always returns your pre-registered credentials.
### Basic Setup
## Understanding the DCR Gap
Here's how to implement OAuth Proxy with any provider:
**Dynamic Client Registration (DCR)** allows OAuth clients to automatically register themselves with an authorization server and obtain credentials without manual intervention. The MCP specification is designed around this capability, expecting clients to register dynamically.
```python
from fastmcp import FastMCP
from fastmcp.server.auth import OAuthProxy
from fastmcp.server.auth.providers.jwt import JWTVerifier
However, most OAuth providers don't support DCR:
# Configure token verification for your provider
# See the Token Verification guide for provider-specific setups
token_verifier = JWTVerifier(
jwks_uri="https://your-provider.com/.well-known/jwks.json",
issuer="https://your-provider.com",
audience="your-app-id"
)
| Provider Type | DCR Support | Registration Method | Examples |
|--------------|-------------|--------------------|-----------|
| Modern Auth Platforms | ✅ Yes | Automatic via API | WorkOS AuthKit, Some OIDC providers |
| Traditional OAuth | ❌ No | Manual via console | GitHub, Google, Azure, Discord, Facebook |
| Enterprise SSO | ❌ No | IT Administrator | Okta, AD FS, PingIdentity |
# Create the OAuth proxy
auth = OAuthProxy(
# Provider's OAuth endpoints (from their documentation)
upstream_authorization_endpoint="https://provider.com/oauth/authorize",
upstream_token_endpoint="https://provider.com/oauth/token",
Providers without DCR require you to:
- Manually register applications through their developer console
- Obtain fixed client IDs and secrets that never change
- Pre-configure specific redirect URIs
- Manage credentials through their web interface
# Your registered app credentials
upstream_client_id="your-client-id",
upstream_client_secret="your-client-secret",
This creates a fundamental incompatibility: MCP clients expect to call a registration endpoint and receive credentials, but traditional providers only work with pre-registered apps. OAuth Proxy solves this by accepting any client registration request and returning your fixed upstream credentials.
# Token validation (see Token Verification guide)
token_verifier=token_verifier,
## How OAuth Proxy Works
The OAuth Proxy implements an intelligent callback forwarding pattern that solves both the DCR problem and the redirect URI mismatch issue:
```mermaid
sequenceDiagram
participant Client as MCP Client<br/>(localhost:random)
participant Proxy as FastMCP OAuth Proxy<br/>(server:8000)
participant Provider as OAuth Provider<br/>(GitHub, etc.)
Note over Client, Proxy: Dynamic Registration (Local)
Client->>Proxy: 1. POST /register<br/>redirect_uri: localhost:54321/callback
Proxy-->>Client: 2. Returns fixed upstream credentials
Note over Client, Proxy: Authorization with Callback Forwarding
Client->>Proxy: 3. GET /authorize<br/>redirect_uri=localhost:54321/callback
Note over Proxy: Store transaction with client callback
Proxy->>Provider: 4. Redirect to provider<br/>redirect_uri=server:8000/auth/callback
# Your FastMCP server's public URL
base_url="https://your-server.com",
Note over Provider, Proxy: Provider Callback
Provider->>Proxy: 5. GET /auth/callback<br/>with authorization code
Proxy->>Provider: 6. Exchange code for tokens
Provider-->>Proxy: 7. Access & refresh tokens
Note over Proxy, Client: Client Callback Forwarding
Proxy->>Client: 8. Redirect to localhost:54321/callback<br/>with new authorization code
Note over Client, Proxy: Token Exchange
Client->>Proxy: 9. POST /token with code
Proxy-->>Client: 10. Returns stored provider tokens
# Optional: customize the callback path (default is "/auth/callback")
# redirect_path="/custom/callback",
)
mcp = FastMCP(name="My Server", auth=auth)
```
### The Callback Forwarding Pattern
### Configuration Parameters
OAuth Proxy implements an innovative callback forwarding pattern that solves the redirect URI mismatch problem:
**The Challenge:**
- MCP clients listen on random localhost ports (e.g., `http://localhost:54321/callback`)
- Each client session uses a different port
- OAuth providers only accept pre-registered, fixed redirect URIs
- Registering every possible localhost port is impossible
**The Solution:**
The proxy acts as an intermediary callback handler:
1. **Dynamic Registration**: Client provides its localhost callback URL during registration
2. **Transaction Tracking**: Proxy stores the client's callback URL with a transaction ID
3. **Fixed Provider Callback**: Proxy uses its own fixed callback URL with the provider
4. **Server-Side Token Exchange**: Proxy receives the provider's callback and exchanges the authorization code for tokens
5. **Client Forwarding**: Proxy redirects to the client's original localhost callback with a new authorization code
6. **Token Delivery**: Client exchanges this new code with the proxy to receive the provider's tokens
This pattern maintains full OAuth 2.1 security (including PKCE) while enabling dynamic client ports to work with fixed provider callbacks. The client never knows it's talking to a proxy - it experiences a standard DCR flow.
## Basic Implementation
The `OAuthProxy` class provides the complete proxy implementation:
<Card icon="code" title="OAuthProxy Constructor Parameters">
<Card icon="code" title="OAuthProxy Parameters">
<ParamField body="upstream_authorization_endpoint" type="str" required>
URL of your OAuth provider's authorization endpoint (e.g., `https://github.com/login/oauth/authorize`)
</ParamField>
@ -158,216 +119,194 @@ The `OAuthProxy` class provides the complete proxy implementation:
Optional URL to your service documentation
</ParamField>
<ParamField body="forward_pkce" type="bool" default="True">
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
</ParamField>
<ParamField body="allowed_client_redirect_uris" type="list[str] | None">
List of allowed redirect URI patterns for MCP clients. Patterns support wildcards (e.g., `"http://localhost:*"`, `"https://*.example.com/*"`).
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.
</ParamField>
<ParamField body="valid_scopes" type="list[str] | None">
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.
</ParamField>
</Card>
### Dynamic client scope
### Using Built-in Providers
When `OAuthProxy` creates a dynamic client (`ProxyDCRClient`) during registration or for temporary/unregistered access, it sets the client's `scope` string from your `TokenVerifier.required_scopes` (joined with spaces). If `required_scopes` is empty or `None`, the client's `scope` will be an empty string.
FastMCP includes pre-configured providers for common services:
```python
from fastmcp.server.auth.providers.jwt import JWTVerifier
from fastmcp.server.auth.oauth_proxy import OAuthProxy
token_verifier = JWTVerifier(
jwks_uri="https://provider/.well-known/jwks.json",
issuer="https://provider",
audience="my-app",
)
token_verifier.required_scopes = ["read", "write"]
auth = OAuthProxy(
upstream_authorization_endpoint="https://provider/authorize",
upstream_token_endpoint="https://provider/token",
upstream_client_id="cid",
upstream_client_secret="secret",
token_verifier=token_verifier,
base_url="https://your-server.com",
)
# Any dynamic client created by the proxy will have scope "read write"
```
```python
from fastmcp import FastMCP
from fastmcp.server.auth import OAuthProxy
from fastmcp.server.auth.providers.jwt import JWTVerifier
# Configure token validation for your provider
token_verifier = JWTVerifier(
jwks_uri="https://your-provider.com/.well-known/jwks.json",
issuer="https://your-provider.com",
audience="your-app-id"
)
# Create the OAuth proxy (accepts strings for URLs)
auth = OAuthProxy(
# Upstream provider endpoints
upstream_authorization_endpoint="https://your-provider.com/oauth/authorize",
upstream_token_endpoint="https://your-provider.com/oauth/token",
# Your registered app credentials
upstream_client_id="your-registered-client-id",
upstream_client_secret="your-registered-client-secret",
# Token validation
token_verifier=token_verifier,
# Your FastMCP server URL (string automatically converted to AnyHttpUrl)
base_url="https://your-server.com",
# Optional: customize callback path (defaults to "/auth/callback")
redirect_path="/auth/callback",
from fastmcp.server.auth.providers.github import GitHubProvider
auth = GitHubProvider(
client_id="your-github-app-id",
client_secret="your-github-app-secret",
base_url="https://your-server.com"
)
mcp = FastMCP(name="My Server", auth=auth)
```
### OAuth Provider Configuration
Available providers include `GitHubProvider`, `GoogleProvider`, and others. These handle token verification automatically.
When registering your application with your OAuth provider, configure the redirect/callback URL as:
### Scope Configuration
```
https://your-server.com/auth/callback
```
For local development with providers that support it (like GitHub):
```
http://localhost:8000/auth/callback
```
The proxy automatically:
- Implements DCR by returning your fixed credentials to any client that registers
- Handles callback forwarding between dynamic client callbacks and your fixed provider callback
- Exchanges authorization codes server-side for enhanced security
- Validates tokens using your provider's public keys or API
- Maintains PKCE security throughout the flow
## Client Redirect URI Security
<Note>
OAuth Proxy accepts all redirect URIs by default to maintain compatibility with MCP's Dynamic Client Registration (DCR) pattern, where clients register with unpredictable redirect URIs.
If you know which clients will connect, you can restrict redirect URIs using the `allowed_client_redirect_uris` parameter:
OAuth scopes are configured through your `TokenVerifier`. Set `required_scopes` to automatically request the permissions your application needs:
```python
# Default: allow all (for DCR compatibility)
auth = OAuthProxy(...)
JWTVerifier(..., required_scopes = ["read:user", "write:data"])
```
# Restrict to localhost only
Dynamic clients created by the proxy will automatically include these scopes in their authorization requests.
## How It Works
```mermaid
sequenceDiagram
participant Client as MCP Client<br/>(localhost:random)
participant Proxy as FastMCP OAuth Proxy<br/>(server:8000)
participant Provider as OAuth Provider<br/>(GitHub, etc.)
Note over Client, Proxy: Dynamic Registration (Local)
Client->>Proxy: 1. POST /register<br/>redirect_uri: localhost:54321/callback
Proxy-->>Client: 2. Returns fixed upstream credentials
Note over Client, Proxy: Authorization with PKCE & Callback Forwarding
Client->>Proxy: 3. GET /authorize<br/>redirect_uri=localhost:54321/callback<br/>code_challenge=CLIENT_CHALLENGE
Note over Proxy: Store transaction with client PKCE<br/>Generate proxy PKCE pair
Proxy->>Provider: 4. Redirect to provider<br/>redirect_uri=server:8000/auth/callback<br/>code_challenge=PROXY_CHALLENGE
Note over Provider, Proxy: Provider Callback
Provider->>Proxy: 5. GET /auth/callback<br/>with authorization code
Proxy->>Provider: 6. Exchange code for tokens<br/>code_verifier=PROXY_VERIFIER
Provider-->>Proxy: 7. Access & refresh tokens
Note over Proxy, Client: Client Callback Forwarding
Proxy->>Client: 8. Redirect to localhost:54321/callback<br/>with new authorization code
Note over Client, Proxy: Token Exchange
Client->>Proxy: 9. POST /token with code<br/>code_verifier=CLIENT_VERIFIER
Proxy-->>Client: 10. Returns stored provider tokens
```
The flow diagram above illustrates the complete OAuth Proxy pattern. Let's understand each phase:
### Registration Phase
When an MCP client calls `/register` with its dynamic callback URL, the proxy responds with your pre-configured upstream credentials. The client stores these credentials believing it has registered a new app. Meanwhile, the proxy records the client's callback URL for later use.
### Authorization Phase
The client initiates OAuth by redirecting to the proxy's `/authorize` endpoint. The proxy:
1. Stores the client's transaction with its PKCE challenge
2. Generates its own PKCE parameters for upstream security
3. Redirects to the upstream provider using the fixed callback URL
This dual-PKCE approach maintains end-to-end security at both the client-to-proxy and proxy-to-provider layers.
### Callback Phase
After user authorization, the provider redirects back to the proxy's fixed callback URL. The proxy:
1. Exchanges the authorization code for tokens with the provider
2. Stores these tokens temporarily
3. Generates a new authorization code for the client
4. Redirects to the client's original dynamic callback URL
### Token Exchange Phase
Finally, the client exchanges its authorization code with the proxy to receive the provider's tokens. The proxy validates the client's PKCE verifier before returning the stored tokens.
This entire flow is transparent to the MCP client—it experiences a standard OAuth flow with dynamic registration, unaware that a proxy is managing the complexity behind the scenes.
### PKCE Forwarding
OAuth Proxy automatically handles PKCE (Proof Key for Code Exchange) when working with providers that support or require it. The proxy generates its own PKCE parameters to send upstream while separately validating the client's PKCE, ensuring end-to-end security at both layers.
This is enabled by default via the `forward_pkce` parameter and works seamlessly with providers like Google, Azure AD, and GitHub. Only disable it for legacy providers that don't support PKCE:
```python
# Disable PKCE forwarding only if upstream doesn't support it
auth = OAuthProxy(
...,
forward_pkce=False # Default is True
)
```
### Redirect URI Validation
While OAuth Proxy accepts all redirect URIs by default (for DCR compatibility), you can restrict which clients can connect by specifying allowed patterns:
```python
# Allow only localhost clients (common for development)
auth = OAuthProxy(
# ... other parameters ...
allowed_client_redirect_uris=[
"http://localhost:*",
"http://127.0.0.1:*"
]
)
# Allow specific known clients (e.g., Claude.ai)
# Allow specific known clients
auth = OAuthProxy(
...,
# ... other parameters ...
allowed_client_redirect_uris=[
"http://localhost:*",
"https://claude.ai/api/mcp/auth_callback"
]
)
# Custom patterns with wildcards
auth = OAuthProxy(
...,
allowed_client_redirect_uris=[
"http://localhost:*",
"https://*.example.com/auth/*"
"https://claude.ai/api/mcp/auth_callback",
"https://*.mycompany.com/auth/*" # Wildcard patterns supported
]
)
```
**Tip:** Check your server logs for debug messages that say "Client registered with redirect_uri" messages to see what redirect URIs your clients are using.
</Note>
Check your server logs for "Client registered with redirect_uri" messages to identify what URLs your clients use.
## Client Compatibility
## Token Verification
<Tip>
The OAuth Proxy's callback forwarding enables **any MCP client** to authenticate with **any OAuth provider**, regardless of redirect URI restrictions. Clients can use dynamic localhost ports while providers see their expected fixed callbacks.
</Tip>
OAuth Proxy requires a compatible `TokenVerifier` to validate tokens from your provider. Different providers use different token formats:
This breakthrough means that MCP clients no longer need to worry about registering specific callback URLs with OAuth providers. The proxy handles the complexity of bridging dynamic client callbacks with the fixed URLs that providers require. The entire flow maintains OAuth 2.1 and PKCE (RFC-7636) compliance for security.
- **JWT tokens** (Google, Azure): Use `JWTVerifier` with the provider's JWKS endpoint
- **Opaque tokens** (GitHub, Discord): Use provider-specific verifiers or implement custom validation
## Token Verification Strategies
Different OAuth providers use different token formats, requiring appropriate verification strategies:
### Provider Token Types
| Provider | Token Type | Verification Method | Built-in Support |
|----------|-----------|--------------------|-----------------|
| GitHub | Opaque | API validation (`/user` endpoint) | ✅ `GitHubProvider` |
| Google | JWT | JWKS signature verification | ✅ `GoogleProvider` |
| Azure AD | JWT | JWKS signature verification | Configure `JWTVerifier` |
| Discord | Opaque | API validation | ✅ `DiscordOAuthProxyProvider` |
| Custom | Varies | Implement `TokenVerifier` | Extend base class |
### Using Built-in Providers
FastMCP includes pre-configured providers that handle token verification automatically:
```python
from fastmcp.server.auth.providers.github import GitHubProvider
# GitHub provider with automatic API-based token validation
auth = GitHubProvider(
client_id="your-github-client-id",
client_secret="your-github-client-secret",
base_url="https://your-server.com"
)
```
### Custom Token Verification
For providers without built-in support, implement a [`TokenVerifier`](/servers/auth/token-verification):
- **JWT tokens**: Use `JWTVerifier` with the provider's JWKS endpoint
- **Opaque tokens**: Extend `TokenVerifier` to validate via the provider's API
- **Hybrid approaches**: Combine multiple verification methods as needed
See the [Token Verification guide](/servers/auth/token-verification) for detailed setup instructions for your provider.
## Environment Configuration
<VersionBadge version="2.12.1" />
OAuth Proxy-based providers support environment-based configuration for production deployments. Use the specific provider implementations rather than the base OAuth Proxy class:
For production deployments, configure OAuth Proxy through environment variables instead of hardcoding credentials:
```bash
# Use a specific provider implementation
# Specify the provider implementation
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
# or
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
# or your custom OAuth Proxy implementation
export FASTMCP_SERVER_AUTH=mycompany.auth.CustomOAuthProvider
# Provider-specific configuration (example for GitHub)
# Provider-specific credentials
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="abc123..."
export FASTMCP_SERVER_AUTH_GITHUB_BASE_URL="https://your-server.com"
export FASTMCP_SERVER_AUTH_GITHUB_BASE_URL="https://your-production-server.com"
```
For custom OAuth Proxy implementations, configure the environment variables based on your provider's settings class.
With environment variables configured, your code becomes:
With environment configuration, your server code simplifies to:
```python
from fastmcp import FastMCP
# Authentication automatically configured from environment
mcp = FastMCP(name="My Server")
```
@mcp.tool
def protected_tool(data: str) -> str:
"""This tool is now protected by OAuth."""
return f"Processed: {data}"
if __name__ == "__main__":
mcp.run(transport="http", port=8000)
```

93
src/fastmcp/server/auth/oauth_proxy.py
View file

@ -18,12 +18,15 @@ production use with enterprise identity providers.
from __future__ import annotations
import hashlib
import secrets
import time
from base64 import urlsafe_b64encode
from typing import TYPE_CHECKING, Any, Final
from urllib.parse import urlencode
import httpx
from authlib.common.security import generate_token
from authlib.integrations.httpx_client import AsyncOAuth2Client
from mcp.server.auth.provider import (
AccessToken,
@ -243,6 +246,8 @@ class OAuthProxy(OAuthProvider):
# Client redirect URI validation
allowed_client_redirect_uris: list[str] | None = None,
valid_scopes: list[str] | None = None,
# PKCE configuration
forward_pkce: bool = True,
):
"""Initialize the OAuth proxy provider.
@ -264,7 +269,10 @@ class OAuthProxy(OAuthProvider):
If empty list, all redirect URIs are allowed (not recommended for production).
These are for MCP clients performing loopback redirects, NOT for the upstream OAuth app.
valid_scopes: List of all the possible valid scopes for a client.
These are advertised to clients through the `/.well-known` endpoints. Defaults to `reuqired_scopes` if not provided.
These are advertised to clients through the `/.well-known` endpoints. Defaults to `required_scopes` if not provided.
forward_pkce: Whether to forward PKCE to upstream server (default True).
Enable for providers that support/require PKCE (Google, Azure, etc.).
Disable only if upstream provider doesn't support PKCE.
"""
# Always enable DCR since we implement it locally for MCP clients
client_registration_options = ClientRegistrationOptions(
@ -300,6 +308,9 @@ class OAuthProxy(OAuthProvider):
)
self._allowed_client_redirect_uris = allowed_client_redirect_uris
# PKCE configuration
self._forward_pkce = forward_pkce
# Local state for DCR and token bookkeeping
self._clients: dict[str, OAuthClientInformationFull] = {}
self._access_tokens: dict[str, AccessToken] = {}
@ -323,6 +334,25 @@ class OAuthProxy(OAuthProvider):
self._upstream_authorization_endpoint,
)
# -------------------------------------------------------------------------
# PKCE Helper Methods
# -------------------------------------------------------------------------
def _generate_pkce_pair(self) -> tuple[str, str]:
"""Generate PKCE code verifier and challenge pair.
Returns:
Tuple of (code_verifier, code_challenge) using S256 method
"""
# Generate code verifier: 43-128 characters from unreserved set
code_verifier = generate_token(48)
# Generate code challenge using S256 (SHA256 + base64url)
challenge_bytes = hashlib.sha256(code_verifier.encode()).digest()
code_challenge = urlsafe_b64encode(challenge_bytes).decode().rstrip("=")
return code_verifier, code_challenge
# -------------------------------------------------------------------------
# Client Registration (Local Implementation)
# -------------------------------------------------------------------------
@ -389,14 +419,25 @@ class OAuthProxy(OAuthProvider):
This implements the DCR-compliant proxy pattern:
1. Store transaction with client details and PKCE challenge
2. Use transaction ID as state for IdP
3. Redirect to IdP with our fixed callback URL
2. Generate proxy's own PKCE parameters if forwarding is enabled
3. Use transaction ID as state for IdP
4. Redirect to IdP with our fixed callback URL and proxy's PKCE
"""
# Generate transaction ID for this authorization request
txn_id = secrets.token_urlsafe(32)
# Generate proxy's own PKCE parameters if forwarding is enabled
proxy_code_verifier = None
proxy_code_challenge = None
if self._forward_pkce and params.code_challenge:
proxy_code_verifier, proxy_code_challenge = self._generate_pkce_pair()
logger.debug(
"Generated proxy PKCE for transaction %s (forwarding client PKCE to upstream)",
txn_id,
)
# Store transaction data for IdP callback processing
self._oauth_transactions[txn_id] = {
transaction_data = {
"client_id": client.client_id,
"client_redirect_uri": str(params.redirect_uri),
"client_state": params.state,
@ -406,6 +447,12 @@ class OAuthProxy(OAuthProvider):
"created_at": time.time(),
}
# Store proxy's PKCE verifier if we're forwarding
if proxy_code_verifier:
transaction_data["proxy_code_verifier"] = proxy_code_verifier
self._oauth_transactions[txn_id] = transaction_data
# Build query parameters for upstream IdP authorization request
# Use our fixed IdP callback and transaction ID as state
query_params: dict[str, Any] = {
@ -421,14 +468,24 @@ class OAuthProxy(OAuthProvider):
if scopes_to_use:
query_params["scope"] = " ".join(scopes_to_use)
# Forward proxy's PKCE challenge to upstream if enabled
if proxy_code_challenge:
query_params["code_challenge"] = proxy_code_challenge
query_params["code_challenge_method"] = "S256"
logger.debug(
"Forwarding proxy PKCE challenge to upstream for transaction %s",
txn_id,
)
# Build the upstream authorization URL
separator = "&" if "?" in self._upstream_authorization_endpoint else "?"
upstream_url = f"{self._upstream_authorization_endpoint}{separator}{urlencode(query_params)}"
logger.debug(
"Starting OAuth transaction %s for client %s, redirecting to IdP",
"Starting OAuth transaction %s for client %s, redirecting to IdP (PKCE forwarding: %s)",
txn_id,
client.client_id,
"enabled" if proxy_code_challenge else "disabled",
)
return upstream_url
@ -803,14 +860,28 @@ class OAuthProxy(OAuthProvider):
f"Exchanging IdP code for tokens with redirect_uri: {idp_redirect_uri}"
)
idp_tokens: dict[str, Any] = await oauth_client.fetch_token( # type: ignore[misc]
url=self._upstream_token_endpoint,
code=idp_code,
redirect_uri=idp_redirect_uri,
)
# Include proxy's code_verifier if we forwarded PKCE
proxy_code_verifier = transaction.get("proxy_code_verifier")
if proxy_code_verifier:
logger.debug(
"Including proxy code_verifier in token exchange for transaction %s",
txn_id,
)
idp_tokens: dict[str, Any] = await oauth_client.fetch_token( # type: ignore[misc]
url=self._upstream_token_endpoint,
code=idp_code,
redirect_uri=idp_redirect_uri,
code_verifier=proxy_code_verifier,
)
else:
idp_tokens: dict[str, Any] = await oauth_client.fetch_token( # type: ignore[misc]
url=self._upstream_token_endpoint,
code=idp_code,
redirect_uri=idp_redirect_uri,
)
logger.debug(
f"Successfully exchanged IdP code for tokens (transaction: {txn_id})"
f"Successfully exchanged IdP code for tokens (transaction: {txn_id}, PKCE: {bool(proxy_code_verifier)})"
)
except Exception as e:

125
tests/server/auth/test_oauth_proxy.py
View file

@ -594,3 +594,128 @@ class TestOAuthProxyComprehensive:
# Verify code was cleaned up
assert code not in oauth_proxy._client_codes
class TestOAuthProxyPKCE:
"""Test suite for OAuth Proxy PKCE forwarding functionality."""
@pytest.fixture
def jwt_verifier(self):
"""Create a mock JWT verifier for testing."""
verifier = Mock()
verifier.required_scopes = ["read", "write"]
return verifier
@pytest.fixture
def oauth_proxy_with_pkce(self, jwt_verifier):
"""Create an OAuthProxy instance with PKCE forwarding enabled."""
return OAuthProxy(
upstream_authorization_endpoint="https://oauth.example.com/authorize",
upstream_token_endpoint="https://oauth.example.com/token",
upstream_client_id="upstream-client",
upstream_client_secret="upstream-secret",
token_verifier=jwt_verifier,
base_url="https://proxy.example.com",
forward_pkce=True, # Enable PKCE forwarding
)
@pytest.fixture
def oauth_proxy_without_pkce(self, jwt_verifier):
"""Create an OAuthProxy instance with PKCE forwarding disabled."""
return OAuthProxy(
upstream_authorization_endpoint="https://oauth.example.com/authorize",
upstream_token_endpoint="https://oauth.example.com/token",
upstream_client_id="upstream-client",
upstream_client_secret="upstream-secret",
token_verifier=jwt_verifier,
base_url="https://proxy.example.com",
forward_pkce=False, # Disable PKCE forwarding
)
async def test_pkce_forwarding_enabled(self, oauth_proxy_with_pkce):
"""Test that proxy generates and forwards its own PKCE when client uses PKCE."""
client = OAuthClientInformationFull(
client_id="test-client",
client_secret="test-secret",
redirect_uris=[AnyUrl("http://localhost:12345/callback")],
)
params = AuthorizationParams(
redirect_uri=AnyUrl("http://localhost:12345/callback"),
redirect_uri_provided_explicitly=True,
state="client-state",
code_challenge="client_challenge_value",
code_challenge_method="S256",
scopes=["read"],
)
redirect_url = await oauth_proxy_with_pkce.authorize(client, params)
query_params = parse_qs(urlparse(redirect_url).query)
# Verify proxy forwards its own PKCE challenge
assert "code_challenge" in query_params
assert query_params["code_challenge"][0] != "client_challenge_value"
assert query_params["code_challenge_method"] == ["S256"]
# Verify transaction stores both client and proxy PKCE
txn_id = query_params["state"][0]
transaction = oauth_proxy_with_pkce._oauth_transactions[txn_id]
assert transaction["code_challenge"] == "client_challenge_value" # Client's
assert "proxy_code_verifier" in transaction # Proxy's verifier stored
async def test_pkce_forwarding_disabled(self, oauth_proxy_without_pkce):
"""Test that PKCE is not forwarded when forward_pkce=False."""
client = OAuthClientInformationFull(
client_id="test-client",
client_secret="test-secret",
redirect_uris=[AnyUrl("http://localhost:12345/callback")],
)
params = AuthorizationParams(
redirect_uri=AnyUrl("http://localhost:12345/callback"),
redirect_uri_provided_explicitly=True,
state="client-state",
code_challenge="client_challenge_value",
scopes=["read"],
)
redirect_url = await oauth_proxy_without_pkce.authorize(client, params)
query_params = parse_qs(urlparse(redirect_url).query)
# Verify NO PKCE parameters forwarded to upstream
assert "code_challenge" not in query_params
assert "code_challenge_method" not in query_params
# But client's PKCE is still stored for validation
txn_id = query_params["state"][0]
transaction = oauth_proxy_without_pkce._oauth_transactions[txn_id]
assert transaction["code_challenge"] == "client_challenge_value"
assert "proxy_code_verifier" not in transaction
async def test_no_pkce_when_client_has_none(self, oauth_proxy_with_pkce):
"""Test that proxy doesn't generate PKCE if client doesn't use it."""
client = OAuthClientInformationFull(
client_id="test-client",
client_secret="test-secret",
redirect_uris=[AnyUrl("http://localhost:12345/callback")],
)
params = AuthorizationParams(
redirect_uri=AnyUrl("http://localhost:12345/callback"),
redirect_uri_provided_explicitly=True,
state="client-state",
code_challenge="", # Empty string means no PKCE
scopes=["read"],
)
redirect_url = await oauth_proxy_with_pkce.authorize(client, params)
query_params = parse_qs(urlparse(redirect_url).query)
# Verify NO PKCE forwarded
assert "code_challenge" not in query_params
assert "code_challenge_method" not in query_params
# No proxy verifier stored
txn_id = query_params["state"][0]
transaction = oauth_proxy_with_pkce._oauth_transactions[txn_id]
assert "proxy_code_verifier" not in transaction