OAuth Proxy Features

The FastMCP OAuth Proxy enables MCP servers to authenticate with traditional OAuth providers that don't support Dynamic Client Registration (DCR). It acts as a transparent intermediary, presenting a DCR-compliant interface to MCP clients while managing pre-registered credentials with upstream providers.

Core Features

1. OAuth 2.1 Proxy Architecture

The proxy bridges the gap between:

MCP clients expecting RFC 7591 Dynamic Client Registration
Traditional OAuth providers (Google, GitHub, Azure, Auth0, etc.) requiring manual app registration

It transparently handles the entire OAuth flow while maintaining security and RFC compliance.

2. Dynamic Client Registration (DCR)

Implements RFC 7591 to provide DCR capabilities:

Accepts client registration requests
Returns fixed credentials (single pre-registered app)
Stores client callback URLs for OAuth redirects
No actual upstream registration required

3. Two-Tier PKCE Security

Enhanced security through dual PKCE validation:

Client-to-Proxy PKCE: Validates client's code verifier
Proxy-to-Upstream PKCE: Protects communication with OAuth provider
Supports both S256 (SHA-256) and plain challenge methods
Prevents authorization code interception attacks

4. User Consent Flow

Built-in consent screen prevents confused deputy attacks:

Shows clear authorization details and requested scopes
Signed consent cookies with HMAC-SHA256
Configurable 5-minute consent TTL
Can be disabled for trusted development environments
XSS-protected HTML rendering

5. Token Management

Flexible Storage Options

MemoryTokenStorage: Fast in-memory storage for development
DiskStore: Persistent filesystem storage with automatic cleanup
EncryptedTokenStorage: AES-256-GCM encryption wrapper
Custom storage backends via TokenStorage interface

Token Swap Pattern (Enhanced Security - Default Mode)

Enabled by default for enhanced security:

Issues short-lived FastMCP JWTs to clients (1 hour default)
Stores upstream provider tokens securely on the server
Maps JWT IDs (JTI) to upstream tokens
Supports automatic token refresh
Prevents token leakage to clients
Auto-generates JWT signing key if not provided

Passthrough Mode (Optional)

When token swap is disabled (enableTokenSwap: false):

Returns upstream provider tokens directly to clients
Simpler architecture for trusted environments
Client manages token lifecycle
Useful for debugging and development

6. JWT Token Issuance

Built-in JWT issuer for token swap pattern:

HMAC-SHA256 (HS256) signing
Configurable access token TTL (default: 1 hour)
Configurable refresh token TTL (default: 30 days)
PBKDF2 key derivation from secrets
Issuer/audience validation
Automatic expiration checking
Custom claims passthrough from upstream tokens (enabled by default)

6a. Custom Claims Passthrough

Enabled by default - Essential for authorization and RBAC:

Extracts custom claims from upstream access tokens and ID tokens
Includes claims in proxy-issued JWTs for downstream authorization
Supports roles, permissions, groups, email, and other custom claims
Compatible with RBAC libraries and authorization frameworks

Security Features

Protected claims filtering: Standard JWT claims (aud, iss, exp, iat, nbf, jti, client_id) are never copied
JWT detection: Only extracts from JWT-format tokens (3-part base64url)
Graceful handling: Silently skips opaque tokens without errors
Size limits: Configurable claim value size limits (default: 2000 chars)
Type validation: Validates claim values before inclusion

Configuration Options

const authProxy = new OAuthProxy({
  // ... other config ...
  customClaimsPassthrough: {
    // Extract from access token (default: true)
    fromAccessToken: true,

    // Extract from ID token (default: true)
    fromIdToken: true,

    // Add prefix to claim names (default: false/no prefix)
    // Example: 'upstream_' → claims become 'upstream_role', 'upstream_email'
    claimPrefix: false,

    // Only include specific claims (optional allowlist)
    allowedClaims: ['role', 'permissions', 'email', 'groups'],

    // Block specific claims (optional blocklist)
    blockedClaims: ['internal_id'],

    // Maximum size for claim values in characters (default: 2000)
    maxClaimValueSize: 2000,

    // Allow complex objects/arrays (default: false, primitives only)
    allowComplexClaims: false,
  },
});

