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: 'local',
    consent: { enabled: true },
  },
})
export class Server {}

Configuration Options

Option	Type	Default	Description
`consent`	`ConsentConfig`	`{ enabled: false }`	Consent UI configuration
`tokenStorage`	`'memory' \| { redis: RedisConfig }`	`'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

OAuth Callback Flow (`/oauth/callback`)

The callback endpoint processes the user’s response from the authorization page and creates an authorization code. It executes through the following stages:

Stage	Description
`parseInput`	Extract query parameters (email, pending_auth_id, etc.)
`validatePendingAuth`	Verify pending auth record and validate providers
`handleIncrementalAuth`	Process progressive authorization for apps
`handleFederatedAuth`	Chain through federated identity providers
`createAuthorizationCode`	Generate authorization code with consent data
`redirectToClient`	Redirect user back to client with code

Callback Query Parameters

Parameter	Description
`pending_auth_id`	Reference to pending authorization record
`email`	User’s email address
`name`	User’s display name (optional)
`incremental`	Set to `true` for progressive auth (optional)
`app_id`	Target app for incremental authorization (optional)
`federated`	Set to `true` for federated login (optional)
`providers`	Selected provider IDs (optional, array or string)
`tools`	Selected tool IDs for consent (optional, array)

Federated Provider Chaining

When federated=true and providers are selected:

A federated session is created to track progress
PKCE is generated for the first provider
User is redirected to the first provider’s authorization URL
After each provider completes, the chain continues to the next
Once all providers complete, an authorization code is created

Selected provider IDs are validated against the pending authorization’s allowed providers. Invalid provider IDs are rejected with a 400 error.

Error Handling

Missing pending_auth_id: Returns 400 with error page
Expired authorization: Returns 400 with “request expired” message
Invalid provider selection: Returns 400 with “invalid provider selection” message
Missing required fields: Returns 500 with error page

Key Management

Auto-Generated Keys

By default, FrontMCP generates RS256 keys at startup:

auth: {
  mode: '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: '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: '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: 'local',
    consent: { enabled: true },
  },
})
export class BillingApp {}

@App({
  name: 'Analytics',
  auth: {
    mode: '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: 'local',
  tokenStorage: 'memory',
}

Redis (Production)

auth: {
  mode: 'local',
  tokenStorage: {
    redis: {
      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: '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: 'local',
    consent: { enabled: true },
    tokenStorage: {
      redis: {
        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 {}

Auth UI Template Builders

FrontMCP provides server-side HTML template builders for all authentication UI pages. These render with Tailwind CSS and require no build step.

Builder	Purpose
`buildLoginPage()`	Email/password login form
`buildConsentPage()`	Multi-app tool authorization with Authorize/Skip buttons
`buildIncrementalAuthPage()`	Single-app auth for previously skipped apps
`buildFederatedLoginPage()`	Multi-provider selection UI with optional skip
`buildToolConsentPage()`	Tool-level consent within an app
`buildErrorPage()`	Error display with description

Customization

Templates accept a ThemeConfig for visual customization:

import type { ThemeConfig, ThemeColors, ThemeFonts } from '@frontmcp/auth';

Option	Type	Description
`colors`	`ThemeColors`	Primary, background, text, border colors
`fonts`	`ThemeFonts`	Heading and body font families

Layout Variants

Layout	Function	Use Case
`centeredCardLayout()`	Small centered card	Login, error pages
`wideLayout()`	Full-width card	Consent with many tools
`extraWideLayout()`	Extra-wide card	Federated login with many providers

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

​Basic Configuration

​Configuration Options

​OAuth Endpoints

​Authorization Request

​Token Exchange

​OAuth Callback Flow (/oauth/callback)

​Callback Query Parameters

​Federated Provider Chaining

​Error Handling

​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

​Auth UI Template Builders

​Customization

​Layout Variants

​Troubleshooting

​Next Steps

Remote OAuth

Progressive Authorization

Production Checklist

Tokens & Sessions

Basic Configuration

Configuration Options

OAuth Endpoints

Authorization Request

Token Exchange

OAuth Callback Flow (`/oauth/callback`)

Callback Query Parameters

Federated Provider Chaining

Error Handling

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

Auth UI Template Builders

Customization

Layout Variants

Troubleshooting

Next Steps