Local OAuth Provider

FrontMCP includes a built-in OAuth 2.1 authorization server for self-contained authentication scenarios.

The built-in login page accepts any email format without validation. Replace with a real identity provider for production use.

Basic Configuration

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'orchestrated',
    type: 'local',
    consent: { enabled: true },
  },
})
export class Server {}

Configuration Options

Option	Type	Default	Description
`consent`	`ConsentConfig`	`{ enabled: false }`	Consent UI configuration
`sessionMode`	`'stateful' \| 'stateless'`	`'stateful'`	Session management strategy
`tokenStorage`	`object`	`{ type: 'memory' }`	Token storage backend
`allowDefaultPublic`	`boolean`	`false`	Allow unauthenticated access
`anonymousScopes`	`string[]`	`['anonymous']`	Scopes for anonymous sessions
`incrementalAuth`	`IncrementalAuthConfig`	`{ enabled: true }`	Progressive authorization config

OAuth Endpoints

Local mode exposes standard OAuth 2.1 endpoints:

Endpoint	Method	Description
`/oauth/authorize`	GET	Start authorization flow
`/oauth/token`	POST	Exchange code for tokens
`/oauth/register`	POST	Dynamic Client Registration
`/oauth/userinfo`	GET	Get user profile
`/.well-known/oauth-authorization-server`	GET	Server metadata
`/.well-known/jwks.json`	GET	Public signing keys

Authorization Request

GET /oauth/authorize
  ?response_type=code
  &client_id=your-client-id
  &redirect_uri=http://localhost:3000/callback
  &scope=openid profile
  &state=random-state
  &code_challenge=base64url(sha256(verifier))
  &code_challenge_method=S256

Token Exchange

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=authorization-code
&redirect_uri=http://localhost:3000/callback
&client_id=your-client-id
&code_verifier=original-verifier

Key Management

Auto-Generated Keys

By default, FrontMCP generates RS256 keys at startup:

auth: {
  mode: 'orchestrated',
  type: 'local',
  // Keys auto-generated
}

Auto-generated keys are lost on restart. Existing tokens become invalid.

Persistent Keys

Provide keys for stable token validation:

auth: {
  mode: 'orchestrated',
  type: 'local',
  local: {
    signKey: {
      kty: 'RSA',
      kid: 'my-key-id',
      alg: 'RS256',
      n: '...',  // RSA modulus
      e: 'AQAB',
      d: '...',  // Private exponent
      // ... other JWK parameters
    },
  },
}

ES256 Keys

Use ES256 for smaller tokens:

auth: {
  mode: 'orchestrated',
  type: 'local',
  local: {
    signKey: {
      kty: 'EC',
      crv: 'P-256',
      x: '...',
      y: '...',
      d: '...',
    },
  },
}

Dynamic Client Registration

DCR allows clients to register programmatically. DCR is enabled by default in development.

Registration Request

POST /oauth/register
Content-Type: application/json