// Shorthand: boolean enables/disables with defaults
customClaimsPassthrough: true,  // Enable with defaults
customClaimsPassthrough: false, // Disable feature

Token Precedence

When both access token and ID token contain claims:

Access token claims take precedence
ID token claims are merged (non-overlapping only)
This ensures the most authoritative claims are used

Use Cases

RBAC Authorization: Pass user roles from Entra ID/Auth0 to MCP tools
Permission Checks: Use fine-grained permissions from upstream provider
User Context: Include email, name, groups for audit logging
Multi-tenancy: Pass tenant/organization claims for data isolation
Custom Attributes: Forward any custom claims from your identity provider

Example: Authorization with Custom Claims

// Tool with role-based access control
server.addTool({
  name: "admin-action",
  description: "Perform admin action",
  canAccess: async ({ session }) => {
    const token = session?.headers?.["authorization"]?.replace("Bearer ", "");
    if (!token) return false;

    // Decode proxy JWT (contains custom claims from upstream)
    const payload = JSON.parse(
      Buffer.from(token.split(".")[1], "base64url").toString(),
    );

    // Check role claim passed through from upstream IDP
    return payload.role === "admin" || payload.roles?.includes("admin");
  },
  execute: async (args) => {
    // Execute admin action
    return { content: [{ type: "text", text: "Admin action completed" }] };
  },
});

7. Pre-configured Providers

Ready-to-use provider implementations:

GoogleProvider

Endpoint: https://accounts.google.com/o/oauth2/v2/auth
Token: https://oauth2.googleapis.com/token
Default scopes: openid, profile, email

GitHubProvider

Endpoint: https://github.com/login/oauth/authorize
Token: https://github.com/login/oauth/access_token
Default scopes: read:user, user:email

AzureProvider (Entra ID)

Endpoint: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
Token: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Default scopes: openid, profile, email
Supports multi-tenant (common) or specific tenant IDs

8. Automatic Cleanup

Background processes maintain system health:

Expired transactions automatically removed
Authorization codes deleted after use or expiration
Token mappings cleaned up based on TTL
Configurable cleanup intervals (default: 60 seconds)

9. OAuth Endpoints

All standard OAuth 2.1 endpoints:

Endpoint	Method	Purpose
`/oauth/register`	POST	RFC 7591 Dynamic Client Registration
`/oauth/authorize`	GET	OAuth authorization initiation
`/oauth/callback`	GET	OAuth provider callback handler
`/oauth/consent`	GET/POST	User consent screen
`/oauth/token`	POST	Token exchange and refresh
`/.well-known/oauth-authorization-server`	GET	OAuth discovery metadata

10. Security Features

State Management

Cryptographically secure state parameters
State validation on callbacks
Transaction-based flow tracking

Redirect URI Validation

