OAuth 2.0 Protected Resource Metadata
Protected Resource Metadata · PRM · RFC 9728 · RFC9728
By Boston Identity · Explained · 6 min read
The short answer
A small JSON file an API publishes at a fixed web address, naming the authorization servers it works with and the scopes it uses, so a client that has never seen the API can find where to get access.
- What it is
- A standard
- Defined by
- IETF, RFC 9728 (Standards Track)
- Who it's for
- Teams exposing APIs or MCP servers to agents
- In our briefings
- 361by month, last 12
What is OAuth 2.0 Protected Resource Metadata?
OAuth Protected Resource Metadata is a standard from the Internet Engineering Task Force (IETF), published as RFC 9728 in April 2025.S1 OAuth is the framework that hands software access tokens instead of passwords. A protected resource is the API that such a token unlocks. RFC 9728 defines a JSON (JavaScript Object Notation) document that the resource publishes about itself, so a client or an authorization server can learn what it needs to use it.§1
The problem is discovery. The standard is meant for a client with no prior knowledge of the resource server.§5.3 The document must name the resource, and it may list the authorization servers that can be used with it, how a token may be sent, and the scopes, or named permissions, it uses.§2 Of those, only the resource identifier is required; scopes are recommended and the rest optional.§2
Its shape deliberately mirrors two older OAuth documents: the one a client sends when it registers itself, and the one an authorization server publishes about itself.§1 The metadata can be plain JSON, or a JSON Web Token (JWT) signed by an issuer who vouches for it.§2.2 A resource server may later send a fresh challenge to say its metadata may have changed, which lets it switch authorization servers without coordinating with clients.§5.2
Not the same as OAuth Authorization Server Metadata (RFC 8414), which describes an authorization server. Protected Resource Metadata describes the API, and it points the client toward the authorization server it works with.§1
How does OAuth 2.0 Protected Resource Metadata work?
Three parties take part: a client such as an app or an agent, the resource server that hosts the API, and the authorization server that issues access tokens. The RFC's example uses the authorization code flow, and it says any other OAuth flow could follow a similar sequence.§5
Figure steps
- The client asks without a token
- The resource server points to its metadata
- The client fetches the metadata
- The client checks the resource value
- The client looks up the authorization server
- The client gets a token and tries again
The client never needs to be told where to log in: the API's 401 points to its metadata, the metadata names the authorization server, and the client checks the resource value before it trusts any of it.
Drawn from RFC 9728, section 5
Swipe for the full figure →
The resource server points to its metadata
The resource server answers 401 Unauthorized. Its WWW-Authenticate header, the HTTP field that carries an authentication challenge, holds a new resource_metadata parameter with the metadata's URL.§5, §5.1 Using the header this way is optional for the resource server.§5
The client fetches the metadata
The client sends an HTTP GET to that URL. By default the address inserts /.well-known/oauth-protected-resource between the host and any path of the resource identifier, so one host can describe many resources.§3, §3.1 A successful answer is a 200 OK carrying a JSON object.§3.2
The client checks the resource value
The resource value in the document must be identical to the identifier the client used to build the URL; when the URL came from the header, it must match the URL the client first called. If the values differ, the client must not use the data.§3.3 The client must also validate the signature on any signed metadata.§3.3
The client looks up the authorization server
From an issuer identifier in the metadata, the client builds the authorization server's own metadata URL under RFC 8414. It requests that document, and the authorization server returns it.§5
The client gets a token and tries again
The client directs the user to the authorization server, which returns an access token once the exchange completes. The client then repeats its first request with the token, and the resource server returns the resource.§5
Why does OAuth 2.0 Protected Resource Metadata matter now?
The Model Context Protocol (MCP), which connects AI agents to outside servers, has made this document mandatory. Its authorization specification says every MCP server must publish protected resource metadata naming its authorization server, and that server must expose its own metadata or OpenID discovery.1 We read this as meaning that any team putting an MCP server in front of company data is now publishing an RFC 9728 file, whether or not anyone chose the RFC.
The checks are where code has slipped. WorkOS grouped three MCP authentication flaws written up within one month.2 The Rust software development kit (SDK) never compared the resource field in a server's RFC 9728 metadata with the server it was talking to.2 The official Python SDK checked the authorization server's issuer, then skipped that check when a server answered the metadata request with a 404 and the SDK fell back to the older flow.2 The Rust fix shipped on 29 June.2
The same document also appears in standards work on access between companies. An appendix of the IETF's draft on chaining identity across trust domains says a resource server may act as a client, finding the other domain's authorization server from that domain's protected resource metadata.3
Where does it fit?
| Compared with | How OAuth 2.0 Protected Resource Metadata differs |
|---|---|
| OAuth 2.0 Authorization Server Metadata | RFC 8414 lets a client obtain metadata about an authorization server. RFC 9728 does the same for the API, and the client then uses an issuer it names to find the RFC 8414 document.§1, §5 |
| Resource Indicators for OAuth 2.0 | Resource Indicators (RFC 8707) let a client ask for a token restricted to one named resource. RFC 9728 recommends using them alongside its own features, because without them a malicious server may be able to reuse a token at a legitimate one.§7.4 |
| Dynamic Client Registration | Dynamic Client Registration (RFC 7591) is how a client describes itself to an authorization server. RFC 9728 leaves registration out of scope and names dynamic registration as one existing way to do it.§1, §5.3 |
| Client ID Metadata Documents | RFC 9728 only mentions identifying clients by URL as a possible future extension.§5.3 MCP's specification now lists Client ID Metadata Documents as a way for a client to get its identity, and keeps dynamic registration for backward compatibility.1 |
What goes wrong?
- Skipping the match check. A client that does not compare the resource value with the URL it used can accept an attacker's document that claims a real API's identifier.§7.3 The Rust MCP SDK had exactly that gap until its fix.2 The client must also check the server's TLS (Transport Layer Security) certificate on the metadata request, which the RFC says prevents adversary-in-the-middle and DNS-based attacks.§7.3
- Trusting the wrong authorization server. The standard does not settle which authorization servers are legitimate for a resource; it assumes the client has its own way to decide.§7.6 If the client uses an inappropriate one, an attacker may proxy a valid authorization server without either side noticing.§7.6
- Token reuse. Without tokens restricted to one audience, a malicious server may get a client to request a token with a legitimate server's scope, then replay it there.§7.4
- Server-side request forgery (SSRF). The client fetches addresses supplied by servers it may not know, so it should guard against SSRF, for instance by blocking requests to internal IP address ranges.§7.7
- Phishing. A malicious resource chosen by the user can mislead them into revealing credentials; good OAuth sign-in screens reduce this risk without removing it.§7.8
- Reading scopes as a request list. The listed scopes are only what the server is willing to disclose, and the client should still request as narrow a scope as the task allows.§7.2
What should a security leader ask?
- 01
Do our agent clients refuse a metadata document whose resource value does not exactly match the URL they fetched it from?
- 02
When a server's metadata request fails or returns a 404, what does our client fall back to, and does that path still check the authorization server's issuer?
- 03
Which authorization servers will our clients accept from a server's metadata, and who maintains that list?
- 04
Do our clients send a resource parameter so each token is restricted to one server?
- 05
Can a client that fetches metadata from an unfamiliar server reach our internal IP address ranges?
Sources
- S1
OAuth 2.0 Protected Resource Metadata (RFC 9728)IETF · RFC 9728, Standards Track, April 2025
›Evidence: 3 claims from 3 briefings
- 1BI-FIND-2026-0190 · MCP's authorization spec makes the agent a plain OAuth client and leaves delegation to an extensionWe had this from WorkOS's reading of the changelog; the page confirms it first-hand. Every MCP server MUST publish protected-resource metadata naming its authorization server, and that server MUST expose its own metadata or OpenID discovery. A client obtains its identity by a Client ID Metadata Document, by pre-registration, or by dynamic client registration, and the last is now the fallback: 'Dynamic Client Registration is deprecated and retained for backwards compatibility with authorization servers that do not support Client ID Metadata Documents.' Servers should name the scopes an operation needs in the 401 challenge. ZeroID implements both registration paths; the specification has now chosen between them, and any gateway that onboards agents by dynamic registration is building on the deprecated path.
- 2BI-FIND-2026-0397 · Three MCP auth flaws in a month, and the spec had already written the rule the SDKs skippedThree MCP authentication flaws written up in one month share a cause: a verification step that existed on the happy path and not on another. The official Python SDK checked the authorization server's issuer, then skipped the check when a server answered the metadata request with a 404 and fell back to the legacy flow, or returned 403 insufficient_scope, and it stored credentials without binding them to an issuer, so a malicious server could collect a client secret, an authorization code and a PKCE verifier. The Rust SDK never compared the resource field in the server's RFC 9728 metadata with the server it was talking to. LiteLLM's MCP route, on a failed key check, fell through to an empty authentication object when the caller sent a fabricated Authorization header. WorkOS's line is the right one: code 'accepted authentication input that nobody verified'. The thirty days are when the advisories landed; the Rust fix shipped on 29 June and LiteLLM's on 30 June, three months before anyone wrote them up together.
- 3BI-FIND-2026-0187 · The cross-domain OAuth draft is one step from an RFC, and it never mentions agentsThe draft's appendix answers part of the question Uber left open, for the cross-domain case and without saying 'agent'. A resource server may act as the client, discovering the other domain's authorization server from that domain's own protected-resource metadata; and an authorization server may act as the client for callers that cannot reach the other domain themselves, so that 'an authorization server in trust domain A may obtain an access token from an authorization server in trust domain B on-behalf-of any client in trust domain A'. Delegated key binding carries the original client's key across in a requested_cnf parameter so the resulting token stays bound to it. That is a standards-track description of an intermediary carrying authority across a boundary on a client's behalf, which is what an agent gateway is sold as. What it does not carry is an actor chain: nothing in the token says who acted in between, and nothing extends per hop. Medium, because the relevance to agents is ours and the draft's own use cases are CI pipelines, partner dashboards and cross-domain calendars.
›In our briefings
The claim each of the newest briefings on OAuth 2.0 Protected Resource Metadata would have you leave with.
Asor's chain names its principal at every hop but cannot show that the principal still holds the grant. Every token's sub must carry the same value, the party "whose grant the chain acts under"; a required client_id names the agent acting at each hop, and step 3 denies a chain whose sub changes. A row added to Table 1 in -03, credited to Cliff Singletary, records the limit: nothing in a chain says whether the principal named in sub still holds the authority the root token granted. A principal who has left, lost the role or had the grant withdrawn leaves every unexpired, unrevoked chain verifying clean, because a status list revokes tokens and nothing in the chain revokes the principal. A deployment that must know checks standing when the root token is issued, which is also where the draft puts approval. Where the gap after minting is unacceptable, an online server in the call path checks again at use. Approval at the root has its own limit: verification shows that no hop exceeded the root, "never that the root was right".
Asor's agent-chain draft now says a chain keeps verifying after its principal leaves, until expiry or revocationBI-FIND-2026-1335
The IETF datatracker shows that the IESG approved OAuth Identity and Authorization Chaining Across Domains (draft-ietf-oauth-identity-chaining) as a Proposed Standard on 22 June 2026, and that it has been in the RFC Editor's queue since that day. Revision 17, the text we read, was posted on 19 July 2026 during that editing. Its authors are Arndt Schwenkschuster and Pieter Kasselman of Defakto Security, Kelley Burgin of MITRE, Mike Jenkins of NSA-CCSS, Brian Campbell of Ping Identity and Aaron Parecki of Okta. Campbell co-wrote RFC 8693 and RFC 7523, the two RFCs the draft combines, and Parecki co-wrote RFC 9728, one of the ways it names for finding the other domain's authorization server. The working group's write-up for the IESG lists implementations, among them Keycloak 26.5 and Okta's. Two other drafts we have read point to it: the transaction-tokens draft leaves crossing domains to it, and the AI agent authentication draft says cross-domain access SHOULD use identity chaining.
OAuth's draft for crossing trust domains is approved for publication and never says agentBI-FIND-2026-0184
The November 2025 revision turns one consent sentence from the June 2025 page into a checklist for MCP proxy servers that connect clients to third-party APIs. The attack it targets needs all four of these conditions: the proxy uses one static client ID with the third-party authorization server, it lets MCP clients register dynamically, that server sets a consent cookie after the first authorization, and the proxy has no consent step for each client. Against it, proxies MUST keep a per-user registry of approved client_ids and check it before starting the third-party flow, show their own consent page naming the client, the scopes and the redirect_uri, and match redirect URIs by exact string. The cookie or session holding the OAuth state MUST NOT be set until the user has approved that page.
MCP's November 2025 security guide makes proxy servers ask consent for each client before forwarding a loginBI-FIND-2025-0688
›Cited in 36 briefings
Every briefing that discusses this term, newest first.
- Asor's agent-chain draft now says a chain keeps verifying after its principal leaves, until expiry or revocation
Draft · · IETF Datatracker · Rafael Asor · Oct 28, 2026
- OAuth's draft for crossing trust domains is approved for publication and never says agent
Draft · · IETF OAuth Working Group · Arndt Schwenkschuster et al. · Jul 19, 2026
- MCP's November 2025 security guide makes proxy servers ask consent for each client before forwarding a login
Article · · Model Context Protocol · Model Context Protocol project · Nov 25, 2025
- MCP's client credentials extension puts the secret in the form body, while its server rule names HTTP Basic
Article · · Model Context Protocol project · Oct 23, 2026
- An OAuth draft lets the API, not the agent, describe the approval, and now name the key the token is bound to
Draft · · IETF Datatracker · Yaroslav Rosomakho et al. · Jun 25, 2026
- WIMSE's agent draft adds how an agent's access ends and where policy engines fit, without a new requirement
Draft · · IETF WIMSE Working Group · Pieter Kasselman et al. · Sep 15, 2026
- WorkOS's agent checklist limits a delegated agent to what it and its user may both do, checked on every call
Article · · WorkOS Blog · Maria Paktiti · Sep 30, 2026
- Cisco's SD-Card rewrite pins MCP tools to what a registry signed; its security sections still read TODO
Draft · · IETF Datatracker · Suhas Nandakumar et al. · Nov 1, 2026
- Cross-App Access draft warns that one stolen sign-in token could reach every app the identity provider permits
Draft · · IETF Datatracker · Aaron Parecki et al. · May 21, 2026
- Agent URI draft -04 ties an agent's name to a key document and bars OAuth servers from trusting the name alone
Draft · · IETF Datatracker · Yaswanth Narvaneni et al. · Oct 20, 2026
- MCP's November 2025 authorization spec puts metadata documents ahead of dynamic client registration
Article · · Model Context Protocol · Nov 25, 2025
- OAuth tokens prove an agent's rights, not a person's consent; revision 05 adds a day-long grant with spend caps
Draft · · IETF Datatracker · Meiling Chen et al. · Oct 27, 2026
- A cross-domain transaction-token grant now names AI agents as a use and keeps the call chain at home
Draft · · IETF Datatracker · George Fletcher et al. · Sep 10, 2026
- MCP client setup moves from registration to metadata checks in a Spring walkthrough
Video · · OWASP Foundation · Oct 24, 2026
- Six companies' agent-auth draft, since adopted by the WIMSE group, keeps credentials out of the model's reach
Draft · · IETF Internet-Draft (individual submission, since adopted by the WIMSE working group) · Pieter Kasselman et al. · Jul 6, 2026
- OpenID Federation 1.0 lets each level of a trust chain only tighten the rules, and defines no revocation process
Article · · OpenID Foundation · Roland Hedberg et al. · Feb 17, 2026
- An attested OAuth client is one somebody vouched for; revision 12 says to trust its claims only as far as the voucher
Draft · · IETF Datatracker · Tobias Looker et al. · Oct 13, 2026
- World's maker proposes a site-scoped handle for each verified human, and bars using it alone to log anyone in
Draft · · IETF Datatracker · Aurélien Brézun, Tools for Humanity · Aug 6, 2026
- An MCP server picks the login URL its client opens, and that was enough to run code on users' machines
Video · · Black Hat · Aug 20, 2026
- TPX replaces an app's embedded AI provider key with a capped, metered grant the user approves at their provider
Article · · tokenpony.dev · Alex Polvi · Jul 20, 2026
- MCP's enterprise login extension says IdP revocation is immediate. Its own spec does not back that up
Article · · Model Context Protocol (modelcontextprotocol.io) · MCP project et al. · Jun 18, 2026
- PayPal moved MCP tool permission checks into the server, and prompt-injected agents stopped getting through
Paper · · arXiv · Huan Li et al. · Sep 18, 2026
- A phishing agent hosted on Microsoft's own domain, and why giving agents identities does not stop it
Article · · WorkOS Blog · Maria Paktiti · Sep 29, 2026
- Three MCP auth flaws in a month, and the spec had already written the rule the SDKs skipped
Article · · WorkOS Blog · Maria Paktiti · Oct 2, 2026
- MCP's authorization spec makes the agent a plain OAuth client and leaves delegation to an extension
Article · · Model Context Protocol project · Jul 28, 2026
- One implementer found a transaction-token rule that let any scope through; the OAuth group fixed it in weeks
Draft · · IETF Datatracker · Dhruv Agnihotri · Jun 23, 2026
- A proposed standard for agent authority advises against delegating it across company lines by default
Paper · · arXiv · Partha Madhira · May 12, 2026
- A KubeCon demo moves MCP servers' OAuth checks into a gateway, safe only if nothing can reach a server directly
Video · · CNCF [Cloud Native Computing Foundation] · Uploaded March 24, 2026
- On its authors' tasks, an LLM check of agent scopes works at one tool and refuses most valid three-tool requests
Paper · · arXiv · Majed El Helou et al. · Oct 30, 2025
- Huawei-led OAuth draft lets clients chain narrower tokens offline but leaves revocation delivery out of scope
Draft · · IETF Datatracker · Li Ruochen et al. · Oct 20, 2025
- Rosenberg and White's AAuth now has the resource server, not the agent, write and sign the approval text
Draft · · IETF Datatracker · Jonathan Rosenberg et al. · Oct 20, 2025
- The July 2025 Cross App Access draft lets the IdP decide app-to-app access and treats agents as plain clients
Draft · · IETF Datatracker · Aaron Parecki et al. · Jul 2, 2025
- MCP's June 2025 authorization spec: a server accepts only tokens issued for it and passes none upstream
Article · · Model Context Protocol project · Jun 18, 2025
- RFC 9728 tells clients where an API's tokens come from and leaves most of the trust decision to them
Article · · RFC Editor · Michael B. Jones et al. · Apr 2025
- RFC 8414 tells an OAuth client to discard server metadata whose issuer differs from the URL it started from
Article · · RFC Editor · Michael B. Jones et al. · Jun 1, 2018
- RFC 6750 tokens work for whoever holds them; RFC 9700 now urges key binding and bars them from query strings
Article · · RFC Editor · Michael B. Jones et al. · Oct 1, 2012
Related terms
What appears alongside OAuth 2.0 Protected Resource Metadata in the same briefings.
OAuth 2.0 Authorization Server MetadataResource Indicators for OAuth 2.0Client ID Metadata DocumentsDynamic Client RegistrationOAuth Identity and Authorization Chaining Across DomainsJWT Bearer GrantPKCEDPoP
Was this explainer useful?
Share this explainer
Pass it on. Every claim has a permanent number, so what you share today still points at the same words next year.