Remote OAuth Providers

FrontMCP supports two approaches for integrating external identity providers:

Transparent Mode

Pass-through tokens from the IdP. FrontMCP validates but doesn’t issue tokens.Best for: Single IdP, existing auth infrastructure

Orchestrated Remote

FrontMCP acts as OAuth server, proxying user authentication to upstream IdP.Best for: Multi-provider, progressive auth, federated scenarios

Transparent Mode

Direct token pass-through from external identity provider.

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'transparent',
    provider: 'https://auth.example.com',
    expectedAudience: 'https://api.myservice.com',
  },
})
export class Server {}

Configuration Options

Option	Type	Default	Description
`provider`	`string`	Required	Base URL of the identity provider
`providerConfig.jwksUri`	`string`	Auto-discovered	Custom JWKS endpoint
`providerConfig.jwks`	`JSONWebKeySet`	-	Inline JWKS for offline verification
`expectedAudience`	`string \| string[]`	Resource URL	Required audience claim value(s)
`requiredScopes`	`string[]`	`[]`	Scopes that must be present in token
`allowAnonymous`	`boolean`	`false`	Allow requests without tokens

Provider Examples

Auth0
Okta
Azure AD
Google

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'transparent',
    provider: 'https://your-tenant.auth0.com',
    // JWKS auto-discovered from /.well-known/jwks.json
    expectedAudience: 'https://api.yourservice.com',
    requiredScopes: ['openid', 'profile'],
  },
})
export class Server {}

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'transparent',
    provider: 'https://your-org.okta.com/oauth2/default',
    expectedAudience: 'api://default',
  },
})
export class Server {}

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'transparent',
    provider: 'https://login.microsoftonline.com/{tenant}/v2.0',
    providerConfig: {
      jwksUri: 'https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys',
    },
    expectedAudience: 'api://{client-id}',
  },
})
export class Server {}

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'transparent',
    provider: 'https://accounts.google.com',
    providerConfig: {
      jwksUri: 'https://www.googleapis.com/oauth2/v3/certs',
    },
    expectedAudience: '{your-client-id}.apps.googleusercontent.com',
  },
})
export class Server {}

Token Flow

Orchestrated Remote Mode

FrontMCP acts as an OAuth server while proxying user authentication to a single mandatory upstream IdP.

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

In mode: 'remote', GET /oauth/authorize redirects straight to the upstream IdP — FrontMCP never shows its own login page or a provider-selection page. After the IdP returns to /oauth/provider/{id}/callback, FrontMCP exchanges the code, stores the upstream tokens (encrypted, server-side), derives the session identity (sub/email/name) from the upstream user, and mints its own HS256-signed session token. Tools read the upstream token with this.orchestration.getToken('<provider-id>') — the provider id is taken from providerConfig.id (or derived from the provider hostname).

Configuration Options

Option	Type	Default	Description
`provider`	`string`	Required	Upstream IdP base URL
`clientId`	`string`	Required	OAuth client ID
`clientSecret`	`string`	-	OAuth client secret (confidential clients)
`scopes`	`string[]`	`['openid']`	Scopes to request from IdP
`providerConfig.dcrEnabled`	`boolean`	`false`	Use Dynamic Client Registration
`consent`	`ConsentConfig`	`{ enabled: false }`	Show consent UI after IdP login
`requireRegisteredClients`	`boolean`	`true`	Refuse an MCP client that isn’t registered
`allowedScopes`	`string[]`	OpenID scopes	Scopes FrontMCP grants in its own tokens
`expectedAudience`	`string \| string[]`	Resource URL	Audiences (`aud`) whose tokens this server accepts, in place of the request’s URL

/oauth/authorize gives the browser a frontmcp_signin_<id> cookie (__Host-frontmcp_signin_<id> over https), and the provider callback accepts the sign-in only from the browser that holds it, so the browser must start the sign-in on the host the IdP returns to (the issuer’s host). See Sign-in cookie.

MCP client registration

requireRegisteredClients defaults to true: /oauth/authorize answers a client_id this server doesn’t know with a 400 page (Unknown client_id) instead of issuing a code to whatever redirect_uri the request names. A client is known when it registered through FrontMCP’s /oauth/register (DCR) or identifies with a CIMD client-id URL. Remote mode has no dcr block, so there is no list of pre-registered clients, and /oauth/register is on only outside production (NODE_ENV !== 'production', registrations kept in memory). A production remote server with the defaults therefore serves CIMD clients only.

Upgrading a remote-mode server from 1.8.2 or earlier. There requireRegisteredClients defaulted to false, so MCP clients that sent a plain client_id without registering were accepted. They now get Unknown client_id. To keep them working:

have them use a CIMD client-id URL (an HTTPS URL of their client metadata document; FrontMCP fetches it and checks redirect_uri against it), or
set requireRegisteredClients: false for local development only. An unregistered client’s redirect_uri can’t be checked against anything, so any site could receive a sign-in code for a client_id it names.