Configurable allowlist patterns
Wildcard support (e.g., https://*.example.com/*)
Localhost support for development

Token Security

One-time authorization codes
Secure random ID generation (crypto.randomUUID)
TTL-based automatic expiration
Optional encryption at rest

OAuth 2.1 Compliance

PKCE required by default
State parameter validation
Standard error responses
Authorization server metadata discovery

11. Advanced Features

Persistent Storage (DiskStore)

File-based token persistence
Survives server restarts
Configurable directory location
Automatic TTL-based cleanup
Key sanitization against directory traversal

Encrypted Storage

AES-256-GCM encryption
Scrypt-based key derivation
Authentication tag verification
Transparent encrypt/decrypt wrapper

Custom Token Storage

Implement the TokenStorage interface:

interface TokenStorage {
  save(key: string, value: unknown, ttl?: number): Promise<void>;
  get(key: string): Promise<unknown | null>;
  delete(key: string): Promise<void>;
  cleanup(): Promise<void>;
}

Forward PKCE Mode

Optional PKCE forwarding to upstream provider:

forwardPkce: false (default): Proxy generates own PKCE
forwardPkce: true: Forwards client's PKCE to upstream

12. Refresh Token Support

Full refresh token lifecycle:

Exchanges refresh tokens with upstream provider
Returns new access tokens to clients
Maintains refresh token mappings (token swap mode)
Automatic expiration handling

13. Scope Management

Flexible scope handling:

Configure default scopes per provider
Supports scope intersection with client requests
Clear scope display in consent screen
Forwards scopes to upstream provider

14. Error Handling

Standardized OAuth error responses:

OAuthProxyError class for consistent errors
RFC-compliant error codes and descriptions
Clear error messages for debugging
Proper HTTP status codes

15. Discovery Metadata

RFC 8414 Authorization Server Metadata:

Advertises supported grant types
Lists available endpoints
Declares PKCE support
Provides issuer information

Performance Characteristics

Startup time: Instant (no warm-up required)
OAuth flow latency: <100ms (local testing)
Memory footprint: Lightweight (~10MB base)
Storage overhead: Minimal (transactions + tokens)
Cleanup efficiency: Background process, non-blocking

Integration Points

FastMCP Server Integration

Use the auth option for seamless OAuth integration:

import { FastMCP, GoogleProvider, requireAuth } from "fastmcp";

const server = new FastMCP({
  auth: new GoogleProvider({
    baseUrl: "https://your-server.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  }),
  name: "My Server",
  version: "1.0.0",
});

No manual route setup required
Seamless Python-style API
Automatic endpoint registration

Session Integration

OAuth tokens available in tool execution context via getAuthSession:

import {
  requireAuth,
  requireScopes,
  requireRole,
  getAuthSession,
} from "fastmcp";

server.addTool({
  canAccess: requireAuth, // Or: requireScopes("read"), requireRole("admin")
  execute: async (_args, { session }) => {
    const { accessToken } = getAuthSession(session);
    const response = await fetch("https://api.provider.com/data", {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    return JSON.stringify(await response.json());
  },
  name: "get-data",
});

Use built-in helpers: requireAuth, requireScopes, requireRole, getAuthSession
Combine with requireAll and requireAny for complex logic
Access upstream token via getAuthSession(session).accessToken

Transport Compatibility

Works with FastMCP HTTP transport:

Requires httpStream transport type
Compatible with existing MCP infrastructure
No special middleware needed

Extensibility

Custom Providers

Extend OAuthProxy class:

Override configuration for new providers
Add provider-specific logic
Maintain consistent interface

Storage Backends

Implement TokenStorage for custom backends:

Redis for distributed deployments
Database storage for persistence
Cloud storage services

Token Verification

Implement TokenVerifier interface:

Custom JWT validation logic
Support for RS256/ES256 algorithms
JWKS (JSON Web Key Set) integration

Monitoring and Observability

Built-in debugging capabilities:

Detailed error messages with context
Transaction state tracking
Token lifecycle visibility
Cleanup operation logging

Limitations

Current Scope

Server-side proxy only (no client-side OAuth handler)
HS256 JWT signing only (no RS256/ES256 yet)
No built-in token revocation endpoint
No built-in distributed locking for multi-server deployments

Storage Considerations

In-memory storage doesn't persist across restarts
DiskStore is single-server only (no distributed support)
Large-scale deployments may need Redis/database backends

Provider Support

Pre-configured providers: Google, GitHub, Azure
Other providers require manual configuration
Some providers may have specific quirks requiring custom handling

Security Considerations

Production Checklist

Threat Mitigation

Confused Deputy: User consent screen
Code Interception: Two-tier PKCE
Token Theft: Short-lived JWTs, encryption at rest
XSS: HTML escaping in consent screen
CSRF: State parameter validation
Replay Attacks: One-time authorization codes
Directory Traversal: Key sanitization in storage

Comparison with Other Solutions

vs. Native DCR

Advantage: Works with providers that don't support DCR Trade-off: Requires pre-registration and proxy management

vs. Direct OAuth Integration

Advantage: Provides DCR interface to clients Trade-off: Additional proxy layer

vs. Auth Middleware

Advantage: MCP-specific, handles full OAuth lifecycle Trade-off: Focused on MCP use case only

Uh oh!

FilesExpand file tree

oauth-proxy-features.md

Latest commit

History