{
  "redirect_uris": ["http://localhost:3000/callback"],
  "client_name": "My Application",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Registration Response

{
  "client_id": "generated-uuid",
  "client_id_issued_at": 1234567890,
  "redirect_uris": ["http://localhost:3000/callback"],
  "client_name": "My Application",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

DCR is intended for development only. In production, pre-register clients. DCR only allows localhost redirect URIs by default.

Per-App Configuration

Configure local auth per app with splitByApp: true:

@App({
  name: 'Billing',
  auth: {
    mode: 'orchestrated',
    type: 'local',
    consent: { enabled: true },
  },
})
export class BillingApp {}

@App({
  name: 'Analytics',
  auth: {
    mode: 'orchestrated',
    type: 'local',
  },
})
export class AnalyticsApp {}

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

Token Storage

In-Memory (Development)

auth: {
  mode: 'orchestrated',
  type: 'local',
  tokenStorage: { type: 'memory' },
}

Redis (Production)

auth: {
  mode: 'orchestrated',
  type: 'local',
  tokenStorage: {
    type: 'redis',
    config: {
      host: process.env.REDIS_HOST!,
      port: parseInt(process.env.REDIS_PORT || '6379'),
      password: process.env.REDIS_PASSWORD,
      keyPrefix: 'myapp:auth:',
    },
  },
}

Enable and customize the consent UI:

auth: {
  mode: 'orchestrated',
  type: 'local',
  consent: {
    enabled: true,
    groupByApp: true,           // Group tools by app
    showDescriptions: true,     // Show tool descriptions
    allowSelectAll: true,       // Allow selecting all tools
    requireSelection: true,     // Require at least one tool
    rememberConsent: true,      // Remember for future sessions
    excludedTools: ['health'],  // Always available tools
    defaultSelectedTools: [],   // Pre-selected tools
    customMessage: 'Select the tools you want to grant access to.',
  },
}

Complete Example

import { FrontMcp } from '@frontmcp/sdk';

@FrontMcp({
  info: { name: 'MyServer', version: '1.0.0' },
  auth: {
    mode: 'orchestrated',
    type: 'local',
    consent: { enabled: true },
    sessionMode: 'stateful',
    tokenStorage: {
      type: 'redis',
      config: {
        host: process.env.REDIS_HOST!,
        port: parseInt(process.env.REDIS_PORT || '6379'),
        password: process.env.REDIS_PASSWORD,
      },
    },
    refresh: {
      enabled: true,
      skewSeconds: 60,
    },
    local: {
      signKey: JSON.parse(process.env.JWT_SIGNING_KEY!),
    },
    incrementalAuth: {
      enabled: true,
      allowSkip: true,
      skippedAppBehavior: 'require-auth',
    },
  },
})
export class Server {}

Troubleshooting

Tokens invalid after restart

Auto-generated keys are lost on restart. Either:

Provide persistent keys via local.signKey
Use Redis for token storage
Accept that users must re-authenticate

PKCE verification failed

Ensure you’re using S256 challenge method and the code_verifier matches the original code_challenge.

Session not found across instances

When running multiple server instances, use Redis for token storage to share session state.

Next Steps

Remote OAuth

Connect to external identity providers

Progressive Authorization

Implement incremental app authorization

Production Checklist

Security requirements for deployment

Tokens & Sessions

Configure token lifetimes

Get Started

Servers

Authentication

Extensibility

Adapters

Plugins

Testing

Guides

Deployment

Local OAuth Provider

Basic Configuration

Configuration Options

OAuth Endpoints

Authorization Request

Token Exchange

Key Management

Auto-Generated Keys

Persistent Keys

ES256 Keys

Dynamic Client Registration

Registration Request

Registration Response

Per-App Configuration

Token Storage

In-Memory (Development)

Redis (Production)

Complete Example

Troubleshooting

Next Steps

Remote OAuth

Progressive Authorization

Production Checklist

Tokens & Sessions

​Basic Configuration

​Configuration Options

​OAuth Endpoints

​Authorization Request

​Token Exchange

​Key Management

​Auto-Generated Keys

​Persistent Keys

​ES256 Keys

​Dynamic Client Registration

​Registration Request

​Registration Response

​Per-App Configuration

​Token Storage

​In-Memory (Development)

​Redis (Production)

​Consent Configuration

​Complete Example

​Troubleshooting

​Next Steps

Remote OAuth

Progressive Authorization

Production Checklist

Tokens & Sessions

Basic Configuration

Configuration Options

OAuth Endpoints

Authorization Request

Token Exchange

Key Management

Auto-Generated Keys

Persistent Keys

ES256 Keys

Dynamic Client Registration

Registration Request

Registration Response

Per-App Configuration

Token Storage

In-Memory (Development)

Redis (Production)

Consent Configuration

Complete Example

Troubleshooting

Next Steps