IETF · April 2025

OAuth 2.0 Protected Resource Metadata

RFC 9728

M. Jones, A. Parecki, F. Skokan

RFCStableIdentity + Authn + AuthzFoundationField guide

This is how an agent goes from 'I have a URL' to 'I know which AS to use and which audience to request' without a human pasting client IDs.

At a glance

Problem: A client that knows only the API URL does not know which authorization server protects it, which scopes exist, or whether DPoP/mTLS is required. RFC 8414 documented the AS; this documents the resource.
Identity / authn / authz: Discovery for the resource server. The missing half of 'agent finds a tool and learns how to auth'.

Actors

Client
Resource server
Authorization server

The gap for agents

A client that knows only the API URL does not know which AS protects it, which scopes exist, or whether DPoP/mTLS is required. RFC 8414 documented the AS; RFC 9728 (April 2025) documents the resource. This is how an agent goes from 'I have a URL' to 'I know which AS to use and which audience to request'.

MCP servers MUST implement RFC 9728. A 401 WWW-Authenticate: Bearer resource_metadata="…" is the usual bootstrap.

Actors and trust boundaries

Validate TLS for the resource identifier to prevent impersonation. The document's resource field is the canonical URI used as RFC 8707 resource. authorization_servers are AS issuer URLs — then fetch 8414 and check those issuers. Do not request every advertised scope.

Mechanics

JSON at /.well-known/oauth-protected-resource with path insertion rules. Fields include resource, authorization_servers, scopes_supported, bearer_methods_supported, jwks_uri, DPoP/mTLS hints, resource_documentation. WWW-Authenticate can point at the document.

resourcefrom spec: Quoted: canonical identifier of the RS. Used as RFC 8707 resource parameter.
authorization_serversfrom spec: Quoted: AS issuer URLs. Client then fetches RFC 8414 metadata.
WWW-Authenticate resource_metadatafrom spec: Quoted challenge parameter used by MCP and others to bootstrap discovery from a 401.

Step-by-step flows

Flow 1

401 → metadata → AS → token

1
Client calls the API, gets 401 with resource_metadata URL.
2
Fetches PRM. Records resource and authorization_servers.
3
Fetches AS metadata (8414 and/or OIDC). Verifies issuer.
4
Performs OAuth 2.1 with resource=canonical URI. Presents the token only to this RS.

Identity vs authentication vs authorization

Discovery for the resource server. The missing half of 'agent finds a tool and learns how to auth'. Not itself an identity or grant protocol.

How it composes

AS metadata
Next hop after reading authorization_servers.
Resource Indicators
resource field becomes the resource parameter.
MCP authorization
MUST for MCP servers and clients (HTTP).
AAuth
AAuth has its own aauth-resource.json well-known. Different document, similar job.

What bites agent implementers

Wrong resource identifier
If PRM resource does not match the URL you call, you will mint a token the RS must reject — or a sloppy RS will accept a confused-deputy token.
Scope greed
scopes_supported is a menu, not a shopping list. Request least privilege.

Stability — what you can ship

RFC 9728, April 2025, M. Jones, A. Parecki, F. Skokan. Stable and new enough that older MCP guides omit it. https://www.rfc-editor.org/rfc/rfc9728.html

Catalog claims (short form)

resource: Canonical identifier of the RS. Used as RFC 8707 resource parameter.
authorization_servers: AS issuer URLs. Client then fetches RFC 8414 metadata.

Implementer notes

MCP servers MUST implement RFC 9728. Validate TLS certificates for the resource identifier to prevent impersonation. Do not request every advertised scope.

Relationship to others

Primary sources

RFC 9728https://www.rfc-editor.org/rfc/rfc9728.html