> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# AuthRegistry

> The AuthRegistry manages authentication providers within a scope. It handles auth configuration, provider detection, and orchestration.

## Overview

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import { AuthRegistry } from '@frontmcp/sdk';

// Access via scope
const auth = scope.authProviders;

// Get primary auth provider
const primary = auth.getPrimary();

// Get all auth providers
const providers = auth.getAuthProviders();
```

## Methods

### getPrimary()

Get the primary auth provider.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getPrimary(): FrontMcpAuth
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const auth = registry.getPrimary();

// Check if user is authenticated
const isAuth = await auth.isAuthenticated(request);

// Get current user
const user = await auth.getUser(request);
```

### getAuthProviders()

Get all auth provider entries.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
getAuthProviders(): ReadonlyArray<AuthProviderEntry>
```

**Example:**

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
const providers = registry.getAuthProviders();
for (const provider of providers) {
  console.log(`Provider: ${provider.name} (${provider.mode})`);
}
```

## Auth Modes

FrontMCP supports multiple authentication modes:

<CardGroup cols={3}>
  <Card title="Public" icon="globe">
    No authentication required
  </Card>

  <Card title="Transparent" icon="eye">
    Auth handled externally
  </Card>

  <Card title="Orchestrated" icon="shield-check">
    Full auth flow management
  </Card>
</CardGroup>

### Public Mode

No authentication required:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  name: 'public-server',
  auth: { mode: 'public' },
})
class PublicServer { }
```

### Transparent Mode

Auth is handled by an external system (e.g., API gateway):

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  name: 'transparent-server',
  auth: {
    mode: 'transparent',
    headerName: 'X-User-Id',
  },
})
class TransparentServer { }
```

### Orchestrated Mode

Full auth flow with OAuth support:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  name: 'orchestrated-server',
  auth: {
    mode: 'local',
    providers: ['google', 'github'],
    sessionStore: 'redis',
  },
})
class OrchestratedServer { }
```

## Properties

### primary

The primary auth provider instance (`FrontMcpAuth`).

### parsedOptions

The parsed authentication configuration.

### requiresOrchestration

Whether the current configuration requires orchestration.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
if (registry.requiresOrchestration) {
  // Setup OAuth callbacks, session management, etc.
}
```

### detection

Auth provider detection result across apps in scope.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface AuthProviderDetectionResult {
  hasAuth: boolean;
  modes: AuthMode[];
  providers: string[];
}
```

## Auth Provider Detection

The registry detects auth requirements across the scope hierarchy:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Check detection result
const detection = registry.detection;

if (detection.hasAuth) {
  console.log(`Modes: ${detection.modes.join(', ')}`);
  console.log(`Providers: ${detection.providers.join(', ')}`);
}
```

## Context Extensions

Orchestrated auth installs context extensions:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@Tool({ name: 'protected_tool', inputSchema: {} })
class ProtectedTool extends ToolContext {
  async execute() {
    // Auth context extension
    const user = this.auth.getUser();
    const token = this.auth.getAccessToken();
  }
}
```

## Configuration Validation

The registry validates auth configuration:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
// Invalid configuration throws
@FrontMcp({
  auth: {
    mode: 'local',
    providers: [], // Error: No providers specified
  },
})
class InvalidServer { }
```

## FrontMcpAuth API

The primary auth provider exposes:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
interface FrontMcpAuth {
  // Check authentication
  isAuthenticated(request: Request): Promise<boolean>;

  // Get user info
  getUser(request: Request): Promise<User | null>;

  // Get access token
  getAccessToken(request: Request): Promise<string | null>;

  // Handle OAuth callback
  handleCallback(request: Request): Promise<AuthResult>;

  // Logout
  logout(request: Request): Promise<void>;
}
```

## Session Integration

Auth integrates with session management:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  auth: {
    mode: 'local',
    sessionStore: {
      provider: 'redis',
      host: 'localhost',
      keyPrefix: 'auth:session:',
    },
  },
})
class SecureServer { }
```

## Multi-App Auth

When multiple apps have different auth requirements:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
@FrontMcp({
  name: 'server',
  apps: [PublicApp, ProtectedApp],
})
class MultiAuthServer { }

// The registry detects mixed auth modes
const detection = scope.authProviders.detection;
// detection.modes = ['public', 'orchestrated']
```

## FrontMcpAuthContext

The `FrontMcpAuthContext` is a request-scoped auth identity object available inside tool, resource, and prompt execution. It provides role, permission, and scope checks extracted from JWT claims.

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
import type { FrontMcpAuthContext } from '@frontmcp/auth';
```

### Properties

| Property      | Type                                | Description                                                   |
| ------------- | ----------------------------------- | ------------------------------------------------------------- |
| `user`        | `FrontMcpAuthUser`                  | Resolved user identity (`sub`, `name`, `email`, `picture`)    |
| `isAnonymous` | `boolean`                           | True when `sub` starts with `anon:` or is empty               |
| `mode`        | `string`                            | Authentication mode (`public`, `transparent`, `orchestrated`) |
| `sessionId`   | `string`                            | Session identifier (empty string if no session)               |
| `scopes`      | `readonly string[]`                 | OAuth scopes granted to this session                          |
| `claims`      | `Readonly<Record<string, unknown>>` | Raw JWT claims                                                |
| `roles`       | `readonly string[]`                 | Resolved roles (via `claimsMapping` or direct extraction)     |
| `permissions` | `readonly string[]`                 | Resolved permissions (via `claimsMapping` or direct)          |

### Methods

| Method              | Signature                                     | Description                                 |
| ------------------- | --------------------------------------------- | ------------------------------------------- |
| `hasRole`           | `(role: string) => boolean`                   | Check if user has a specific role           |
| `hasAllRoles`       | `(roles: readonly string[]) => boolean`       | Check if user has ALL specified roles       |
| `hasAnyRole`        | `(roles: readonly string[]) => boolean`       | Check if user has at least one role         |
| `hasPermission`     | `(permission: string) => boolean`             | Check if user has a specific permission     |
| `hasAllPermissions` | `(permissions: readonly string[]) => boolean` | Check if user has ALL specified permissions |
| `hasAnyPermission`  | `(permissions: readonly string[]) => boolean` | Check if user has at least one permission   |
| `hasScope`          | `(scope: string) => boolean`                  | Check if session has a specific OAuth scope |
| `hasAllScopes`      | `(scopes: readonly string[]) => boolean`      | Check if session has ALL specified scopes   |
| `hasAnyScope`       | `(scopes: readonly string[]) => boolean`      | Check if session has at least one scope     |

### Extension

Add custom typed fields via global interface augmentation:

```typescript theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
declare global {
  interface ExtendFrontMcpAuthContext {
    tenantId: string;
    orgName: string;
  }
}
```

Custom fields are populated by `AuthContextPipe` functions registered in your server config.

<Info>
  **FrontMcpAuthContext vs Authorization**: `FrontMcpAuthContext` is request-scoped and provides roles, permissions, and scopes from JWT claims. The `Authorization` interface is transport-scoped and tracks authorized tools, prompts, apps, and provider tokens. Use `FrontMcpAuthContext` for role/permission checks; use `Authorization` for tool/app access control.
</Info>

## Related

* [Authentication Overview](/frontmcp/authentication/overview)
* [Auth Modes](/frontmcp/authentication/modes)
* [Authorities](/frontmcp/authentication/authorities)
* [Production Auth](/frontmcp/authentication/production)
* [Registries Overview](/frontmcp/sdk-reference/registries/overview)