Update to OAuth 2.0 Protected Resource Metadata Resource Identifier Validation

4.1. Original Rule (Replaced)

Section 3.3 of [RFC9728] states:¶

• If the protected resource metadata was retrieved from a URL returned by the protected resource via the WWW-Authenticate resource_metadata parameter, then the resource value returned MUST be identical to the URL that the client used to make the request to the resource server. If these values are not identical, the data contained in the response MUST NOT be used.¶

This document replaces the above requirement with the updated rule in Section 4.2.¶

4.2. Updated Validation Rule

When a client retrieves protected resource metadata from a URL obtained via the resource_metadata parameter in a WWW-Authenticate challenge (as defined in Section 5 of [RFC9728]), the client MUST verify ALL of the following conditions using the resource value from the metadata response and the URL the client used to make the request that triggered the challenge:¶

1. The scheme of the resource value MUST be https.¶

2. The host of the resource value MUST be identical (using case-insensitive comparison) to the host of the request URL.¶

3. The port of the resource value MUST be identical to the port of the request URL. If either URL omits the port, the default port for the https scheme (443) MUST be used for comparison.¶

4. The path of the resource value MUST be a prefix of the path of the request URL, as defined in Section 4.3.¶

If any of these conditions are not met, the client MUST NOT use the metadata, consistent with the security requirements of [RFC9728].¶

Note that when the resource value is identical to the request URL, all four conditions are trivially satisfied. This means the updated rule is fully backwards compatible with the original exact-match rule in [RFC9728]: any metadata that was valid under the original rule remains valid under this update.¶

This update only applies to metadata retrieved via a WWW-Authenticate challenge. The validation rule for metadata retrieved directly from a well-known URI is NOT changed by this document; the resource value MUST still be identical to the resource identifier from which the well-known URI was derived, as specified in Section 3.3 of [RFC9728].¶

4.3. Path Prefix Matching

This section defines the path prefix matching algorithm referenced by condition 4 of the updated validation rule in Section 4.2.¶

The path of the resource value is a prefix of the path of the request URL if any of the following conditions hold:¶

1. The paths are identical (exact match).¶

2. The resource path ends with / and the request URL path starts with the resource path. For example, a resource path of /api/v1/ is a prefix of a request URL path of /api/v1/accounts.¶

3. The resource path does not end with /, and the request URL path is the resource path followed by / and optionally additional segments. For example, a resource path of /api/v1 is a prefix of request URL paths /api/v1/ and /api/v1/accounts.¶

Matching MUST occur on segment boundaries. A resource path MUST NOT be treated as a prefix if the match would split a path segment. For example, a resource path of /api/v1 MUST NOT match a request URL path of /api/v10 or /api/v1admin, because v10 and v1admin are distinct path segments from v1.¶

Paths MUST be compared in their URI-normalized form per [RFC3986]. Percent-encoded characters MUST be decoded before comparison. An empty or absent path MUST be treated as / for comparison purposes.¶

The following table illustrates the matching behavior:¶

5.1. Host-Level Resource Identifier

A resource server at https://api.example.com advertises a host-level resource identifier covering all of its protected resources.¶

When a client requests https://api.example.com/transactions without a token:¶

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://api.example.com/.well-known/oauth-protected-resource"

The metadata response contains:¶

{
  "resource": "https://api.example.com/",
  "authorization_servers": ["https://as.example.com"],
  "scopes_supported": ["accounts.read", "transactions.read",
    "profile.read"]
  ...
}

The client validates that https://api.example.com/ shares the same TLS origin as https://api.example.com/transactions and that the path / is a prefix of /transactions.¶

5.2. Path-Level Resource Identifier

A resource server at https://platform.example.com exposes two independent sets of protected resources under different path prefixes.¶

When a client requests https://platform.example.com/api/v1/transactions without a token:¶

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://platform.example.com/.well-known/oauth-protected-resource/api/v1"

The metadata response contains:¶

{
  "resource": "https://platform.example.com/api/v1",
  "authorization_servers": ["https://as.example.com"],
  "scopes_supported": ["transactions.read", "accounts.read"]
  ...
}

The client validates that https://platform.example.com/api/v1 shares the same TLS origin as https://platform.example.com/api/v1/transactions and that the path /api/v1 is a prefix of /api/v1/transactions on a segment boundary.¶

A subsequent request to https://platform.example.com/api/v2/reports would NOT match the resource https://platform.example.com/api/v1 because /api/v1 is not a prefix of /api/v2/reports. The client would need to perform a separate discovery for the /api/v2 protected resources.¶

7.1. Preservation of Origin Security Boundary

Section 7.3 of [RFC9728] describes impersonation attacks where an adversary publishes metadata claiming to represent a legitimate resource. The updated validation rule in Section 4.2 maintains the fundamental security property that prevents these attacks: the TLS origin check (conditions 1-3) ensures that the resource value is authoritative for the same server that issued the challenge. An attacker who controls https://evil.example.com cannot cause a client to accept metadata with a resource value of https://api.example.com/, because the origins differ.¶

7.2. Path-Level Isolation

