AshAi.Mcp.OAuth.Discovery (ash_ai v1.5.6)

Copy Markdown View Source

Finds an MCP server's authorization server.

Implements the discovery steps of the MCP authorization spec (2026-07-28): the WWW-Authenticate challenge, OAuth 2.0 Protected Resource Metadata (RFC 9728), and authorization server metadata through RFC 8414 or OpenID Connect Discovery.

Summary

Types

The parameters of a Bearer challenge.

t()

What discover/2 found.

Functions

Fetches and validates the authorization server metadata for issuer.

The URLs to try for an issuer's metadata, in the spec's priority order.

The canonical resource URI of an MCP server (RFC 8707), used as the resource parameter and as the key tokens are stored under.

Discovers the authorization server for the MCP server at server_url.

Parses the Bearer challenge out of a WWW-Authenticate header.

The well-known protected resource metadata URLs for an MCP server, in the spec's priority order.

Types

challenge()

@type challenge() :: %{
  resource_metadata: String.t() | nil,
  scope: String.t() | nil,
  error: String.t() | nil,
  error_description: String.t() | nil,
  params: %{required(String.t()) => String.t()},
  www_authenticate: String.t()
}

The parameters of a Bearer challenge.

t()

@type t() :: %{
  server: String.t(),
  resource: String.t(),
  issuer: String.t(),
  protected_resource: map(),
  authorization_server: map(),
  challenge: challenge() | nil
}

What discover/2 found.

Functions

authorization_server_metadata(issuer, opts \\ [])

@spec authorization_server_metadata(String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Fetches and validates the authorization server metadata for issuer.

Tries the endpoints the spec lists, in order, and requires the document's issuer to be identical to issuer, HTTPS endpoints, and PKCE S256 support.

authorization_server_metadata_urls(issuer)

@spec authorization_server_metadata_urls(String.t()) :: [String.t()]

The URLs to try for an issuer's metadata, in the spec's priority order.

canonical_resource(url)

@spec canonical_resource(String.t()) :: {:ok, String.t()} | {:error, term()}

The canonical resource URI of an MCP server (RFC 8707), used as the resource parameter and as the key tokens are stored under.

Lowercases the scheme and host, drops the fragment and a default port, and drops a bare trailing slash.

discover(server_url, opts \\ [])

@spec discover(String.t(), keyword()) :: {:ok, t()} | {:error, term()}

Discovers the authorization server for the MCP server at server_url.

Uses the resource_metadata URL from :challenge (a WWW-Authenticate header value or a parsed challenge) when present, and otherwise the well-known URIs: with path insertion first, then at the root. If neither exists and no challenge was given, it sends one unauthenticated request to the server to obtain a challenge.

Uses the first authorization server the metadata lists.

parse_www_authenticate(values)

@spec parse_www_authenticate(String.t() | [String.t()] | nil) :: challenge() | nil

Parses the Bearer challenge out of a WWW-Authenticate header.

Accepts one header value or a list of them, and returns nil when there is no Bearer challenge.

protected_resource_metadata_urls(server_url)

@spec protected_resource_metadata_urls(String.t()) :: [String.t()]

The well-known protected resource metadata URLs for an MCP server, in the spec's priority order.