---
title: Authentication Overview
sidebarTitle: Overview
slug: authentication/overview
icon: shield-check
description: Understanding FrontMCP's authentication modes
keywords: ['frontmcp', 'mcp', 'model context protocol', 'authentication', 'auth', 'oauth', 'security', 'typescript']
---

FrontMCP implements a flexible authentication system with four modes designed for both development simplicity and production security.

## Authentication Modes

FrontMCP supports four authentication modes, each designed for different deployment scenarios:

<CardGroup cols={2}>
  <Card title="Public Mode" icon="unlock">
    `mode: 'public'` — No authentication required. Anonymous sessions are auto-generated for all requests.

    **Best for:** Development, testing, public APIs

  </Card>
  <Card title="Transparent Mode" icon="arrow-right-arrow-left">
    `mode: 'transparent'` — Pass-through tokens from external identity providers. FrontMCP validates tokens against upstream JWKS.

    **Best for:** Existing Auth0, Okta, Azure AD integrations

  </Card>
  <Card title="Local Mode" icon="server">
    `mode: 'local'` — Built-in OAuth 2.1 authorization server. FrontMCP issues and validates its own tokens.

    **Best for:** Self-contained auth, multi-app scenarios, progressive authorization

  </Card>
  <Card title="Remote Mode" icon="sitemap">
    `mode: 'remote'` — FrontMCP runs as an OAuth 2.1 server that proxies user authentication to an upstream IdP.

    **Best for:** Federated auth, IdPs without DCR, custom consent layer

  </Card>
</CardGroup>

## Quick Mode Selection

| Scenario                   | Recommended Mode | Why                                 |
| -------------------------- | ---------------- | ----------------------------------- |
| Local development          | `public`         | No setup required                   |
| Existing IdP (Auth0, Okta) | `transparent`    | Direct token pass-through           |
| Multi-provider federation  | `remote`         | Unified session, multiple IdPs      |
| Self-contained auth        | `local`          | Full control, built-in OAuth server |

## Configuration Levels

Authentication can be configured at two levels:

<Tabs>
  <Tab title="Server Level">
    Apply the same auth configuration to all apps:

    ```typescript
    @FrontMcp({
      info: { name: 'MyServer', version: '1.0.0' },
      apps: [BillingApp, AnalyticsApp],
      auth: {
        mode: 'local',
        consent: { enabled: true },
      },
    })
    export class Server {}
    ```

  </Tab>
  <Tab title="App Level">
    Each app defines its own full auth config — mode + options (required when `splitByApp: true`):

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

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

  </Tab>
</Tabs>

<Warning>
  When using `splitByApp: true`, you must configure auth per app. Server-level `auth` is not allowed.
</Warning>

## OAuth 2.1 Compliance

FrontMCP's `local` mode is fully OAuth 2.1 compliant. In `remote` mode, FrontMCP's own endpoints (the surface the MCP client talks to) are OAuth 2.1-aligned, but the end-to-end behavior also depends on the upstream identity provider FrontMCP is proxying to.

The guarantees below apply to FrontMCP's own implementation:

<Check>**PKCE Required** - Only S256 code challenge method supported (downstream)</Check>
<Check>**Authorization Code Flow** - No implicit or password grants</Check>
<Check>**Refresh Token Rotation** - FrontMCP-issued refresh tokens rotate on each use (`local` mode; `remote` mode mirrors upstream behavior)</Check>
<Check>**JWT Access Tokens** - FrontMCP-issued access tokens are signed with **HS256** using your `JWT_SECRET` (RS256/ES256 apply only to the JWKS-published discovery key and to verifying transparent upstream-issued tokens)</Check>

## Session Management

Sessions determine how tokens are stored and managed:

| Session Mode  | Token Storage              | Refresh             | Multi-Instance          |
| ------------- | -------------------------- | ------------------- | ----------------------- |
| **Stateful**  | Server-side (Redis/memory) | Silent refresh      | Requires shared storage |
| **Stateless** | Embedded in JWT            | Client must re-auth | Works anywhere          |

<Tip>
  Use **stateful** sessions when working with short-lived upstream tokens. You'll get automatic refresh without client round-trips.
</Tip>

```typescript
auth: {
  mode: 'local',
  tokenStorage: {
    redis: { host: 'localhost', port: 6379 },
  },
}
```

## Discovery Endpoints

FrontMCP exposes standard OAuth discovery endpoints:

| Endpoint                                  | Description                                        |
| ----------------------------------------- | -------------------------------------------------- |
| `/.well-known/oauth-authorization-server` | OAuth 2.0 Authorization Server Metadata (RFC 8414) |
| `/.well-known/jwks.json`                  | JSON Web Key Set for token verification (RFC 7517) |
| `/.well-known/oauth-protected-resource`   | Protected Resource Metadata                        |

## Next Steps

<CardGroup cols={2}>
  <Card title="Authorization Modes" icon="layer-group" href="/frontmcp/authentication/modes">
    Deep dive into public, transparent, local, and remote modes
  </Card>
  <Card title="Token & Sessions" icon="key" href="/frontmcp/authentication/token">
    Configure token lifetimes and session management
  </Card>
  <Card title="Remote OAuth" icon="cloud" href="/frontmcp/authentication/remote">
    Connect to external identity providers
  </Card>
  <Card title="Custom Auth UI" icon="palette" href="/frontmcp/authentication/custom-ui">
    Replace the built-in login / consent pages with your own React components via the `auth.ui` slot→file map
  </Card>
  <Card title="Production Checklist" icon="clipboard-check" href="/frontmcp/authentication/production">
    Security requirements for production deployments
  </Card>
</CardGroup>
