OzMcp.Auth behaviour (OzMcp v0.9.0)

Copy Markdown View Source

Contract for the token check of a protected MCP server.

When the server module declares an authorization block, OzMcp is an OAuth 2.1 resource server. OzMcp does not read, validate, store, log, or forward the raw bearer token. The application owns the whole check through the authenticate/2 callback: it can verify a JWT, call an introspection endpoint (RFC 7662), or trust a header set by a gateway. OzMcp does the rest: it refuses a request without a valid credential before the body is read, it tells the client where the authorization servers are (see OzMcp.Auth.Metadata), it binds each session to the principal that created it and the callbacks receive the caller as ctx.principal. The guide about the authorization gives the whole behaviour: the authorization block, the answers, authorize/3, the scopes of the entities and their filter and the revocation of a principal.

Scopes in the DSL

Declare the scopes that an entity needs with required_scopes in its block. OzMcp refuses a call without them with 403 and an insufficient_scope challenge and the list methods show only the entities that the principal can use. The cursor of a filtered list is an opaque string. If the scopes of the token change between two calls, items can move between pages and the filtered list can get shorter: a cursor that names a page after the new last page is then refused with the error -32602. The guide about the authorization gives the limits of the filter.

The duties of the application

  • Set audiences of the principal (the aud claim) and expires_at (the exp claim). OzMcp refuses a principal whose audiences hold no entry for the resource_url of the server and a principal that is already expired. If your verifier checks the audience itself, set audience_check false in the authorization block.
  • Do not forward the received token to another service: token passthrough is forbidden.
  • To end the access of a principal that you revoke, refuse its token in authenticate/2. Then call OzMcp.Sessions.terminate_principal/2.
  • Keep authenticate/2 fast: it runs for every request. A check that needs a remote service must cache its result.
  • Keep the :claims of a principal small: a task keeps a snapshot of the principal for its whole life.
  • Do not put the token in the text of your own exception: the log of a failure names the type of the failure, never a value of the application.

Run the server behind TLS and configure the runtime option :resource_url with the public URL of the endpoint.

A server with no authorization block is open. A server on the stdio transport (OzMcp.Transport.Stdio) uses none of this, even with an authorization block: the client owns the process of the server.

Setup

defmodule MyApp.McpServer do
  use OzMcp.Config.Server

  server_info do
    name "my-app"
    version "1.0.0"
  end

  authorization do
    verifier MyApp.AuthVerifier
    authorization_servers ["https://auth.example.com"]
    scopes_supported ["files:read", "files:write"]
    challenge_scopes ["files:read"]
  end
end

defmodule MyAppWeb.PlugRouter do
  use Plug.Router
  plug :match
  plug :dispatch

  forward "/mcp",
    to: OzMcp.Router, init_opts: [instance: MyApp.McpServer]

  forward "/.well-known/oauth-protected-resource",
    to: OzMcp.Auth.Metadata, init_opts: [instance: MyApp.McpServer]
end

# Serve the router with Bandit, behind TLS:
# {Bandit, plug: MyAppWeb.PlugRouter, port: 4000}
{OzMcp,
 server: MyApp.McpServer,
 resource_url: "https://mcp.example.com/mcp",
 allowed_origins: ["https://app.example.com"]}

The resource_url is the canonical URL of the MCP endpoint (RFC 8707). It can be read from the environment of a release.

The router takes the allowed_origins from the runtime config. The plug option allowed_origins of OzMcp.Router overrides the list.

The guide about the authorization shows a verifier on a JWT library and a verifier behind a gateway.

Summary

Callbacks

Called for each HTTP request except OPTIONS.

Called after the JSON-RPC request is valid, when the server declares it.

Functions

Read the bearer token from the Authorization header of the request. Never reads a token from the query string.

True for a loopback host: localhost, 127.0.0.1, or ::1. http is allowed for these hosts only. The comparison ignores the case.

True when the value matches the RFC 6749 scope-token syntax: printable ASCII, without space, double quote and backslash.

Callbacks

authenticate(conn, server)

@callback authenticate(conn :: Plug.Conn.t(), server :: module()) ::
  {:ok, OzMcp.Auth.Principal.t()}
  | {:error,
     OzMcp.Auth.Challenge.t()
     | :missing_token
     | :invalid_token
     | :invalid_request}

Called for each HTTP request except OPTIONS.

The callback reads the credentials from the connection (usually with bearer_token/1), validates them and returns the principal.

Return {:ok, principal} when the caller is authenticated. Return {:error, challenge}, or one of the shortcut atoms which become a challenge, to refuse the request. The refusal becomes an HTTP status and a WWW-Authenticate header.

authorize(principal, method, bound)

(optional)
@callback authorize(
  principal :: OzMcp.Auth.Principal.t(),
  method :: String.t(),
  bound :: OzMcp.Pipeline.Bound.t()
) ::
  :ok
  | {:error, {:insufficient_scope, [String.t()]}}
  | {:error, {:insufficient_scope, [String.t()], description :: String.t()}}
  | {:error, :forbidden}

Called after the JSON-RPC request is valid, when the server declares it.

The third argument is a OzMcp.Pipeline.Bound.t/0: the entity the request names, found by the bind stage of the pipeline. Read bound.kind (the kind of the entity: :tool, :resource, :template, :prompt, :completion, :task or :none), bound.name, bound.arguments, bound.task and bound.params. For a method that names no entity (initialize, ping, the lists, logging/setLevel, a notification), bound.kind is :none and bound.params holds the params of the request.

Return :ok to allow the request. Return {:error, {:insufficient_scope, scopes}} or {:error, {:insufficient_scope, scopes, description}} to answer 403 with a scope challenge. The scope of the challenge holds the scopes of the principal and the scopes that are missing. When scopes is an empty list, the header names the challenge_scopes of the server next to the scopes of the principal. Return {:error, :forbidden} to answer 403 without a scope challenge.

For initialize the callback runs before the session exists: a refused initialize creates no session and the callback never receives a session id.

An initialize with a refused scope gets 403, even when it carries an Mcp-Session-Id header. The scope check runs first. An allowed initialize with that header gets 400, from the session check.

The callback runs for the JSON-RPC POST only. It does not run for GET and DELETE: the owner check of the session covers them.

Functions

bearer_token(conn, opts \\ [])

@spec bearer_token(Plug.Conn.t(), keyword()) ::
  {:ok, String.t()} | {:error, OzMcp.Auth.Challenge.t()}

Read the bearer token from the Authorization header of the request. Never reads a token from the query string.

Returns:

  • {:ok, token} for a well-formed bearer token,
  • {:error, challenge} with no error parameter for an absent header, a scheme other than Bearer, or a header with no token after the spaces (RFC 6750, section 3.1),
  • {:error, challenge} with the invalid_request error for more than one Authorization header, a token over the maximum size, or a malformed token.

All spaces after the scheme are skipped: "Bearer abc" gives the token "abc". A tab is not a space: it stays in the token and makes it malformed.

The maximum size in bytes is 8192. The gate copies the runtime option :max_token_bytes of the server to the connection and this function reads it. The option max_bytes: here overrides both. A verifier that does not call this function is not limited.

loopback_host?(host)

@spec loopback_host?(term()) :: boolean()

True for a loopback host: localhost, 127.0.0.1, or ::1. http is allowed for these hosts only. The comparison ignores the case.

scope_token?(value)

@spec scope_token?(term()) :: boolean()

True when the value matches the RFC 6749 scope-token syntax: printable ASCII, without space, double quote and backslash.