When to Use Orchestrated Remote

Multiple identity providers - Federate users from different IdPs under one session

Progressive authorization - Users authorize apps incrementally

Custom token claims - Add claims not available from upstream

Consent UI - Let users select which tools/resources to grant

Token Flow

Dynamic Client Registration

Not yet wired. providerConfig.dcrEnabled / providerConfig.registrationEndpoint are accepted by the schema but FrontMCP does not yet perform upstream Dynamic Client Registration. In mode: 'remote' you must provide a pre-registered clientId (and clientSecret for confidential clients) — without a clientId the upstream provider is not registered and /oauth/authorize returns a configuration error. DCR support is planned; track it before relying on it.

auth: {
  mode: 'remote',
  provider: 'https://auth.example.com',
  clientId: 'pre-registered-client-id', // required today (DCR not yet wired)
  clientSecret: process.env.IDP_CLIENT_SECRET,
}

Endpoint Overrides

Override auto-discovered endpoints for non-standard IdPs:

auth: {
  mode: 'remote',
  provider: 'https://legacy-idp.example.com',
  providerConfig: {
    authEndpoint: 'https://legacy-idp.example.com/auth',
    tokenEndpoint: 'https://legacy-idp.example.com/token',
    userInfoEndpoint: 'https://legacy-idp.example.com/userinfo',
    jwksUri: 'https://legacy-idp.example.com/keys',
  },
}

Inline JWKS

For offline verification or non-discoverable providers:

auth: {
  mode: 'transparent',
  provider: 'https://auth.example.com',
  providerConfig: {
    jwks: {
      keys: [
        {
          kty: 'RSA',
          kid: 'key-id-1',
          alg: 'RS256',
          n: '...',
          e: 'AQAB',
        },
      ],
    },
  },
}

Multi-Provider Setup

Combine multiple providers with orchestrated mode:

@App({
  name: 'Slack',
  auth: {
    mode: 'transparent',
    provider: 'https://slack.com/oauth',
  },
  standalone: true,
})
export class SlackApp {}

@App({
  name: 'CRM',
  auth: {
    mode: 'transparent',
    provider: 'https://company.auth0.com',
  },
})
export class CrmApp {}

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

Per-App Remote Auth

Configure different providers per app:

@App({
  name: 'Billing',
  auth: {
    mode: 'transparent',
    provider: 'https://billing.auth0.com',
  },
})
export class BillingApp {}

@App({
  name: 'Analytics',
  auth: {
    mode: 'transparent',
    provider: 'https://analytics.okta.com/oauth2/default',
  },
})
export class AnalyticsApp {}

@FrontMcp({
  info: { name: 'Suite', version: '1.0.0' },
  apps: [BillingApp, AnalyticsApp],
  splitByApp: true,
})
export class Server {}

Use standalone: true to expose an app’s OAuth endpoints directly, bypassing the parent auth.

Troubleshooting

Token verification fails

Check expectedAudience matches the token’s aud claim
Verify JWKS endpoint is accessible
Ensure token hasn’t expired

JWKS fetch fails

Verify IdP URL is correct
Check network connectivity
Try providing inline JWKS via providerConfig.jwks

Redirect URI mismatch

Register exact redirect URI with IdP
Check for trailing slashes
Ensure protocol (http/https) matches

Next Steps

Remote Proxy

Handle IdPs without DCR support

Progressive Authorization

Implement incremental app authorization

Local OAuth

Built-in OAuth server setup

Production Checklist

Security requirements for deployment

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Remote OAuth Providers

Transparent Mode

Orchestrated Remote

Transparent Mode

Configuration Options

Provider Examples

Token Flow

Orchestrated Remote Mode

Configuration Options

MCP client registration

When to Use Orchestrated Remote

Token Flow

Dynamic Client Registration

Endpoint Overrides

Inline JWKS

Multi-Provider Setup

Per-App Remote Auth

Troubleshooting

Next Steps

Remote Proxy

Progressive Authorization

Local OAuth

Production Checklist

Transparent Mode

Orchestrated Remote

​Transparent Mode

​Configuration Options

​Provider Examples

​Token Flow

​Orchestrated Remote Mode

​Configuration Options

​MCP client registration

​When to Use Orchestrated Remote

​Token Flow

​Dynamic Client Registration

​Endpoint Overrides

​Inline JWKS

​Multi-Provider Setup

​Per-App Remote Auth

​Troubleshooting

​Next Steps

Remote Proxy

Progressive Authorization

Local OAuth

Production Checklist

Transparent Mode

Configuration Options

Provider Examples

Token Flow

Orchestrated Remote Mode

Configuration Options

MCP client registration

When to Use Orchestrated Remote

Token Flow

Dynamic Client Registration

Endpoint Overrides

Inline JWKS

Multi-Provider Setup

Per-App Remote Auth

Troubleshooting

Next Steps