Skip to content
IAM Insights

Explainers · Glossary

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
36By month of the source: 2025-12: 0, 2026-01: 0, 2026-02: 1, 2026-03: 1, 2026-04: 0, 2026-05: 2, 2026-06: 3, 2026-07: 4, 2026-08: 2, 2026-09: 5, 2026-10: 7, 2026-11: 11by month, last 12
01

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

02

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
  1. The client asks without a token
  2. The resource server points to its metadata
  3. The client fetches the metadata
  4. The client checks the resource value
  5. The client looks up the authorization server
  6. The client gets a token and tries again
Fig. 1

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 →

  1. The client asks without a token

    The client sends a request to the protected resource without presenting an access token.§5 How the client learned the resource's address is outside the standard; it may be typed in by a user or found by some other discovery.§1

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

03

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

04

Where does it fit?

Compared withHow OAuth 2.0 Protected Resource Metadata differs
OAuth 2.0 Authorization Server MetadataRFC 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.0Resource 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 RegistrationDynamic 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 DocumentsRFC 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
05

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
06

What should a security leader ask?

  1. 01

    Do our agent clients refuse a metadata document whose resource value does not exactly match the URL they fetched it from?

  2. 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?

  3. 03

    Which authorization servers will our clients accept from a server's metadata, and who maintains that list?

  4. 04

    Do our clients send a resource parameter so each token is restricted to one server?

  5. 05

    Can a client that fetches metadata from an unfamiliar server reach our internal IP address ranges?

07

Sources

›Evidence: 3 claims from 3 briefings
  1. 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.
  2. 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.
  3. 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.

  1. 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

  2. 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

  3. 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.

  1. 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

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

  7. 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

  8. 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

  9. 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

  10. 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

  11. MCP's November 2025 authorization spec puts metadata documents ahead of dynamic client registration

    Article · · Model Context Protocol · Nov 25, 2025

  12. 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

  13. 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

  14. MCP client setup moves from registration to metadata checks in a Spring walkthrough

    Video · · OWASP Foundation · Oct 24, 2026

  15. 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

  16. 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

  17. 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

  18. 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

  19. 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

  20. 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

  21. 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

  22. 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

  23. 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

  24. 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

  25. 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

  26. 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

  27. A proposed standard for agent authority advises against delegating it across company lines by default

    Paper · · arXiv · Partha Madhira · May 12, 2026

  28. 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

  29. 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

  30. 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

  31. 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

  32. 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

  33. 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

  34. 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

  35. 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

  36. 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.