Remote OAuth Proxy

Some identity providers don’t support Dynamic Client Registration (DCR). FrontMCP’s OAuth proxy bridges this gap by acting as a local OAuth server while delegating user authentication to the upstream IdP.

When to Use OAuth Proxy

Use Proxy When

IdP doesn’t support DCR
Need custom token claims
Want unified auth endpoints
Require consent UI layer

Use Direct When

IdP supports DCR (Auth0, Okta)
Simple pass-through needed
No custom claims required
Direct transparent mode works

How It Works

The proxy maintains:

Client registration with pre-provisioned credentials
JWKS for signing FrontMCP tokens
Session state linking upstream tokens to local sessions
Token vault storing upstream tokens for API calls

Configuration

Basic Setup

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'remote',
    provider: 'https://legacy-idp.example.com',
    clientId: 'pre-provisioned-client-id',
    clientSecret: process.env.IDP_CLIENT_SECRET,
    scopes: ['openid', 'profile', 'email'],
    consent: { enabled: true },
  },
})
export class Server {}

Configuration Options

Option	Type	Default	Description
`provider`	`string`	Required	Upstream IdP base URL
`clientId`	`string`	Required	Pre-registered client ID
`clientSecret`	`string`	-	Client secret (confidential clients)
`scopes`	`string[]`	`['openid']`	Scopes to request from IdP
`providerConfig`	`ProviderConfig`	-	Endpoint overrides and IdP-specific settings
`consent`	`ConsentConfig`	`{ enabled: false }`	Consent UI configuration

Endpoint Overrides

For non-standard IdPs, override auto-discovered endpoints:

auth: {
  mode: 'remote',
  provider: 'https://legacy-idp.example.com',
  clientId: 'my-client',
  clientSecret: process.env.SECRET,
  providerConfig: {
    // Override endpoints
    authEndpoint: 'https://legacy-idp.example.com/authorize',
    tokenEndpoint: 'https://legacy-idp.example.com/token',
    userInfoEndpoint: 'https://legacy-idp.example.com/userinfo',
    jwksUri: 'https://legacy-idp.example.com/keys',
  },
}

Inline JWKS

For IdPs without a JWKS endpoint:

auth: {
  mode: 'remote',
  provider: 'https://legacy-idp.example.com',
  clientId: 'my-client',
  providerConfig: {
    jwks: {
      keys: [
        {
          kty: 'RSA',
          kid: 'key-1',
          alg: 'RS256',
          n: '...',
          e: 'AQAB',
        },
      ],
    },
  },
}

Token Management

Upstream Token Storage

The proxy stores upstream IdP tokens in the token vault:

// Token vault structure (server-side)
{
  session_id: 'sess_abc123',
  frontmcp_tokens: {
    access_token: 'eyJ...',  // FrontMCP-issued
    refresh_token: 'frt_...',
  },
  upstream_tokens: {
    access_token: 'idp_...',  // From legacy IdP
    refresh_token: 'idp_rt_...',
    expires_at: 1234567890,
  },
}

Automatic Refresh

When upstream tokens expire, the proxy handles refresh:

auth: {
  mode: 'remote',
  provider: 'https://legacy-idp.example.com',
  clientId: 'my-client',
  refresh: {
    enabled: true,
    skewSeconds: 60, // refresh upstream tokens this many seconds before expiry
  },
}

Custom Claims

Custom claims are sourced from the upstream identity provider. Configure your IdP to include the claims you need on the upstream JWT (department, employee_id, roles, etc.); FrontMCP forwards them through this.context.authInfo (or, for typed access, this.auth.claims).

Multi-Provider Proxy

Proxy multiple IdPs under one FrontMCP instance:

@App({
  name: 'CRM',
  auth: {
    mode: 'remote',
    provider: 'https://crm-idp.example.com',
    clientId: process.env.CRM_CLIENT_ID,
    clientSecret: process.env.CRM_CLIENT_SECRET,
  },
})
export class CrmApp {}

@App({
  name: 'ERP',
  auth: {
    mode: 'remote',
    provider: 'https://erp-idp.example.com',
    clientId: process.env.ERP_CLIENT_ID,
    clientSecret: process.env.ERP_CLIENT_SECRET,
  },
})
export class ErpApp {}

@FrontMcp({
  info: { name: 'EnterpriseSuite', version: '1.0.0' },
  apps: [CrmApp, ErpApp],
  auth: {
    mode: 'local',
    consent: { enabled: true },
  },
})
export class Server {}

Each app maintains its own upstream token in the vault. Users authenticate once per app via progressive authorization.

Proxy vs Direct Comparison

Aspect	OAuth Proxy	Direct (Transparent)
Token Issuer	FrontMCP	Upstream IdP
JWKS	FrontMCP-managed	IdP-managed
Session Control	Full	Pass-through
Custom Claims	Yes	No
Consent UI	Optional	No
DCR Required	No	Yes (or pre-registered)
Complexity	Higher	Lower

Security Considerations

Store client secrets securely. Never commit secrets to version control. Use environment variables or a secrets manager.

Validate redirect URIs - Ensure callback URLs are registered with the upstream IdP

Use HTTPS - All communication with upstream IdP must be encrypted

Rotate secrets - Periodically rotate client secrets

Monitor token usage - Log and alert on unusual token patterns

Troubleshooting

Callback fails with state mismatch

Ensure session storage is configured (Redis for multi-instance)
Check that pending authorization TTL hasn’t expired
Verify the state parameter is being preserved

Upstream token exchange fails

Verify client credentials are correct
Check that redirect URI matches exactly (including trailing slash)
Ensure scopes requested are allowed by IdP configuration

User info not available

Confirm openid and profile scopes are requested
Check userinfo endpoint is accessible
Verify IdP returns expected claims

Refresh token not working

Some IdPs require offline_access scope for refresh tokens
Check if IdP rotates refresh tokens (handle rotation)
Verify refresh token hasn’t been revoked

Next Steps

Remote OAuth

Direct IdP integration without proxy

Progressive Authorization

Incremental app authorization

Production Checklist

Security requirements for deployment

Tokens & Sessions

Token lifecycle management

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

When to Use OAuth Proxy

Use Proxy When

Use Direct When

How It Works

Configuration

Basic Setup

Configuration Options

Endpoint Overrides

Inline JWKS

Token Management

Upstream Token Storage

Automatic Refresh

Custom Claims

Multi-Provider Proxy

Proxy vs Direct Comparison

Security Considerations

Troubleshooting

Next Steps

Remote OAuth

Progressive Authorization

Production Checklist

Tokens & Sessions

​When to Use OAuth Proxy

Use Proxy When

Use Direct When

​How It Works

​Configuration

​Basic Setup

​Configuration Options

​Endpoint Overrides

​Inline JWKS

​Token Management

​Upstream Token Storage

​Automatic Refresh

​Custom Claims

​Multi-Provider Proxy

​Proxy vs Direct Comparison

​Security Considerations

​Troubleshooting

​Next Steps

Remote OAuth

Progressive Authorization

Production Checklist

Tokens & Sessions

When to Use OAuth Proxy

How It Works

Configuration

Basic Setup

Configuration Options

Endpoint Overrides

Inline JWKS

Token Management

Upstream Token Storage

Automatic Refresh

Custom Claims

Multi-Provider Proxy

Proxy vs Direct Comparison

Security Considerations

Troubleshooting

Next Steps