Some deployments host multiple independent services on the same origin, distinguished only by path (e.g., a shared hosting environment where https://shared.example.com/serviceA and https://shared.example.com/serviceB are operated by different tenants). The path-prefix matching rule in this document supports these deployments: each service can advertise its own path-scoped resource identifier (e.g., https://shared.example.com/serviceA) that covers only protected resources under that path prefix.¶

Resource servers in multi-tenant environments SHOULD use path-specific resource identifiers that maintain the necessary isolation between tenants. A resource identifier of https://shared.example.com/serviceA will not match requests to https://shared.example.com/serviceB/resource because /serviceA is not a path prefix of /serviceB/resource. This ensures that tokens obtained for one service cannot be inadvertently reused for another service on the same origin.¶

7.3. Token Scope and Audience

Relaxing the resource matching rule does not change the authorization server's responsibility to enforce audience restrictions on issued tokens. The authorization server remains the authority on what resource(s) a token is valid for. A client's use of a resource identifier (whether host-level or path-scoped) as the resource parameter in a token request is a signal to the authorization server, which MAY issue a token with a narrower or broader audience at its discretion.¶

7.4. Sender-Constrained Tokens

Deployments using sender-constrained tokens (e.g., DPoP [RFC9449]) are compatible with the relaxed matching rule defined in this document. The sender constraint binds the token to the client, not to a specific protected resource, so token reuse across protected resources on the same origin does not weaken the sender-constraint security property.¶

7.5. Metadata Substitution Within an Origin

The updated validation rule in Section 4.2 permits a protected resource to direct clients to metadata with a resource value that differs from the URL of the protected resource (but shares the same origin and satisfies the path-prefix condition). This means that a compromised protected resource on an origin could direct clients to metadata controlled by another protected resource on the same origin. This risk is inherent to same-origin trust and is no different from the existing web security model, where all content on the same origin shares a trust boundary. This risk also exists under the original [RFC9728] rule, since a compromised protected resource can already return arbitrary WWW-Authenticate challenges.¶

9.1. Normative References

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/info/rfc3986>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/info/rfc6750>.

[RFC8707]

Campbell, B., Bradley, J., and H. Tschofenig, "Resource Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, February 2020, <https://www.rfc-editor.org/info/rfc8707>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/info/rfc9110>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/info/rfc9449>.

[RFC9728]

Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, <https://www.rfc-editor.org/info/rfc9728>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.

9.2. Informative References

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/info/rfc6749>.

[I-D.mcguinness-oauth-resource-token-resp]

McGuinness, K. and J. Hanson, "OAuth 2.0 Resource Parameter in Access Token Response", Work in Progress, Internet-Draft, draft-mcguinness-oauth-resource-token-resp-01, 21 December 2025, <https://datatracker.ietf.org/doc/html/draft-mcguinness-oauth-resource-token-resp-01>.

A.1. Exact-Match Constraint

Consider a resource server that exposes individual user resources at unique URLs of the form https://example.com/users/{id}.¶

A client that does not yet hold an access token makes a GET request to the resource. The resource server responds with 401 Unauthorized and a WWW-Authenticate challenge identifying the Protected Resource Metadata document:¶

GET /users/100 HTTP/1.1
Host: example.com

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=
  "https://example.com/.well-known/oauth-protected-resource"

Following the discovery procedure in Section 3 of [RFC9728], the client retrieves the metadata document:¶

GET /.well-known/oauth-protected-resource HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resource": "https://example.com/users/",
  "authorization_servers": ["https://as.example.com"],
  ...
}

Under the original Section 3.3 rule of [RFC9728], the resource value MUST be identical to the request URL https://example.com/users/100. Because the metadata instaed contains an invalid value of https://example.com/users/, the client MUST NOT use the metadata.¶

To satisfy the original exact-match requirement, a resource server has two options.¶

Option 1: A distinct metadata document per resource URL.¶

Each resource URL requires its own Protected Resource Metadata document, for example:¶

https://example.com/users/100/.well-known/...
https://example.com/users/101/.well-known/...
https://example.com/users/102/.well-known/...
...

For APIs where the set of resource URLs is not fixed in advance, this creates an unbounded number of metadata documents to provision, serve, and keep consistent. In practice this results in increased storage overhead, cache fragmentation, and operational complexity that scales linearly with the number of resources.¶

Option 2: Out-of-band knowledge of a representative resource URL.¶

To work around the exact-match constraint, a client could first make a GET request to a "parent" resource (e.g., https://example.com/users) in order to trigger a 401 Unauthorized response whose associated metadata contains a resource value of https://example.com/users. The client would perform discovery against that URL, obtain an access token, and then use the access token to access https://example.com/users/100.¶

GET /users HTTP/1.1
Host: example.com

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=
  "https://example.com/.well-known/oauth-protected-resource"

This approach requires out-of-band knowledge of which URL to request first, which is not conveyed by the protocol. It also introduces an additional round trip before the client can access the originally desired resource, increasing latency and complexity for every new client interaction.¶

A.2. Resolution with the Updated Rule

The updated validation rule in Section 4.2 permits the resource value to be any URI that shares the same TLS origin as the request URL and whose path is a prefix of the request URL path. This allows a single metadata document to cover a collection of related resources, enabling straightforward discovery with no additional round trips or out-of-band coordination.¶

A client that does not yet hold an access token makes a GET request to the resource. The resource server responds with 401 Unauthorized and a WWW-Authenticate challenge:¶

GET /users/100 HTTP/1.1
Host: example.com

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata=
  "https://example.com/.well-known/oauth-protected-resource"

The client retrieves the metadata document:¶

GET /.well-known/oauth-protected-resource HTTP/1.1
Host: example.com

HTTP/1.1 200 OK
Content-Type: application/json

{
  "resource": "https://example.com/users/",
  "authorization_servers": ["https://as.example.com"],
  ...
}

The client validates that https://example.com/users/ shares the same TLS origin as https://example.com/users/100 and that the path /users/ is a prefix of /users/100 on a segment boundary. Both conditions are satisfied, so the client accepts the metadata.¶

The client uses https://example.com/users/ as the resource indicator (per [RFC8707]) when requesting an access token from the authorization server. The resulting access token can be reused for subsequent requests to https://example.com/users/101, https://example.com/users/102, and so on without repeating the discovery or token-request flow.¶