Wiki · Concept · Last reviewed June 25, 2026

OAuth Authorization Server Metadata

OAuth Authorization Server Metadata is the discovery document that tells clients where an authorization server's endpoints are, what issuer they belong to, and which OAuth capabilities the server claims to support.

Category: Concept Updated: June 25, 2026 Tags: AI agents, authorization, OAuth, discovery, metadata, audit trails

Definition

OAuth Authorization Server Metadata is the Standards Track extension defined in RFC 8414, OAuth 2.0 Authorization Server Metadata, by Michael B. Jones, Nat Sakimura, and John Bradley. RFC 8414 was published in June 2018. It defines a JSON metadata format that an OAuth 2.0 client can use to obtain the information needed to interact with an authorization server.

The metadata document is the authorization server's public map. It can identify the issuer, authorization endpoint, token endpoint, public-key set, dynamic registration endpoint, supported scopes, response types, grant types, client authentication methods, PKCE code challenge methods, revocation endpoint, introspection endpoint, service documentation, policy URI, and terms-of-service URI.

For AI agents, this matters because tool authorization often begins with discovery. A coding agent, browser assistant, or workflow runner may know a resource or issuer before it knows the exact authorization endpoint, token endpoint, supported client authentication method, or PKCE requirement. Authorization server metadata gives the client a structured document to inspect instead of guessing protocol details.

How It Works

RFC 8414 defines a well-known location for metadata. By default, a client retrieves it with an HTTP GET request from a path using /.well-known/oauth-authorization-server, derived from the issuer identifier. If the issuer contains a path component, the well-known segment is inserted between the host and that path. The well-known metadata path must use HTTPS.

A successful response uses HTTP 200 and returns an application/json object. The required issuer value is an HTTPS URL with no query or fragment. authorization_endpoint is required unless no supported grant type uses it. token_endpoint is required unless only the implicit grant type is supported. response_types_supported is required.

The document can also include signed_metadata, a JWT containing metadata claims. If a client supports signed metadata, RFC 8414 says values conveyed in signed metadata take precedence over corresponding plain JSON values. The RFC also requires the issuer value in the metadata to exactly match the issuer identifier used to retrieve the metadata.

Agent Context

The Model Context Protocol makes this layer visible. Its 2025-11-25 authorization specification lists OAuth 2.0 Authorization Server Metadata among the standards it builds on, and it uses metadata discovery when clients and servers negotiate HTTP authorization. The same spec requires MCP clients to verify PKCE support through authorization server metadata or OpenID Connect provider metadata before proceeding.

This matters for agent runtimes because endpoint selection is a security boundary. An agent should not synthesize a token endpoint from a prompt, a page, or a tool description when a standards-based metadata document is available. The metadata gives policy engines a place to pin issuer identity, accepted algorithms, endpoint URLs, and feature support.

Metadata is not trust by itself. A malicious or compromised issuer can still publish coherent metadata. The value is that clients can bind an authorization flow to an issuer and a declared set of endpoints rather than moving through loose strings and model-generated assumptions.

Governance and Safety

Governance begins with remembering what was discovered. Audit trails should preserve the issuer identifier, metadata URL, fetch time, response digest, selected authorization endpoint, token endpoint, JWKS URI, advertised PKCE methods, supported client authentication method, revocation and introspection endpoints if used, cache status, and policy decision.

OAuth Protected Resource Metadata complements this layer. Protected resource metadata tells a client which authorization server governs a resource; authorization server metadata tells the client how to interact with that issuer. In agent systems, those two records help reconstruct why a token request went to a particular server.

Failure modes are practical: accepting metadata over HTTP, ignoring issuer mismatch, caching stale endpoints too long, trusting unsigned or unsigned-looking metadata beyond local policy, letting untrusted content choose the metadata URL, or failing open when required fields such as code_challenge_methods_supported are missing for a flow that requires PKCE.

Defense Pattern

Source Discipline

Claims about OAuth Authorization Server Metadata should identify the issuer identifier, well-known URL, metadata fetch result, required fields, endpoint values, JWKS URI, signed metadata handling, cache policy, and validation result. Do not collapse it into OpenID Connect Discovery, OAuth Protected Resource Metadata, OAuth Client ID Metadata Documents, or a legal conclusion that a user consented.

Spiralist Reading

Spiralism reads authorization server metadata as the institution publishing its own coordinates. Before an agent asks for power, it should know which door is real, which keys verify the door, and which procedures the institution says it supports.

The map is not permission. It is orientation. A serious client still checks policy, consent, audience, scope, and the actual action the agent is about to perform.

Open Questions

Sources

Return to Wiki