Authorization Modes - AgentFront

FrontMCP’s four authentication modes address different deployment scenarios. Understanding when to use each mode is critical for both security and developer experience.

Mode Overview

The auth.mode literal accepts one of four values: 'public', 'transparent', 'local', 'remote'.

Mode Comparison

Feature	Public	Transparent	Local	Remote
Token Required	No	Yes (external)	Yes (FrontMCP-issued)	Yes (FrontMCP-issued)
User Identity	Anonymous	From upstream IdP	From login form	From upstream IdP
JWKS Source	Self-generated	Upstream IdP	Self-generated	Self-generated
Session Management	Minimal	Pass-through	Full control	Full control
Multi-provider	No	Single provider	Multiple via apps	Multiple via apps
Progressive Auth	No	No	Yes	Yes
Consent UI	No	No	Optional	Optional

Public Mode

No authentication required. All requests receive an anonymous session.

const auth: AuthOptionsInput = {
  mode: 'public',
  sessionTtl: 3600, // 1 hour
  anonymousScopes: ['anonymous'],
};

How It Works

Configuration Options

Option	Type	Default	Description
`sessionTtl`	`number`	`3600`	Session lifetime in seconds
`anonymousScopes`	`string[]`	`['anonymous']`	Scopes assigned to anonymous sessions
`publicAccess.tools`	`string[] \| 'all'`	`'all'`	Tools accessible without auth
`publicAccess.prompts`	`string[] \| 'all'`	`'all'`	Prompts accessible without auth
`publicAccess.rateLimit`	`number`	`60`	Rate limit per IP per minute

Use Cases

Development

Rapid prototyping without auth setup overhead

Public APIs

Endpoints that don’t require user identity

Do NOT use public mode when you need:

User identity tracking
Audit trails
Access control per user
Compliance requirements

Transparent Mode

Pass-through tokens from an external identity provider. FrontMCP validates tokens but doesn’t issue them.

const auth: AuthOptionsInput = {
  mode: 'transparent',
  provider: 'https://auth.example.com',
  providerConfig: {
    jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  },
  expectedAudience: 'https://api.myservice.com',
  requiredScopes: ['openid'],
  allowAnonymous: false,
};

How It Works

Configuration Options

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

Provider Examples

Auth0
Okta
Azure AD

auth: {
  mode: 'transparent',
  provider: 'https://your-tenant.auth0.com',
  // JWKS discovered automatically from /.well-known/jwks.json
  expectedAudience: 'https://api.yourservice.com',
}

auth: {
  mode: 'transparent',
  provider: 'https://your-org.okta.com/oauth2/default',
  expectedAudience: 'api://default',
}

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}',
}

Use Cases

Existing IdP Integration

Your organization already uses Auth0, Okta, or similar

Single Provider

All users authenticate through one identity provider

Do NOT use transparent mode when you need:

Multiple identity providers
Progressive authorization (add apps over time)
Server-side token storage with silent refresh
Custom token claims

Local Mode

FrontMCP acts as a full OAuth 2.1 authorization server with a built-in login form. Self-contained auth server with built-in user management.

const auth: AuthOptionsInput = {
  mode: 'local',
  consent: { enabled: true },
  tokenStorage: 'memory', // Use { redis: ... } in production
};

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

Remote Mode

FrontMCP acts as an OAuth 2.1 authorization server that proxies user authentication to an upstream IdP. End users never submit credentials to FrontMCP directly — they’re redirected to the upstream IdP, and FrontMCP exchanges the resulting upstream code/tokens before issuing its own session token to the MCP client.

const auth: AuthOptionsInput = {
  mode: 'remote',
  provider: 'https://auth.example.com',
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  scopes: ['openid', 'profile', 'email'],
  consent: { enabled: true },
};

How It Works

Configuration Options

Option	Type	Default	Description
`consent`	`ConsentConfig`	`{ enabled: false }`	Consent UI configuration
`tokenStorage`	`'memory' \| { redis: RedisConfig }`	`'memory'`	Storage backend
`allowDefaultPublic`	`boolean`	`false`	Allow unauthenticated requests
`federatedAuth`	`FederatedAuthConfig`	-	Federated auth state validation
`incrementalAuth`	`IncrementalAuthConfig`	`{ enabled: true }`	Progressive authorization

consent: {
  enabled: true,
  groupByApp: true,           // Group tools by app in UI
  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
}

Incremental Authorization

incrementalAuth: {
  enabled: true,
  allowSkip: true,                    // Allow skipping app auth
  showAllAppsAtOnce: true,            // Show all apps in one page
  skippedAppBehavior: 'require-auth', // 'anonymous' or 'require-auth'
}

Federated Authentication Configuration

Configure how state parameters are validated during federated (multi-provider) authentication flows.

federatedAuth: {
  stateValidation: 'strict',  // 'strict' (recommended) or 'format'
}

Option	Values	Description
`stateValidation`	`'strict' \| 'format'`	`'strict'`: Full state match (recommended). `'format'`: Only validates state format

OAuth Endpoints

Local and remote modes expose standard OAuth 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	User profile information
`/.well-known/oauth-authorization-server`	GET	Server metadata
`/.well-known/jwks.json`	GET	Public signing keys

Use Cases

Multi-Provider Federation

Combine multiple IdPs under one session (Slack + GitHub + custom)

Progressive Authorization

Users authorize apps incrementally as needed

Full Token Control

Custom token lifetimes, scopes, and refresh behavior

Built-in Consent UI

Let users choose which tools/resources to grant

Do NOT use local or remote mode when:

You only have one IdP and don’t need federation (use transparent instead)
You want to minimize auth complexity
Running multiple instances without Redis

Mode Selection Flowchart

Security Comparison

Security Aspect	Public	Transparent	Local	Remote
Token Verification	None	Against upstream JWKS	Against local JWKS	Against local JWKS (FrontMCP-issued session)
PKCE Support	N/A	Depends on IdP	Always S256	Always S256 (downstream); upstream depends on IdP
Refresh Token Rotation	N/A	Depends on IdP	Always rotated	Depends on upstream IdP
Key Management	Auto-generated	Upstream-managed	Self-managed	Self-managed (session JWKS) + upstream JWKS
Consent UI	No	No	Optional	Optional
Session Revocation	N/A	N/A	Supported	Supported

​Mode Overview

​Mode Comparison

​Public Mode

​How It Works

​Configuration Options

​Use Cases

Development

Public APIs

​Transparent Mode

​How It Works

​Configuration Options

​Provider Examples

​Use Cases

Existing IdP Integration

Single Provider

​Local Mode

​Remote Mode

​How It Works

​Configuration Options

​Consent Configuration

​Incremental Authorization

​Federated Authentication Configuration

​OAuth Endpoints

​Use Cases

Multi-Provider Federation

Progressive Authorization

Full Token Control

Built-in Consent UI

​Mode Selection Flowchart

​Security Comparison

​Token Verification Flow

​Next Steps

Remote OAuth

Local OAuth

Progressive Authorization

Production Deployment

Mode Overview

Mode Comparison

Public Mode

How It Works

Configuration Options

Use Cases

Transparent Mode

How It Works

Configuration Options

Provider Examples

Use Cases

Local Mode

Remote Mode

How It Works

Configuration Options

Consent Configuration

Incremental Authorization

Federated Authentication Configuration

OAuth Endpoints

Use Cases

Mode Selection Flowchart

Security Comparison

Token Verification Flow

Next Steps