OAuth 2.0 Protected Resource Metadata
Extracted elements (30)
All JWS and JWE data structures in this specification MUST use the Compact Serialization rather than the JSON Serialization. Choosing a single serialization is intended to facilitate interoperability.
Each protected resource publishes its metadata at a well-known location deterministically derived from its own resource identifier URL, preventing attackers from publishing metadata that claims to describe a different resource but is not authoritative for it.
The specification is intentionally parallel in structure and content to RFC 7591 (Dynamic Client Registration) and RFC 8414 (Authorization Server Metadata), enabling symmetric metadata publishing across clients, authorization servers, and protected resources in the OAuth ecosystem.
Resource servers MAY return other WWW-Authenticate headers indicating various authentication schemes alongside the resource_metadata parameter, allowing support for clients that may or may not implement this specification and allowing clients to choose their preferred authentication scheme.
A protected resource metadata document MUST be queried using an HTTP GET request. If the resource identifier contains a path or query component, any terminating slash following the host component MUST be removed before inserting /.well-known/ and the well-known URI path suffix.
A successful metadata response MUST use the 200 OK HTTP status code and return a JSON object using the application/json content type. Any metadata parameters that are not understood MUST be ignored. Parameters with zero values MUST be omitted from the response.
If a client expects to interact with multiple resource servers, it SHOULD request audience-restricted access tokens using RFC 8707, and the authorization server SHOULD support audience-restricted access tokens.
If a client receives a WWW-Authenticate response indicating that resource metadata may have changed, it SHOULD retrieve the updated protected resource metadata and use the new metadata values after validating them.
If protected resource metadata was retrieved from a URL returned via WWW-Authenticate resource_metadata, the resource value MUST be identical to the URL the client used to make the request to the resource server; if not identical, the data MUST NOT be used.
Implementations MUST support TLS and MUST follow the guidance in BCP 195. TLS certificate checking MUST be performed by the client as described in RFC 9525 when making a protected resource metadata request.
Protected resources supporting metadata MUST make a JSON document available at a URL formed by inserting the well-known URI string (default: /.well-known/oauth-protected-resource) between the host component and path/query components of the resource identifier.
String comparisons between JSON strings and other Unicode strings MUST be performed as Unicode code-point-to-code-point equality comparisons, and Unicode Normalization MUST NOT be applied at any point to either string.
The jwks_uri URL MUST use the https scheme. When both signing and encryption keys are made available, a use parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage.
The recipient MUST validate that any signed metadata was signed by a key belonging to the issuer and that the signature is valid. If the signature does not validate or the issuer is not trusted, the recipient SHOULD treat this as an error condition.
The resource_signing_alg_values_supported parameter value none MUST NOT be used, preventing unsigned resource responses when signing algorithms are advertised.
The resource value returned in the metadata MUST be identical to the protected resource's resource identifier used to derive the well-known URL. If these values are not identical, the data contained in the response MUST NOT be used.
The signed_metadata JWT MUST be digitally signed or MACed using JWS and MUST contain an iss (issuer) claim. Signed metadata values MUST take precedence over corresponding values conveyed using plain JSON elements.
Human-readable metadata fields (resource_name, resource_documentation, resource_policy_uri, resource_tos_uri) support language-tagged variants using BCP 47 tags appended to field names with a # delimiter (e.g., resource_name#fr).
Protected resource metadata is a JSON document published at a well-known URL derived from the resource identifier. It declares capabilities including supported scopes, bearer token methods, authorization servers, signing algorithms, DPoP support, and JWK Set URI.
The authorization_servers field is an OPTIONAL JSON array of OAuth authorization server issuer identifiers that can be used with the protected resource. The protected_resources field (in authorization server metadata) is the complementary list from the AS side.
The signed_metadata field is an OPTIONAL JWT included in the protected resource metadata JSON object, asserting metadata values about the protected resource as claims. The signed_metadata parameter SHOULD NOT itself appear as a claim within the JWT.
The WWW-Authenticate HTTP response header field is extended with a new resource_metadata parameter whose value is the URL of the protected resource metadata. This parameter MAY be used with any authorization scheme (Bearer, DPoP, etc.).
IANA has registered the protected_resources authorization server metadata parameter in the existing "OAuth Authorization Server Metadata" registry (RFC 8414), enabling authorization servers to list their associated protected resources.
IANA has registered the well-known URI suffix oauth-protected-resource in the "Well-Known URIs" registry with permanent status, referencing Section 3 of RFC 9728.
This specification establishes the IANA "OAuth Protected Resource Metadata" registry for protected resource metadata parameter names, with Specification Required policy. Initial entries include resource, authorization_servers, jwks_uri, scopes_supported, bearer_methods_supported, resource_signing_alg_values_supported, resource_name, tls_client_certificate_bound_access_tokens, dpop_signing_alg_values_supported, dpop_bound_access_tokens_required, and signed_metadata.
An attacker may attempt to impersonate a protected resource by publishing a metadata document containing the victim's resource identifier URL. The client MUST ensure the resource identifier prefix used for the metadata request exactly matches the resource metadata parameter in the response, as specified in Section 3.3.
Dynamic discovery of authorization servers from untrusted resource server metadata opens an SSRF risk. Clients SHOULD take precautions against SSRF attacks such as blocking requests to internal IP address ranges when fetching authorization server metadata derived from resource metadata.
Unsigned metadata is integrity protected solely by TLS and PKIX, while signed metadata is additionally protected by the JWS signature from the issuer (iss claim). Signed metadata allows trust decisions based on the signing issuer's identity, which is not available with unsigned metadata.
Without audience-restricted access tokens, a malicious resource server could use the WWW-Authenticate header to cause a client to obtain a scoped token then replay it at a legitimate resource server. Use of RFC 8707 Resource Indicators is RECOMMENDED when using dynamically configured clients.
The metadata document is returned as application/json with members including resource (string, REQUIRED), authorization_servers (JSON array, OPTIONAL), scopes_supported (JSON array, RECOMMENDED), bearer_methods_supported (JSON array with values header/body/query, OPTIONAL), and dpop_bound_access_tokens_required (boolean, default false).