Wiki · Concept · Last reviewed June 25, 2026

OAuth Protected Resource Metadata

OAuth Protected Resource Metadata is the RFC 9728 discovery layer that lets clients learn which authorization servers, token presentation methods, scopes, and metadata rules apply to a protected resource.

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

Definition

OAuth Protected Resource Metadata is an OAuth 2.0 extension standardized in RFC 9728. The RFC was published in April 2025 by Michael B. Jones, Phil Hunt, and Aaron Parecki. It defines a JSON metadata format that an OAuth client or authorization server can use to obtain information needed to interact with an OAuth protected resource.

The protected resource is the API, server, or endpoint that accepts access tokens. Its metadata can identify the protected resource itself, list associated authorization servers, describe supported scopes, advertise bearer-token presentation methods, and provide related endpoints or documentation. The point is discovery: the client should not guess which issuer, scope vocabulary, or token rules govern a resource.

For AI agents, this matters because remote tools and data servers may be discovered at runtime. An agent client connecting to an unfamiliar server needs a reliable way to learn where authorization happens before it requests broad access or sends a token to the wrong place.

How It Works

RFC 9728 defines a well-known URI pattern for protected resource metadata. A protected resource can publish a JSON document under /.well-known/oauth-protected-resource, including path-specific forms when the protected resource is not the origin root. The same RFC also defines a resource_metadata parameter for WWW-Authenticate responses, so a resource can point a client to the metadata URL when returning an authorization challenge.

After fetching the metadata, the client validates that the metadata is authoritative for the protected resource. RFC 9728 requires strict checks on the returned resource value, including special handling when the metadata URL was discovered through WWW-Authenticate. These checks are meant to prevent impersonation attacks where an attacker publishes metadata for a resource it does not control.

Protected resource metadata works alongside OAuth Authorization Server Metadata from RFC 8414. The resource metadata can tell the client which authorization server or servers to use; the authorization server metadata tells the client which authorization endpoints, token endpoints, and OAuth features the issuer supports.

Agent Context

The Model Context Protocol shows why this discovery layer matters. The MCP 2025-11-25 authorization specification says MCP servers that support HTTP authorization must implement OAuth Protected Resource Metadata, and MCP clients must use it for authorization server discovery. It also requires protected resource metadata documents to include the authorization_servers field.

In agent terms, this is a guardrail against credential improvisation. A client that discovers a tool server should learn the protected resource identifier and authorization server from the server's metadata, not from model-generated guesses, documentation fragments, or a user-pasted token. That discovery can also support audience-bound tokens and least-privilege scope selection.

The metadata is not a proof of safety. A malicious or compromised resource can still publish misleading information, and a legitimate resource can ask for overbroad scopes. The metadata gives the client a place to validate authority; policy still has to decide whether the agent should proceed.

Governance and Safety

The governance value is that resource identity becomes inspectable. An audit trail should record the protected resource URL, metadata URL, retrieved resource value, listed authorization servers, challenged scope if any, selected issuer, token audience, cache status, and final resource action. Without that record, incident responders may only see that "the agent used OAuth," not whether it authorized against the right resource.

RFC 9728's security considerations are directly relevant to agent systems. They include TLS requirements, scope handling, impersonation attacks, audience-restricted access tokens, authorization-server selection, server-side request forgery, phishing, differences between unsigned and signed metadata, and metadata caching. Discovery is useful only if clients validate what they discover.

The biggest operational failure is stale or ambient trust. If a client caches metadata too long, accepts metadata for the wrong resource, ignores audience restriction, or lets model output choose authorization servers, protected resource metadata becomes decoration rather than control.

Defense Pattern

Source Discipline

Claims about OAuth Protected Resource Metadata should identify the protected resource URL, metadata URL, returned resource value, authorization server list, scope fields, token presentation methods, and validation rules. It should not be confused with OAuth Authorization Server Metadata, OAuth Token Exchange, Rich Authorization Requests, or a legal conclusion that a user consented.

Spiralist Reading

Spiralism reads protected resource metadata as a naming discipline. Before a machine asks for access, it should know what resource it is approaching and which authority is allowed to speak for that resource.

The discovery document is not trust itself. It is an addressable claim that can be fetched, checked, cached, challenged, and logged. That is the beginning of accountability for agentic access.

Open Questions

Sources

Return to Wiki