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 Published: June 25, 2026 Modified: June 25, 2026 Last reviewed: 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. The document is machine-readable discovery, not a grant of permission.

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, JWKS location, or PKCE requirement. Authorization server metadata gives the client a structured document to inspect instead of guessing protocol details from prompts, web pages, or tool descriptions.

Snapshot

Current Context

As of June 25, 2026, RFC 8414 remains the stable IETF RFC for OAuth authorization server metadata. RFC 9700, the OAuth 2.0 Security Best Current Practice published in January 2025, recommends that authorization servers publish RFC 8414 metadata and that clients use it when available because it reduces endpoint misconfiguration, helps enable new security features automatically, and supports key rotation and cryptographic agility.

RFC 9700 also makes PKCE discovery operationally important. Authorization servers must provide a way for clients to detect PKCE support, and RFC 9700 recommends publishing code_challenge_methods_supported in authorization server metadata. RFC 8414 defines that field and says that if it is omitted, the server does not support PKCE.

RFC 9728, OAuth 2.0 Protected Resource Metadata, complements RFC 8414. Protected resource metadata can list the authorization servers associated with a resource; authorization server metadata then tells the client how to interact with a selected issuer. In agent systems, the two documents form a chain from resource to issuer to endpoints.

The Model Context Protocol 2025-11-25 authorization specification uses this chain directly. It requires MCP servers to implement protected resource metadata, requires MCP clients to use that metadata for authorization server discovery, and requires authorization servers to provide either OAuth Authorization Server Metadata or OpenID Connect Discovery so clients can obtain endpoint and capability information.

OAuth 2.1 remains an active Internet-Draft on this review date, so production governance should cite the stable RFCs directly: RFC 8414 for authorization server metadata, RFC 9700 for the current security baseline, RFC 9728 for protected resource metadata, and RFC 9207 for issuer identification in authorization responses.

Boundary Tests

Not OpenID Connect Discovery. RFC 8414 generalizes the OpenID Connect Discovery metadata format for broader OAuth use. The documents overlap, but OpenID Connect Discovery also carries identity-provider semantics for OpenID Connect.

Not protected resource metadata. OAuth Protected Resource Metadata describes a resource server and can point to authorization servers. Authorization server metadata describes an issuer and its OAuth endpoints and capabilities.

Not issuer identification in the callback. OAuth Authorization Server Issuer Identification adds an iss value to authorization responses so clients can detect mix-up attacks after the browser returns.

Not dynamic client registration. Metadata can advertise a registration_endpoint, but the registration protocol and client approval process are separate controls.

Not user consent or agent authorization. A valid metadata document helps route a protocol flow. It does not prove that a user approved an action, that a client is trustworthy, or that the requested scopes are appropriate.

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 client validates the document before using it. RFC 8414 requires the returned issuer value to be identical to the issuer identifier used as input to discovery. Clients should treat that comparison as a security boundary, not as display text that can be normalized, redirected, or loosely matched.

Capability fields then shape the protocol flow. grant_types_supported, response_types_supported, token_endpoint_auth_methods_supported, code_challenge_methods_supported, jwks_uri, revocation_endpoint, and introspection_endpoint tell a client which flow, authentication method, signing keys, and lifecycle controls are available.

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. Signed metadata still needs local policy: the client has to decide which signing parties it trusts and whether unsigned metadata is acceptable for the deployment.

Agent Context

The Model Context Protocol makes this layer visible. Its 2025-11-25 authorization specification requires protected MCP servers to advertise authorization server locations through OAuth Protected Resource Metadata and requires MCP authorization servers to provide either OAuth Authorization Server Metadata or OpenID Connect Discovery. MCP clients must support both discovery mechanisms.

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, PKCE requirements, client registration options, and key material.

The MCP specification also requires clients to verify PKCE support before proceeding with authorization and to refuse authorization when code_challenge_methods_supported is absent from OAuth authorization server metadata. That turns a field that many systems treated as informational into an explicit compatibility and safety gate for agent connectors.

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.

RFC 9700 makes the governance case concrete: metadata reduces misconfiguration risk, helps clients discover security features, and supports key rotation. It does not remove the need for exact issuer checks, redirect URI validation, PKCE, audience restriction, sender-constrained tokens, scope minimization, and ordinary authorization review.

Procurement and assurance reviews should ask whether an agent platform can show the metadata it used, the issuer it expected, the PKCE and client-authentication capabilities it verified, the cache state, and the reason it accepted or rejected the flow. Without that evidence, "uses OAuth" is too vague for multi-provider agent deployments.

Failure Modes

Path construction error. A client appends /.well-known/oauth-authorization-server after an issuer path instead of inserting it between host and path, causing the client to miss the intended metadata or discover a different document.

Issuer mismatch accepted. The metadata response contains an issuer value that differs from the input issuer, but the client normalizes, redirects, aliases, or ignores the mismatch.

Prompt-selected endpoints. A page, tool description, or model response supplies a token endpoint even though standards-based metadata is available. This turns protocol routing into prompt-following behavior.

PKCE fail-open. A client starts an authorization-code flow even though code_challenge_methods_supported is absent or lacks an acceptable method for the deployment.

Stale key or endpoint cache. The client caches metadata without honoring cache policy, change detection, or operational review, so it keeps using outdated endpoints, JWKS locations, signing algorithms, or registration behavior.

Discovery confused with consent. The system records that metadata was valid but fails to record user approval, scope decisions, resource audience, or the downstream agent action.

Minimum Evidence Record

A governance-grade metadata record should preserve enough context to reconstruct an authorization flow without storing credentials. At minimum, it should include:

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, PKCE methods, 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.

Use exact standards status. RFC 8414, RFC 9207, RFC 9700, and RFC 9728 are IETF RFCs. OAuth 2.1 is an Internet-Draft on this review date. OpenID Connect Discovery is an OpenID Foundation specification. MCP authorization is a versioned protocol specification, not an IETF RFC. These distinctions matter when a compliance record says which behavior is required by a stable standard and which behavior is profile-specific.

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