# What is OAuth 2.0 Protected Resource Metadata?

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

Explainer by Boston Identity, 2026-10-28. 6 min read. https://insights.bostonidentity.com/glossary/protected-resource-metadata

- What it is: standard
- Defined by: IETF, RFC 9728 (Standards Track)
- Who it's for: Teams exposing APIs or MCP servers to agents

## 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 [S1 §1].

The problem is discovery. The standard is meant for a client with no prior knowledge of the resource server [S1 §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 [S1 §2]. Of those, only the resource identifier is required; scopes are recommended and the rest optional [S1 §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 [S1 §1]. The metadata can be plain JSON, or a JSON Web Token (JWT) signed by an issuer who vouches for it [S1 §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 [S1 §5.2].

Think of it like this: Think of a sign on an office door naming the front desk that issues visitor badges for that office. The standard makes the visitor check that the sign really names this door; it does not tell the visitor whether the front desk itself deserves trust.

Not the same as: 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 [S1 §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 [S1 §5].

[Figure: 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.]

1. **The client asks without a token.** The client sends a request to the protected resource without presenting an access token [S1 §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 [S1 §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 [S1 §5, §5.1]. Using the header this way is optional for the resource server [S1 §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 [S1 §3, §3.1]. A successful answer is a 200 OK carrying a JSON object [S1 §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 [S1 §3.3]. The client must also validate the signature on any signed metadata [S1 §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 [S1 §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 [S1 §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 [BI-FIND-2026-0190](https://insights.bostonidentity.com/ref/BI-FIND-2026-0190). 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 [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397). 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 [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397). 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 [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397). The Rust fix shipped on 29 June [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397).

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 [BI-FIND-2026-0187](https://insights.bostonidentity.com/ref/BI-FIND-2026-0187).

## Where does it fit?

- Compared with 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 [S1 §1, §5].
- Compared with 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 [S1 §7.4].
- Compared with 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 [S1 §1, §5.3].
- Compared with Client ID Metadata Documents: RFC 9728 only mentions identifying clients by URL as a possible future extension [S1 §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 [BI-FIND-2026-0190](https://insights.bostonidentity.com/ref/BI-FIND-2026-0190).

## 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 [S1 §7.3]. The Rust MCP SDK had exactly that gap until its fix [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397). 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 [S1 §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 [S1 §7.6]. If the client uses an inappropriate one, an attacker may proxy a valid authorization server without either side noticing [S1 §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 [S1 §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 [S1 §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 [S1 §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 [S1 §7.2].

## What should a security leader ask?

1. Do our agent clients refuse a metadata document whose resource value does not exactly match the URL they fetched it from?
2. 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. Which authorization servers will our clients accept from a server's metadata, and who maintains that list?
4. Do our clients send a resource parameter so each token is restricted to one server?
5. 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)](https://www.rfc-editor.org/rfc/rfc9728) (IETF, RFC 9728, Standards Track, April 2025)

## Evidence

- [BI-FIND-2026-0190](https://insights.bostonidentity.com/ref/BI-FIND-2026-0190): We 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. (from "MCP's authorization spec makes the agent a plain OAuth client and leaves delegation to an extension")
- [BI-FIND-2026-0397](https://insights.bostonidentity.com/ref/BI-FIND-2026-0397): Three 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. (from "Three MCP auth flaws in a month, and the spec had already written the rule the SDKs skipped")
- [BI-FIND-2026-0187](https://insights.bostonidentity.com/ref/BI-FIND-2026-0187): The 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. (from "The cross-domain OAuth draft is one step from an RFC, and it never mentions agents")

---

© 2026 Boston Identity LLC. All rights reserved. Published by Boston Identity LLC.
Quote up to 100 words with the credit "Boston Identity, IAM Insights" and a link to https://insights.bostonidentity.com/glossary/protected-resource-metadata. Claim numbers may be cited freely. Training, fine-tuning and text-and-data-mining use of this page is permitted.
Terms: https://insights.bostonidentity.com/terms · How to cite: https://insights.bostonidentity.com/cite
