OAuth 2.1 authentication plug for MCP servers.

Validates JWT Bearer tokens against a configured authorization server. Implements the MCP specification's OAuth 2.1 Resource Server requirements.

Features

• JWT signature verification via pluggable key providers
• Issuer and audience validation
• Mandatory exp (a token without one is rejected, not accepted forever) and nbf enforcement when present
• Scope extraction and enforcement: a request lacking a tool's, resource's or prompt's declared scope is answered 403 with an insufficient_scope challenge (forbidden/4) so the client can step up
• WWW-Authenticate headers per RFC 9728
• Protected Resource Metadata endpoint support

Configuration

# Basic OAuth with JWKS auto-discovery
{ConduitMcp.Transport.StreamableHTTP,
  server_module: MyServer,
  auth: [
    strategy: :oauth,
    issuer: "https://auth.example.com",
    audience: "https://mcp.example.com",
    scopes_supported: ["read", "write", "admin"],
    key_provider: {ConduitMcp.OAuth.KeyProvider.JWKS,
      jwks_uri: "https://auth.example.com/.well-known/jwks.json"}
  ]}

# Static keys for testing
{ConduitMcp.Transport.StreamableHTTP,
  server_module: MyServer,
  auth: [
    strategy: :oauth,
    issuer: "test-issuer",
    audience: "test-audience",
    key_provider: {ConduitMcp.OAuth.KeyProvider.Static,
      keys: [test_key_map]}
  ]}

Token Claims and the principal

After successful validation the token claims are stored in conn.assigns[:oauth_claims] (or :assign_as) and the scopes in conn.assigns[:oauth_scopes].

The canonical ConduitMcp.Principal is assigned to conn.assigns[:mcp_principal], with :id built from the first claim in :subject_claims (default ["sub", "client_id"]) that holds a non-empty string or an integer, prefixed by that claim's name: "sub:user-123", "client_id:svc-42". The prefix keeps a client-chosen client_id from aliasing a user's sub (see "Id formats" in ConduitMcp.Principal). Task ownership and per-user rate limiting key on that scalar — never on the claims map, which changes every request (exp, iat, jti).

A verified token carrying none of those claims is rejected with

401. sub is optional in a JWT and absent from many client-credentials access tokens, and assigning id: nil would produce an authenticated principal that every consumer reads as anonymous: tasks created by that caller would be unowned (visible to every caller unless :tasks_require_owner is set), and rate limiting would fall back to the shared IP bucket. Point :subject_claims at whatever your authorization server does emit rather than accepting an unidentifiable bearer.

Telemetry

Every verification emits [:conduit_mcp, :auth, :verify] with a :duration measurement and %{strategy: :oauth, status: :ok | :error} metadata. A failure adds :reason, always one of these atoms — never the token, a header value, or a key provider's error term:

A failure without its own 401 message ("Token verification failed") also logs its detailed reason as a Logger warning, clamped and stripped of control characters.