rfc9728.original   rfc9728.txt 
OAuth Working Group M.B. Jones Internet Engineering Task Force (IETF) M.B. Jones
Internet-Draft Self-Issued Consulting Request for Comments: 9728 Self-Issued Consulting
Intended status: Standards Track P. Hunt Category: Standards Track P. Hunt
Expires: 18 April 2025 Independent Identity, Inc. ISSN: 2070-1721 Independent Identity, Inc.
A. Parecki A. Parecki
Okta Okta
15 October 2024 April 2025
OAuth 2.0 Protected Resource Metadata OAuth 2.0 Protected Resource Metadata
draft-ietf-oauth-resource-metadata-13
Abstract Abstract
This specification defines a metadata format that an OAuth 2.0 client This specification defines a metadata format that an OAuth 2.0 client
or authorization server can use to obtain the information needed to or authorization server can use to obtain the information needed to
interact with an OAuth 2.0 protected resource. interact with an OAuth 2.0 protected resource.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 18 April 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9728.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction
1.1. Requirements Notation and Conventions . . . . . . . . . . 4 1.1. Requirements Notation and Conventions
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.2. Terminology
2. Protected Resource Metadata . . . . . . . . . . . . . . . . . 5 2. Protected Resource Metadata
2.1. Human-Readable Resource Metadata . . . . . . . . . . . . 7 2.1. Human-Readable Resource Metadata
2.2. Signed Protected Resource Metadata . . . . . . . . . . . 8 2.2. Signed Protected Resource Metadata
3. Obtaining Protected Resource Metadata . . . . . . . . . . . . 8 3. Obtaining Protected Resource Metadata
3.1. Protected Resource Metadata Request . . . . . . . . . . . 9 3.1. Protected Resource Metadata Request
3.2. Protected Resource Metadata Response . . . . . . . . . . 10 3.2. Protected Resource Metadata Response
3.3. Protected Resource Metadata Validation . . . . . . . . . 11 3.3. Protected Resource Metadata Validation
4. Authorization Server Metadata . . . . . . . . . . . . . . . . 11 4. Authorization Server Metadata
5. Use of WWW-Authenticate for Protected Resource Metadata . . . 12 5. Use of WWW-Authenticate for Protected Resource Metadata
5.1. WWW-Authenticate Response . . . . . . . . . . . . . . . . 14 5.1. WWW-Authenticate Response
5.2. Changes to Resource Metadata . . . . . . . . . . . . . . 15 5.2. Changes to Resource Metadata
5.3. Client Identifier and Client Authentication . . . . . . . 15 5.3. Client Identifier and Client Authentication
5.4. Compatibility with Other Authentication Methods . . . . . 16 5.4. Compatibility with Other Authentication Methods
6. String Operations . . . . . . . . . . . . . . . . . . . . . . 16 6. String Operations
7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 7. Security Considerations
7.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . 16 7.1. TLS Requirements
7.2. Scopes . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.2. Scopes
7.3. Impersonation Attacks . . . . . . . . . . . . . . . . . . 17 7.3. Impersonation Attacks
7.4. Audience-Restricted Access Tokens . . . . . . . . . . . . 17 7.4. Audience-Restricted Access Tokens
7.5. Publishing Metadata in a Standard Format . . . . . . . . 18 7.5. Publishing Metadata in a Standard Format
7.6. Authorization Servers . . . . . . . . . . . . . . . . . . 18 7.6. Authorization Servers
7.7. Server-Side Request Forgery (SSRF) . . . . . . . . . . . 19 7.7. Server-Side Request Forgery (SSRF)
7.8. Phishing . . . . . . . . . . . . . . . . . . . . . . . . 19 7.8. Phishing
7.9. Differences between Unsigned and Signed Metadata . . . . 19 7.9. Differences Between Unsigned and Signed Metadata
7.10. Metadata Caching . . . . . . . . . . . . . . . . . . . . 20 7.10. Metadata Caching
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 8. IANA Considerations
8.1. OAuth Protected Resource Metadata Registry . . . . . . . 21 8.1. OAuth Protected Resource Metadata Registry
8.1.1. Registration Template . . . . . . . . . . . . . . . . 21 8.1.1. Registration Template
8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 22 8.1.2. Initial Registry Contents
8.2. OAuth Authorization Server Metadata Registry . . . . . . 24 8.2. OAuth Authorization Server Metadata Registry
8.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 8.2.1. Registry Contents
8.3. Well-Known URI Registry . . . . . . . . . . . . . . . . . 24 8.3. Well-Known URIs Registry
8.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 24 8.3.1. Registry Contents
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 9. References
9.1. Normative References . . . . . . . . . . . . . . . . . . 24 9.1. Normative References
9.2. Informative References . . . . . . . . . . . . . . . . . 27 9.2. Informative References
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 28 Acknowledgements
Appendix B. Document History . . . . . . . . . . . . . . . . . . 28 Authors' Addresses
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31
1. Introduction 1. Introduction
This specification defines a metadata format enabling OAuth 2.0 This specification defines a metadata format enabling OAuth 2.0
clients and authorization servers to obtain information needed to clients and authorization servers to obtain information needed to
interact with an OAuth 2.0 protected resource. The structure and interact with an OAuth 2.0 protected resource. The structure and
content of this specification is intentionally as parallel as content of this specification are intentionally as parallel as
possible to that of "OAuth 2.0 Dynamic Client Registration Protocol" possible to (1) "OAuth 2.0 Dynamic Client Registration Protocol"
[RFC7591], which enables a client to provide metadata about itself to [RFC7591], which enables a client to provide metadata about itself to
an OAuth 2.0 authorization server and to OAuth 2.0 Authorization an OAuth 2.0 authorization server and (2) "OAuth 2.0 Authorization
Server Metadata [RFC8414], which enables a client to obtain metadata Server Metadata" [RFC8414], which enables a client to obtain metadata
about an OAuth 2.0 authorization server. about an OAuth 2.0 authorization server.
The means by which the client obtains the location of the protected The means by which the client obtains the location of the protected
resource is out of scope of this document. In some cases, the resource is out of scope for this document. In some cases, the
location may be manually configured into the client; for example, an location may be manually configured into the client; for example, an
email client could provide an interface for a user to enter the URL email client could provide an interface for a user to enter the URL
of their JMAP [RFC8620] server. In other cases, it may be of their JSON Meta Application Protocol (JMAP) server [RFC8620]. In
dynamically discovered; for example, a user could enter their email other cases, it may be dynamically discovered; for example, a user
address into an email client, the client could perform WebFinger could enter their email address into an email client, the client
[RFC7033] discovery (in a manner related to the description in could perform WebFinger discovery [RFC7033] (in a manner related to
Section 2 of "OpenID Connect Discovery 1.0" [OpenID.Discovery]) to the description in Section 2 of [OpenID.Discovery]) to find the
find the resource server, then fetch the resource server metadata to resource server, and the client could then fetch the resource server
find the authorization server to use to obtain authorization to metadata to find the authorization server to use to obtain
access the user's email. authorization to access the user's email.
The metadata for a protected resource is retrieved from a well-known The metadata for a protected resource is retrieved from a well-known
location as a JSON [RFC8259] document, which declares information location as a JSON [RFC8259] document, which declares information
about its capabilities and optionally, its relationships to other about its capabilities and, optionally, its relationships with other
services. This process is described in Section 3. services. This process is described in Section 3.
This metadata can either be communicated in a self-asserted fashion This metadata can be communicated either in a self-asserted fashion
or as a set of signed metadata values represented as claims in a JSON or as a set of signed metadata values represented as claims in a JSON
Web Token (JWT) [JWT]. In the JWT case, the issuer is vouching for Web Token (JWT) [JWT]. In the JWT case, the issuer is vouching for
the validity of the data about the protected resource. This is the validity of the data about the protected resource. This is
analogous to the role that the Software Statement plays in OAuth analogous to the role that the software statement plays in OAuth
Dynamic Client Registration [RFC7591]. Dynamic Client Registration [RFC7591].
Each protected resource publishing metadata about itself makes its Each protected resource publishing metadata about itself makes its
own metadata document available at a well-known location own metadata document available at a well-known location
deterministically derived from the protected resource's URL, even deterministically derived from the protected resource's URL, even
when the resource server implements multiple protected resources. when the resource server implements multiple protected resources.
This prevents attackers from publishing metadata supposedly This prevents attackers from publishing metadata that supposedly
describing the protected resource, but that is not actually describes the protected resource but that is not actually
authoritative for the protected resource, as described in authoritative for the protected resource, as described in
Section 7.3. Section 7.3.
Section 2 defines metadata parameters that a protected resource can Section 2 defines metadata parameters that a protected resource can
publish, which includes things like which scopes are supported, how a publish, which includes things like which scopes are supported, how a
client can present an access token, and more. These values may be client can present an access token, and more. These values, such as
used by other specifications, such as the jwks_uri used to publish the jwks_uri (see Section 2), may be used with other specifications;
public keys the resource server uses to sign resource responses, for for example, the public keys published in the jwks_uri can be used to
instance, as described in [FAPI.MessageSigning]. verify the signed resource responses, as described in
[FAPI.MessageSigning].
Section 5 describes the use of WWW-Authenticate by protected Section 5 describes the use of WWW-Authenticate by protected
resources to dynamically inform clients of the URL of their protected resources to dynamically inform clients of the URL of their protected
resource metadata. This use of WWW-Authenticate can indicate that resource metadata. This use of WWW-Authenticate can indicate that
the protected resource metadata may have changed. the protected resource metadata may have changed.
1.1. Requirements Notation and Conventions 1.1. Requirements Notation and Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption All applications of JSON Web Signature (JWS) data structures [JWS]
(JWE) [JWE] data structures in this specification utilize the JWS and JSON Web Encryption (JWE) data structures [JWE] as discussed in
Compact Serialization or the JWE Compact Serialization; the JWS JSON this specification utilize the JWS Compact Serialization or the JWE
Serialization and the JWE JSON Serialization are not used. Choosing Compact Serialization; the JWS JSON Serialization and the JWE JSON
a single serialization is intended to facilitate interoperability. Serialization are not used. Choosing a single serialization is
intended to facilitate interoperability.
1.2. Terminology 1.2. Terminology
This specification uses the terms "Access Token", "Authorization This specification uses the terms "access token", "authorization
Code", "Authorization Endpoint", "Authorization Grant", code", "authorization server", "client", "client authentication",
"Authorization Server", "Client", "Client Authentication", "Client "client identifier", "protected resource", and "resource server"
Identifier", "Client Secret", "Grant Type", "Protected Resource", defined by OAuth 2.0 [RFC6749], and the terms "Claim Name" and "JSON
"Redirection URI", "Refresh Token", "Resource Owner", "Resource Web Token (JWT)" defined by "JSON Web Token (JWT)" [JWT].
Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0
[RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token
(JWT)" defined by JSON Web Token (JWT) [JWT].
This specification defines the following term: This specification defines the following term:
Resource Identifier: Resource Identifier:
The Protected resource's resource identifier, which is a URL that The protected resource's resource identifier, which is a URL that
uses the https scheme and has no fragment component. As in uses the https scheme and has no fragment component. As specified
Section 2 of [RFC8707], it also SHOULD NOT include a query in Section 2 of [RFC8707], it also SHOULD NOT include a query
component, but it is recognized that there are cases that make a component, but it is recognized that there are cases that make a
query component a useful and necessary part of a resource query component a useful and necessary part of a resource
identifier. Protected resource metadata is published at a .well- identifier. Protected resource metadata is published at a .well-
known location [RFC8615] derived from this resource identifier, as known location [RFC8615] derived from this resource identifier, as
described in Section 3. described in Section 3.
2. Protected Resource Metadata 2. Protected Resource Metadata
Protected resources can have metadata describing their configuration. Protected resources can have metadata describing their configuration.
The following protected resource metadata parameters are used by this The following protected resource metadata parameters are used by this
specification and are registered in the IANA "OAuth Protected specification and are registered in the "OAuth Protected Resource
Resource Metadata" registry established in Section 8.1: Metadata" registry established in Section 8.1:
resource resource
REQUIRED. The protected resource's Resource Identifier, as REQUIRED. The protected resource's resource identifier, as
defined in Section 1.2. defined in Section 1.2.
authorization_servers authorization_servers
OPTIONAL. JSON array containing a list of OAuth authorization OPTIONAL. JSON array containing a list of OAuth authorization
server issuer identifiers, as defined in [RFC8414], for server issuer identifiers, as defined in [RFC8414], for
authorization servers that can be used with this protected authorization servers that can be used with this protected
resource. Protected resources MAY choose not to advertise some resource. Protected resources MAY choose not to advertise some
supported authorization servers even when this parameter is used. supported authorization servers even when this parameter is used.
In some use cases, the set of authorization servers will not be In some use cases, the set of authorization servers will not be
enumerable, in which case this metadata parameter would not be enumerable, in which case this metadata parameter would not be
skipping to change at page 5, line 37 skipping to change at line 217
OPTIONAL. URL of the protected resource's JSON Web Key (JWK) Set OPTIONAL. URL of the protected resource's JSON Web Key (JWK) Set
[JWK] document. This contains public keys belonging to the [JWK] document. This contains public keys belonging to the
protected resource, such as signing key(s) that the resource protected resource, such as signing key(s) that the resource
server uses to sign resource responses. This URL MUST use the server uses to sign resource responses. This URL MUST use the
https scheme. When both signing and encryption keys are made https scheme. When both signing and encryption keys are made
available, a use (public key use) parameter value is REQUIRED for available, a use (public key use) parameter value is REQUIRED for
all keys in the referenced JWK Set to indicate each key's intended all keys in the referenced JWK Set to indicate each key's intended
usage. usage.
scopes_supported scopes_supported
RECOMMENDED. JSON array containing a list of the OAuth 2.0 RECOMMENDED. JSON array containing a list of scope values, as
[RFC6749] scope values that are used in authorization requests to defined in OAuth 2.0 [RFC6749], that are used in authorization
request access to this protected resource. Protected resources requests to request access to this protected resource. Protected
MAY choose not to advertise some scope values supported even when resources MAY choose not to advertise some scope values supported
this parameter is used. even when this parameter is used.
bearer_methods_supported bearer_methods_supported
OPTIONAL. JSON array containing a list of the supported methods OPTIONAL. JSON array containing a list of the supported methods
of sending an OAuth 2.0 Bearer Token [RFC6750] to the protected of sending an OAuth 2.0 bearer token [RFC6750] to the protected
resource. Defined values are ["header", "body", "query"], resource. Defined values are ["header", "body", "query"],
corresponding to Sections 2.1, 2.2, and 2.3 of RFC 6750. The corresponding to Sections 2.1, 2.2, and 2.3 of [RFC6750]. The
empty array [] can be used to indicate that no Bearer methods are empty array [] can be used to indicate that no bearer methods are
supported. If this entry is omitted, no default Bearer methods supported. If this entry is omitted, no default bearer methods
supported are implied, nor does its absence indicate that they are supported are implied, nor does its absence indicate that they are
not supported. not supported.
resource_signing_alg_values_supported resource_signing_alg_values_supported
OPTIONAL. JSON array containing a list of the JWS [JWS] signing OPTIONAL. JSON array containing a list of the JWS [JWS] signing
algorithms (alg values) [JWA] supported by the protected resource algorithms (alg values) [JWA] supported by the protected resource
for signing resource responses, for instance, as described in for signing resource responses, for instance, as described in
[FAPI.MessageSigning]. No default algorithms are implied if this [FAPI.MessageSigning]. No default algorithms are implied if this
entry is omitted. The value none MUST NOT be used. entry is omitted. The value none MUST NOT be used.
resource_name resource_name
Human-readable name of the protected resource intended for display Human-readable name of the protected resource intended for display
to the end-user. It is RECOMMENDED that protected resource to the end user. It is RECOMMENDED that protected resource
metadata includes this field. The value of this field MAY be metadata include this field. The value of this field MAY be
internationalized, as described in Section 2.1. internationalized, as described in Section 2.1.
resource_documentation resource_documentation
OPTIONAL. URL of a page containing human-readable information OPTIONAL. URL of a page containing human-readable information
that developers might want or need to know when using the that developers might want or need to know when using the
protected resource. The value of this field MAY be protected resource. The value of this field MAY be
internationalized, as described in Section 2.1. internationalized, as described in Section 2.1.
resource_policy_uri resource_policy_uri
OPTIONAL. URL of a page containing human-readable information OPTIONAL. URL of a page containing human-readable information
skipping to change at page 6, line 41 skipping to change at line 269
OPTIONAL. URL of a page containing human-readable information OPTIONAL. URL of a page containing human-readable information
about the protected resource's terms of service. The value of about the protected resource's terms of service. The value of
this field MAY be internationalized, as described in Section 2.1. this field MAY be internationalized, as described in Section 2.1.
tls_client_certificate_bound_access_tokens tls_client_certificate_bound_access_tokens
OPTIONAL. Boolean value indicating protected resource support for OPTIONAL. Boolean value indicating protected resource support for
mutual-TLS client certificate-bound access tokens [RFC8705]. If mutual-TLS client certificate-bound access tokens [RFC8705]. If
omitted, the default value is false. omitted, the default value is false.
authorization_details_types_supported authorization_details_types_supported
OPTIONAL. A JSON array containing a list of the authorization OPTIONAL. JSON array containing a list of the authorization
details type values supported by the resource server when the details type values supported by the resource server when the
authorization_details request parameter [RFC9396] is used. authorization_details request parameter [RFC9396] is used.
dpop_signing_alg_values_supported dpop_signing_alg_values_supported
OPTIONAL. A JSON array containing a list of the JWS alg values OPTIONAL. JSON array containing a list of the JWS alg values
(from the "JSON Web Signature and Encryption Algorithms" registry (from the "JSON Web Signature and Encryption Algorithms" registry
[IANA.JOSE]) supported by the resource server for validating DPoP [IANA.JOSE]) supported by the resource server for validating
proof JWTs [RFC9449]. Demonstrating Proof of Possession (DPoP) proof JWTs [RFC9449].
dpop_bound_access_tokens_required dpop_bound_access_tokens_required
OPTIONAL. A boolean value specifying whether the protected OPTIONAL. Boolean value specifying whether the protected resource
resource always requires the use of DPoP-bound access tokens always requires the use of DPoP-bound access tokens [RFC9449]. If
[RFC9449]. If omitted, the default value is false. omitted, the default value is false.
Additional protected resource metadata parameters MAY also be used. Additional protected resource metadata parameters MAY also be used.
2.1. Human-Readable Resource Metadata 2.1. Human-Readable Resource Metadata
Human-readable resource metadata values and resource metadata values Human-readable resource metadata values and resource metadata values
that reference human-readable content MAY be represented in multiple that reference human-readable content MAY be represented in multiple
languages and scripts. For example, the values of fields such as languages and scripts. For example, the values of fields such as
resource_name, resource_documentation, resource_tos_uri, and resource_name, resource_documentation, resource_tos_uri, and
resource_policy_uri might have multiple locale-specific metadata resource_policy_uri might have multiple locale-specific metadata
values to facilitate use in different locations. values to facilitate use in different locations.
To specify the languages and scripts, BCP 47 [RFC5646] language tags To specify the languages and scripts, language tags [BCP47] are added
are added to resource metadata parameter names, delimited by a # to resource metadata parameter names, delimited by a # character.
character. Since JSON [RFC8259] member names are case sensitive, it Since member names as discussed in JSON [RFC8259] are case sensitive,
is RECOMMENDED that language tag values used in Claim Names be it is RECOMMENDED that language tag values used in Claim Names be
spelled using the character case with which they are registered in spelled using the character case with which they are registered in
the "IANA Language Subtag" registry [IANA.Language]. In particular, the "Language Subtag Registry" [IANA.Language]. In particular,
normally language names are spelled with lowercase characters, region normally, language names are spelled with lowercase characters,
names are spelled with uppercase characters, and languages are region names are spelled with uppercase characters, and languages are
spelled with mixed-case characters. However, since BCP 47 language spelled with mixed-case characters. However, since language tag
tag values are case-insensitive, implementations SHOULD interpret the values are case insensitive per [BCP47], implementations SHOULD
language tag values supplied in a case insensitive manner. Per the interpret the language tag values supplied in a case-insensitive
recommendations in BCP 47, language tag values used in metadata manner. Per the recommendations in [BCP47], language tag values used
parameter names should only be as specific as necessary. For in metadata parameter names should only be as specific as is
instance, using fr might be sufficient in many contexts, rather than necessary. For instance, using fr might be sufficient in many
fr-CA or fr-FR. contexts, rather than fr-CA or fr-FR.
For example, a resource could represent its name in English as For example, a resource could represent its name in English as
"resource_name#en": "My Resource" and its name in Italian as "resource_name#en": "My Resource" and its name in Italian as
"resource_name#it": "La mia bella risorsa" within its metadata. Any "resource_name#it": "La mia bella risorsa" within its metadata. Any
or all of these names MAY be displayed to the end-user, choosing or all of these names MAY be displayed to the end user, choosing
which names to display based on system configuration, user which names to display based on system configuration, user
preferences, or other factors. preferences, or other factors.
If any human-readable field is sent without a language tag, parties If any human-readable field is sent without a language tag, parties
using it MUST NOT make any assumptions about the language, character using it MUST NOT make any assumptions about the language, character
set, or script of the string value, and the string value MUST be used set, or script of the string value, and the string value MUST be used
as is wherever it is presented in a user interface. To facilitate as is wherever it is presented in a user interface. To facilitate
interoperability, it is RECOMMENDED that each kind of human-readable interoperability, it is RECOMMENDED that each kind of human-readable
metadata provided includes an instance of its metadata parameter metadata provided include an instance of its metadata parameter
without any language tags in addition to any language-specific without any language tags in addition to any language-specific
parameters, and it is RECOMMENDED that any human-readable fields sent parameters, and it is RECOMMENDED that any human-readable fields sent
without language tags contain values suitable for display on a wide without language tags contain values suitable for display on a wide
variety of systems. variety of systems.
2.2. Signed Protected Resource Metadata 2.2. Signed Protected Resource Metadata
In addition to JSON elements, metadata values MAY also be provided as In addition to JSON elements, metadata values MAY also be provided as
a signed_metadata value, which is a JSON Web Token (JWT) [JWT] that a signed_metadata value, which is a JSON Web Token (JWT) [JWT] that
asserts metadata values about the protected resource as a bundle. A asserts metadata values about the protected resource as a bundle. A
set of metadata parameters that can be used in signed metadata as set of metadata parameters that can be used in signed metadata as
claims are defined in Section 2. The signed metadata MUST be claims are defined in Section 2. The signed metadata MUST be
digitally signed or MACed using JSON Web Signature (JWS) [JWS] and digitally signed or MACed (protected with a Message Authentication
MUST contain an iss (issuer) claim denoting the party attesting to Code) using a JSON Web Signature (JWS) [JWS] and MUST contain an iss
the claims in the signed metadata. Consumers of the metadata MAY (issuer) claim denoting the party attesting to the claims in the
ignore the signed metadata if they do not support this feature. If signed metadata. Consumers of the metadata MAY ignore the signed
the consumer of the metadata supports signed metadata, metadata metadata if they do not support this feature. If the consumer of the
values conveyed in the signed metadata MUST take precedence over the metadata supports signed metadata, metadata values conveyed in the
corresponding values conveyed using plain JSON elements. signed metadata MUST take precedence over the corresponding values
conveyed using plain JSON elements.
Signed metadata is included in the protected resource metadata JSON Signed metadata is included in the protected resource metadata JSON
object using this OPTIONAL metadata parameter: object using this OPTIONAL metadata parameter:
signed_metadata signed_metadata
A JWT containing metadata parameters about the protected resource A JWT containing metadata parameters about the protected resource
as claims. This is a string value consisting of the entire signed as claims. This is a string value consisting of the entire signed
JWT. A signed_metadata parameter SHOULD NOT appear as a claim in JWT. A signed_metadata parameter SHOULD NOT appear as a claim in
the JWT; it is RECOMMENDED to reject any metadata in which this the JWT; it is RECOMMENDED to reject any metadata in which this
occurs. occurs.
3. Obtaining Protected Resource Metadata 3. Obtaining Protected Resource Metadata
Protected resources supporting metadata MUST make a JSON document Protected resources supporting metadata MUST make a JSON document
containing metadata as specified in Section 2 available at a URL containing metadata as specified in Section 2 available at a URL
formed by inserting a well-known URI string into the protected formed by inserting a well-known URI string into the protected
resource's resource identifier between the host component and the resource's resource identifier between the host component and the
path and/or query components, if any. By default, the well-known URI path and/or query components, if any. By default, the well-known URI
string used is /.well-known/oauth-protected-resource. The syntax and string used is /.well-known/oauth-protected-resource. The syntax and
semantics of .well-known are defined in [RFC8615]. The well-known semantics of .well-known are defined in [RFC8615]. The well-known
URI path suffix used MUST be registered in the IANA "Well-Known URIs" URI path suffix used MUST be registered in the "Well-Known URIs"
registry [IANA.well-known]. Examples of this construction can be registry [IANA.well-known]. Examples of this construction can be
found in Section 3.1. found in Section 3.1.
The term "application", as used below (and as used in [RFC8414]), The term "application", as used below (and as used in [RFC8414]),
encompasses all the components used to accomplish the task for the encompasses all the components used to accomplish the task for the
use case. That can include OAuth clients, authorization servers, use case. That can include OAuth clients, authorization servers,
protected resources, and non-OAuth components, inclusive of the code protected resources, and non-OAuth components, inclusive of the code
running in each of them. Applications are built to solve particular running in each of them. Applications are built to solve particular
problems and may utilize many components and services. problems and may utilize many components and services.
Different applications utilizing OAuth protected resources in Different applications utilizing OAuth protected resources in
application-specific ways MAY define and register different well- application-specific ways MAY define and register different well-
known URI path suffixes for publishing protected resource metadata known URI path suffixes for publishing protected resource metadata
used by those applications. For instance, if the Example application used by those applications. For instance, if the Example application
uses an OAuth protected resource in an Example-specific way, and uses an OAuth protected resource in an Example-specific way and there
there are Example-specific metadata values that it needs to publish, are Example-specific metadata values that it needs to publish, then
then it might register and use the example-protected-resource URI it might register and use the example-protected-resource URI path
path suffix and publish the metadata document at the URL formed by suffix and publish the metadata document at the URL formed by
inserting /.well-known/example-protected-resource between the host inserting /.well-known/example-protected-resource between the host
and path and/or query components of the protected resource's resource and path and/or query components of the protected resource's resource
identifier. Alternatively, many such applications will use the identifier. Alternatively, many such applications will use the
default well-known URI string /.well-known/oauth-protected-resource, default well-known URI string /.well-known/oauth-protected-resource,
which is the right choice for general-purpose OAuth protected which is the right choice for general-purpose OAuth protected
resources, and not register an application-specific one. resources, and not register an application-specific one.
An OAuth 2.0 application using this specification MUST specify what An OAuth 2.0 application using this specification MUST specify what
well-known URI suffix it will use for this purpose. The same well-known URI suffix it will use for this purpose. The same
protected resource MAY choose to publish its metadata at multiple protected resource MAY choose to publish its metadata at multiple
well-known locations derived from its resource identifier, for well-known locations derived from its resource identifier -- for
example, publishing metadata at both /.well-known/example-protected- example, publishing metadata at both /.well-known/example-protected-
resource and /.well-known/oauth-protected-resource. resource and /.well-known/oauth-protected-resource.
3.1. Protected Resource Metadata Request 3.1. Protected Resource Metadata Request
A protected resource metadata document MUST be queried using an HTTP A protected resource metadata document MUST be queried using an HTTP
GET request at the previously specified URL. GET request at the previously specified URL.
The consumer of the metadata would make the following request when The consumer of the metadata would make the following request when
the resource identifier is https://resource.example.com and the well- the resource identifier is https://resource.example.com and the well-
known URI path suffix is oauth-protected-resource to obtain the known URI path suffix is oauth-protected-resource to obtain the
metadata, since the resource identifier contains no path component: metadata, since the resource identifier contains no path component:
GET /.well-known/oauth-protected-resource HTTP/1.1 GET /.well-known/oauth-protected-resource HTTP/1.1
Host: resource.example.com Host: resource.example.com
If the resource identifier value contains a path or query component, If the resource identifier value contains a path or query component,
any terminating / following the host component MUST be removed before any terminating slash (/) following the host component MUST be
inserting /.well-known/ and the well-known URI path suffix between removed before inserting /.well-known/ and the well-known URI path
the host component and the path and/or query components. The suffix between the host component and the path and/or query
consumer of the metadata would make the following request when the components. The consumer of the metadata would make the following
resource identifier is https://resource.example.com/resource1 and the request when the resource identifier is https://resource.example.com/
well-known URI path suffix is oauth-protected-resource to obtain the resource1 and the well-known URI path suffix is oauth-protected-
metadata, since the resource identifier contains a path component: resource to obtain the metadata, since the resource identifier
contains a path component:
GET /.well-known/oauth-protected-resource/resource1 HTTP/1.1 GET /.well-known/oauth-protected-resource/resource1 HTTP/1.1
Host: resource.example.com Host: resource.example.com
Using path components enables supporting multiple resources per host. Using path components enables supporting multiple resources per host.
This is required in some multi-tenant hosting configurations. This This is required in some multi-tenant hosting configurations. This
use of .well-known is for supporting multiple resources per host; use of .well-known is for supporting multiple resources per host;
unlike its use in [RFC8615], it does not provide general information unlike its use in [RFC8615], it does not provide general information
about the host. about the host.
skipping to change at page 12, line 10 skipping to change at line 500
specification defines the authorization server metadata parameter specification defines the authorization server metadata parameter
protected_resources, which enables the authorization server to protected_resources, which enables the authorization server to
explicitly list the protected resources. Note that if the set of explicitly list the protected resources. Note that if the set of
legitimate authorization servers to use with a protected resource is legitimate authorization servers to use with a protected resource is
also enumerable, lists in the authorization server metadata and also enumerable, lists in the authorization server metadata and
protected resource metadata should be cross-checked against one protected resource metadata should be cross-checked against one
another for consistency when these lists are used by the application another for consistency when these lists are used by the application
profile. profile.
The following authorization server metadata parameter is defined by The following authorization server metadata parameter is defined by
this specification and is registered in the IANA "OAuth Authorization this specification and is registered in the "OAuth Authorization
Server Metadata" registry established in OAuth 2.0 Authorization Server Metadata" registry established in "OAuth 2.0 Authorization
Server Metadata [RFC8414]. Server Metadata" [RFC8414].
protected_resources protected_resources
OPTIONAL. JSON array containing a list of resource identifiers OPTIONAL. JSON array containing a list of resource identifiers
for OAuth protected resources for protected resources that can be for OAuth protected resources that can be used with this
used with this authorization server. Authorization servers MAY authorization server. Authorization servers MAY choose not to
choose not to advertise some supported protected resources even advertise some supported protected resources even when this
when this parameter is used. In some use cases, the set of parameter is used. In some use cases, the set of protected
protected resources will not be enumerable, in which case this resources will not be enumerable, in which case this metadata
metadata parameter will not be present. parameter will not be present.
5. Use of WWW-Authenticate for Protected Resource Metadata 5. Use of WWW-Authenticate for Protected Resource Metadata
A protected resource MAY use the WWW-Authenticate [RFC9110] HTTP A protected resource MAY use the WWW-Authenticate HTTP response
response header field to return a URL to its protected resource header field, as discussed in [RFC9110], to return a URL to its
metadata to the client. The client can then retrieve protected protected resource metadata to the client. The client can then
resource metadata as described in Section 3. The client might then, retrieve protected resource metadata as described in Section 3. The
for instance, determine what authorization server to use for the client might then, for instance, determine what authorization server
resource based on protected resource metadata retrieved. to use for the resource based on protected resource metadata
retrieved.
A typical end-to-end flow doing so is as follows. Note that while A typical end-to-end flow doing so is as follows. Note that while
this example uses the OAuth 2.0 Authorization Code flow, a similar this example uses the OAuth 2.0 authorization code flow, a similar
sequence could also be implemented with any other OAuth flow. sequence could also be implemented with any other OAuth flow.
+----------+ +----------+ +---------------+ +----------+ +----------+ +---------------+
| Client | | Resource | | Authorization | | Client | | Resource | | Authorization |
| | | Server | | Server | | | | Server | | Server |
+----+-----+ +----+-----+ +-------+-------+ +----+-----+ +----+-----+ +-------+-------+
| | | | | |
| 1. Resource Request | | | 1. Resource Request | |
| ----------------------> | | | ----------------------> | |
| Without Access Token | | | Without Access Token | |
skipping to change at page 13, line 51 skipping to change at line 573
+-+-------------------------+------------------+-+ +-+-------------------------+------------------+-+
| | | | | |
| 10. Resource Request | | | 10. Resource Request | |
| ----------------------> | | | ----------------------> | |
| With Access Token | | | With Access Token | |
| | | | | |
| | | | | |
| 11. Resource Response | | | 11. Resource Response | |
| <---------------------- | | | <---------------------- | |
| | | | | |
+----+-----+ +----+-----+ +-------+-------+
| Client | | Resource | | Authorization |
| | | Server | | Server |
+----------+ +----------+ +---------------+
Figure 1: Sequence Diagram Figure 1: Sequence Diagram
1. The client makes a request to a protected resource without 1. The client makes a request to a protected resource without
presenting an access token. presenting an access token.
2. The resource server responds with a WWW-Authenticate header 2. The resource server responds with a WWW-Authenticate header
including the URL of the protected resource metadata. including the URL of the protected resource metadata.
3. The client fetches the protected resource metadata from this 3. The client fetches the protected resource metadata from this
URL. URL.
4. The resource server responds with the protected resource 4. The resource server responds with the protected resource
metadata according to Section 3.2. metadata according to Section 3.2.
5. The client validates the protected resource metadata, as 5. The client validates the protected resource metadata, as
described in Section 3.3. described in Section 3.3, and builds the authorization server
metadata URL from an issuer identifier in the resource metadata
according to [RFC8414].
6. The client builds the authorization server metadata URL from an 6. The client makes a request to fetch the authorization server
issuer identifier in the resource metadata according to
[RFC8414] and makes a request to fetch the authorization server
metadata. metadata.
7. The authorization server responds with the authorization server 7. The authorization server responds with the authorization server
metadata document according to [RFC8414]. metadata document according to [RFC8414].
8. The client directs the user agent to the authorization server to 8. The client directs the user agent to the authorization server to
begin the authorization flow. begin the authorization flow.
9. The authorization exchange is completed and the authorization 9. The authorization exchange is completed and the authorization
server returns an access token to the client. server returns an access token to the client.
skipping to change at page 15, line 5 skipping to change at line 626
This specification introduces a new parameter in the WWW-Authenticate This specification introduces a new parameter in the WWW-Authenticate
HTTP response header field to indicate the protected resource HTTP response header field to indicate the protected resource
metadata URL: metadata URL:
resource_metadata: resource_metadata:
The URL of the protected resource metadata. The URL of the protected resource metadata.
The response below is an example of a WWW-Authenticate header that The response below is an example of a WWW-Authenticate header that
includes the resource identifier. includes the resource identifier.
HTTP/1.1 400 Bad Request HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_request", WWW-Authenticate: Bearer resource_metadata=
error_description="No access token was provided in this request",
resource_metadata=
"https://resource.example.com/.well-known/oauth-protected-resource" "https://resource.example.com/.well-known/oauth-protected-resource"
The HTTP status code and error string in the example response above The HTTP status code in the example response above is defined by
are defined by [RFC6750]. [RFC6750].
This parameter MAY also be used in WWW-Authenticate responses using This parameter MAY also be used in WWW-Authenticate responses using
Authorization schemes other than Bearer [RFC6750], such as the DPoP authorization schemes other than "Bearer" [RFC6750], such as the DPoP
scheme defined by [RFC9449]. scheme defined by [RFC9449].
The resource_metadata parameter MAY be combined with other parameters The resource_metadata parameter MAY be combined with other parameters
defined in other extensions, such as the max_age parameter defined by defined in other extensions, such as the max_age parameter defined by
[RFC9470]. [RFC9470].
5.2. Changes to Resource Metadata 5.2. Changes to Resource Metadata
At any point, for any reason determined by the resource server, the At any point, for any reason determined by the resource server, the
protected resource MAY respond with a new WWW-Authenticate challenge protected resource MAY respond with a new WWW-Authenticate challenge
skipping to change at page 15, line 37 skipping to change at line 656
indicate that its metadata may have changed. If the client receives indicate that its metadata may have changed. If the client receives
such a WWW-Authenticate response, it SHOULD retrieve the updated such a WWW-Authenticate response, it SHOULD retrieve the updated
protected resource metadata and use the new metadata values obtained, protected resource metadata and use the new metadata values obtained,
after validating them as described in Section 3.3. Among other after validating them as described in Section 3.3. Among other
things, this enables a resource server to change which authorization things, this enables a resource server to change which authorization
servers it uses without any other coordination with clients. servers it uses without any other coordination with clients.
5.3. Client Identifier and Client Authentication 5.3. Client Identifier and Client Authentication
The way in which the client identifier is established at the The way in which the client identifier is established at the
authorization server is out of scope of this specification. authorization server is out of scope for this specification.
This specification is intended to be deployed in scenarios where the This specification is intended to be deployed in scenarios where the
client has no prior knowledge about the resource server, and the client has no prior knowledge about the resource server and where the
resource server might or might not have prior knowledge about the resource server might or might not have prior knowledge about the
client. client.
There are some existing methods by which an unrecognized client can There are some existing methods by which an unrecognized client can
make use of an authorization server, such as using Dynamic Client make use of an authorization server, such as using Dynamic Client
Registration [RFC7591] to register the client prior to initiating the Registration [RFC7591] to register the client prior to initiating the
authorization flow. Future OAuth extensions might define authorization flow. Future OAuth extensions might define
alternatives, such as using URLs to identify clients. alternatives, such as using URLs to identify clients.
5.4. Compatibility with Other Authentication Methods 5.4. Compatibility with Other Authentication Methods
Resource servers MAY return other WWW-Authenticate headers indicating Resource servers MAY return other WWW-Authenticate headers indicating
various authentication schemes. This allows the resource server to various authentication schemes. This allows the resource server to
support clients that may or may not implement this specification, and support clients that may or may not implement this specification and
allows clients to choose their preferred authentication scheme. allows clients to choose their preferred authentication scheme.
6. String Operations 6. String Operations
Processing some OAuth 2.0 messages requires comparing values in the Processing some OAuth 2.0 messages requires comparing values in the
messages to known values. For example, the member names in the messages to known values. For example, the member names in the
metadata response might be compared to specific member names such as metadata response might be compared to specific member names such as
resource. Comparing Unicode [UNICODE] strings, however, has resource. Comparing Unicode strings [UNICODE], however, has
significant security implications. significant security implications.
Therefore, comparisons between JSON strings and other Unicode strings Therefore, comparisons between JSON strings and other Unicode strings
MUST be performed as specified below: MUST be performed as specified below:
1. Remove any JSON applied escaping to produce an array of Unicode 1. Remove any JSON-applied escaping to produce an array of Unicode
code points. code points.
2. Unicode Normalization [USA15] MUST NOT be applied at any point to 2. Unicode Normalization [USA15] MUST NOT be applied at any point to
either the JSON string or to the string it is to be compared either the JSON string or the string it is to be compared
against. against.
3. Comparisons between the two strings MUST be performed as a 3. Comparisons between the two strings MUST be performed as a
Unicode code point to code point equality comparison. Unicode code-point-to-code-point equality comparison.
Note that this is the same equality comparison procedure described in Note that this is the same equality comparison procedure as that
Section 8.3 of [RFC8259]. described in Section 8.3 of [RFC8259].
7. Security Considerations 7. Security Considerations
7.1. TLS Requirements 7.1. TLS Requirements
Implementations MUST support TLS. They MUST follow the guidance in Implementations MUST support TLS. They MUST follow the guidance in
BCP 195 [RFC8996] [RFC9325], which provides recommendations and [BCP195], which provides recommendations and requirements for
requirements for improving the security of deployed services that use improving the security of deployed services that use TLS.
TLS.
Use of TLS at the protected resource metadata URLs protects against The use of TLS at the protected resource metadata URLs protects
information disclosure and tampering. against information disclosure and tampering.
7.2. Scopes 7.2. Scopes
The scopes_supported parameter is the list of scopes the resource The scopes_supported parameter is the list of scopes the resource
server is willing to disclose that it supports. It is not meant to server is willing to disclose that it supports. It is not meant to
indicate that an OAuth client should request all scopes in the list. indicate that an OAuth client should request all scopes in the list.
The client SHOULD still follow OAuth best practices and request The client SHOULD still follow OAuth best practices and request
tokens with as limited scope as possible for the given operation, as tokens with as limited a scope as possible for the given operation,
described in Section 2.3 of OAuth 2.0 Security Best Current Practice as described in Section 2.3 of "Best Current Practice for OAuth 2.0
[I-D.ietf-oauth-security-topics]. Security" [RFC9700].
7.3. Impersonation Attacks 7.3. Impersonation Attacks
TLS certificate checking MUST be performed by the client as described TLS certificate checking MUST be performed by the client as described
in [RFC9525] when making a protected resource metadata request. in [RFC9525] when making a protected resource metadata request.
Checking that the server certificate is valid for the resource Checking that the server certificate is valid for the resource
identifier URL prevents man-in-middle and DNS-based attacks. These identifier URL prevents adversary-in-the-middle and DNS-based
attacks could cause a client to be tricked into using an attacker's attacks. These attacks could cause a client to be tricked into using
resource server, which would enable impersonation of the legitimate an attacker's resource server, which would enable impersonation of
protected resource. If an attacker can accomplish this, they can the legitimate protected resource. If an attacker can accomplish
access the resources that the affected client has access to using the this, they can access the resources that the affected client has
protected resource that they are impersonating. access to, using the protected resource that they are impersonating.
An attacker may also attempt to impersonate a protected resource by An attacker may also attempt to impersonate a protected resource by
publishing a metadata document that contains a resource metadata publishing a metadata document that contains a resource metadata
parameter using the resource identifier URL of the protected resource parameter using the resource identifier URL of the protected resource
being impersonated, but containing information of the attacker's being impersonated but that contains information of the attacker's
choosing. This would enable it to impersonate that protected choosing. This would enable it to impersonate that protected
resource, if accepted by the client. To prevent this, the client resource, if accepted by the client. To prevent this, the client
MUST ensure that the resource identifier URL it is using as the MUST ensure that the resource identifier URL it is using as the
prefix for the metadata request exactly matches the value of the prefix for the metadata request exactly matches the value of the
resource metadata parameter in the protected resource metadata resource metadata parameter in the protected resource metadata
document received by the client, as described in Section 3.3. document received by the client, as described in Section 3.3.
7.4. Audience-Restricted Access Tokens 7.4. Audience-Restricted Access Tokens
If a client expects to interact with multiple resource servers, the If a client expects to interact with multiple resource servers, the
client SHOULD request audience-restricted access tokens using client SHOULD request audience-restricted access tokens using
[RFC8707], and the authorization server SHOULD support audience- [RFC8707], and the authorization server SHOULD support audience-
restricted access tokens. restricted access tokens.
Without audience-restricted access tokens, a malicious resource Without audience-restricted access tokens, a malicious resource
server (RS1) may be able to use the WWW-Authenticate header to get a server (RS1) may be able to use the WWW-Authenticate header to get a
client to request an access token with a scope used by a legitimate client to request an access token with a scope used by a legitimate
resource server (RS2), and after the client sends a request to RS1, resource server (RS2), and after the client sends a request to RS1,
then RS1 could re-use the access token at RS2. then RS1 could reuse the access token at RS2.
While this attack is not explicitly enabled by this specification, While this attack is not explicitly enabled by this specification and
and is possible in a plain OAuth 2.0 deployment, it is made somewhat is possible in a plain OAuth 2.0 deployment, it is made somewhat more
more likely by the use of dynamically-configured clients. As such, likely by the use of dynamically configured clients. As such, the
the use of audience-restricted access tokens and Resource Indicators use of audience-restricted access tokens and Resource Indicators
[RFC8707] is RECOMMENDED when using the features in this [RFC8707] is RECOMMENDED when using the features in this
specification. specification.
7.5. Publishing Metadata in a Standard Format 7.5. Publishing Metadata in a Standard Format
Publishing information about the protected resource in a standard Publishing information about the protected resource in a standard
format makes it easier for both legitimate clients and attackers to format makes it easier for both legitimate clients and attackers to
use the protected resource. Whether a protected resource publishes use the protected resource. Whether a protected resource publishes
its metadata in an ad-hoc manner or in the standard format defined by its metadata in an ad hoc manner or in the standard format defined by
this specification, the same defenses against attacks that might be this specification, the same defenses against attacks that might be
mounted that use this information should be applied. mounted that use this information should be applied.
7.6. Authorization Servers 7.6. Authorization Servers
To support use cases in which the set of legitimate authorization To support use cases in which the set of legitimate authorization
servers to use with the protected resource is enumerable, this servers to use with the protected resource is enumerable, this
specification defines the authorization_servers metadata parameter, specification defines the authorization_servers metadata parameter,
which enables explicitly listing them. Note that if the set of which enables explicitly listing them. Note that if the set of
legitimate protected resources to use with an authorization server is legitimate protected resources to use with an authorization server is
also enumerable, lists in the protected resource metadata and also enumerable, lists in the protected resource metadata and
authorization server metadata should be cross-checked against one authorization server metadata should be cross-checked against one
another for consistency when these lists are used by the application another for consistency when these lists are used by the application
profile. profile.
Secure determination of appropriate authorization servers to use with Secure determination of appropriate authorization servers to use with
a protected resource for all use cases is out of scope of this a protected resource for all use cases is out of scope for this
specification. This specification assumes that the client has a specification. This specification assumes that the client has a
means of determining appropriate authorization servers to use with a means of determining appropriate authorization servers to use with a
protected resource and that the client is using the correct metadata protected resource and that the client is using the correct metadata
for each protected resource. Implementers need to be aware that if for each protected resource. Implementers need to be aware that if
an inappropriate authorization server is used by the client, that an an inappropriate authorization server is used by the client, an
attacker may be able to act as a man-in-the-middle proxy to a valid attacker may be able to act as an adversary-in-the-middle proxy to a
authorization server without it being detected by the authorization valid authorization server without it being detected by the
server or the client. authorization server or the client.
The ways to determine the appropriate authorization servers to use The ways to determine the appropriate authorization servers to use
with a protected resource are in general, application-dependent. For with a protected resource are, in general, application dependent.
instance, some protected resources are used with a fixed For instance, some protected resources are used with a fixed
authorization server or set of authorization servers, the locations authorization server or a set of authorization servers, the locations
of which may be well known, or which could be published as metadata of which may be known via out-of-band mechanisms. Alternatively, as
values by the protected resource. In other cases, the set of described in this specification, the locations of the authorization
authorization servers that can be used with a protected resource can servers could be published by the protected resource as metadata
by dynamically changed by administrative actions or by changes to the values. In other cases, the set of authorization servers that can be
set of authorization servers adhering to a trust framework. Many used with a protected resource can be dynamically changed by
other means of determining appropriate associations between protected administrative actions or by changes to the set of authorization
resources and authorization servers are also possible. servers adhering to a trust framework. Many other means of
determining appropriate associations between protected resources and
authorization servers are also possible.
7.7. Server-Side Request Forgery (SSRF) 7.7. Server-Side Request Forgery (SSRF)
The OAuth client is expected to fetch the authorization server The OAuth client is expected to fetch the authorization server
metadata based on the value of the issuer in the resource server metadata based on the value of the issuer in the resource server
metadata. Since this specification enables clients to interoperate metadata. Since this specification enables clients to interoperate
with RSs and ASs it has no prior knowledge of, this opens a risk for with RSs and ASes it has no prior knowledge of, this opens a risk for
SSRF attacks by malicious users or malicious resource servers. Server-Side Request Forgery (SSRF) attacks by malicious users or
Clients SHOULD take appropriate precautions against SSRF attacks, malicious resource servers. Clients SHOULD take appropriate
such as blocking requests to internal IP address ranges. Further precautions against SSRF attacks, such as blocking requests to
recommendations can be found in the OWASP SSRF Prevention Cheat Sheet internal IP address ranges. Further recommendations can be found in
[OWASP.SSRF]. the Open Worldwide Application Security Project (OWASP) SSRF
Prevention Cheat Sheet [OWASP.SSRF].
7.8. Phishing 7.8. Phishing
This specification may be deployed in a scenario where the desired This specification may be deployed in a scenario where the desired
HTTP resource is identified by a user-selected URL. If this resource HTTP resource is identified by a user-selected URL. If this resource
is malicious or compromised, it could mislead the user into revealing is malicious or compromised, it could mislead the user into revealing
their account credentials or authorizing unwanted access to OAuth- their account credentials or authorizing unwanted access to OAuth-
controlled capabilities. This risk is reduced, but not eliminated, controlled capabilities. This risk is reduced, but not eliminated,
by following best practices for OAuth user interfaces, such as by following best practices for OAuth user interfaces, such as
providing clear notice to the user, displaying the authorization providing clear notice to the user, displaying the authorization
server's domain name, supporting origin-bound phishing-resistant server's domain name, supporting origin-bound phishing-resistant
authenticators, supporting the use of password managers, and applying authenticators, supporting the use of password managers, and applying
heuristic checks such as domain reputation. heuristic checks such as domain reputation.
7.9. Differences between Unsigned and Signed Metadata 7.9. Differences Between Unsigned and Signed Metadata
Unsigned metadata is integrity protected by use of TLS at the site Unsigned metadata is integrity protected by the use of TLS at the
where it is hosted. This means that its security is dependent upon site where it is hosted. This means that its security is dependent
the Internet Public Key Infrastructure (PKI) [RFC9525]. Signed upon the Internet Public Key Infrastructure using X.509 (PKIX), as
metadata is additionally integrity protected by the JWS signature described in [RFC9525]. Signed metadata is additionally integrity
applied by the issuer, which is not dependent upon the Internet PKI. protected by the JWS signature applied by the issuer, which is not
dependent upon the Internet PKI.
When using unsigned metadata, the party issuing the metadata is the When using unsigned metadata, the party issuing the metadata is the
protected resource itself, which is represented by the resource value protected resource itself, which is represented by the resource value
in the metadata. Whereas, when using signed metadata, the party in the metadata, whereas when using signed metadata, the party
issuing the metadata is represented by the iss (issuer) claim in the issuing the metadata is represented by the iss (issuer) claim in the
signed metadata. When using signed metadata, applications can make signed metadata. When using signed metadata, applications can make
trust decisions based on the issuer that performed the signing -- trust decisions based on the issuer that performed the signing --
information that is not available when using unsigned metadata. How information that is not available when using unsigned metadata. How
these trust decisions are made is out of scope for this these trust decisions are made is out of scope for this
specification. specification.
7.10. Metadata Caching 7.10. Metadata Caching
Protected resource metadata is retrieved using an HTTP GET request, Protected resource metadata is retrieved using an HTTP GET request,
as specified in Section 3.1. Normal HTTP caching behaviors apply, as specified in Section 3.1. Normal HTTP caching behaviors apply,
meaning that the GET may retrieve a cached copy of the content, meaning that the GET request may retrieve a cached copy of the
rather than the latest copy. Implementations should utlize HTTP content, rather than the latest copy. Implementations should utilize
caching directives such as Cache-Control with max-age, as defined in HTTP caching directives such as Cache-Control with max-age, as
[RFC7234], to enable caching of retrieved metadata for appropriate defined in [RFC9111], to enable caching of retrieved metadata for
time periods. appropriate time periods.
8. IANA Considerations 8. IANA Considerations
The following registration procedure is used for the registry Values are registered via Specification Required [RFC8126].
established by this specification. Registration requests should be sent to <oauth-ext-review@ietf.org>
to initiate a two-week review period. However, to allow for the
Values are registered on a Specification Required [RFC8126] basis allocation of values prior to publication of the final version of a
after a two-week review period on the oauth-ext-review@ietf.org specification, the designated experts may approve registration once
mailing list, on the advice of one or more Designated Experts. they are satisfied that the specification will be completed and
However, to allow for the allocation of values prior to publication published. However, if the specification is not completed and
of the final version of a specification, the Designated Experts may published in a timely manner, as determined by the designated
approve registration once they are satisfied that the specification experts, the designated experts may request that IANA withdraw the
will be completed and published. However, if the specification is registration.
not completed and published in a timely manner, as determined by the
Designated Experts, the Designated Experts may request that IANA
withdraw the registration.
Registration requests sent to the mailing list for review should use Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register OAuth Protected an appropriate subject (e.g., "Request to register OAuth Protected
Resource Metadata: example"). Resource Metadata: example").
Within the review period, the Designated Experts will either approve Within the review period, the designated experts will either approve
or deny the registration request, communicating this decision to the or deny the registration request, communicating this decision to the
review list and IANA. Denials should include an explanation and, if review list and IANA. Denials should include an explanation and, if
applicable, suggestions as to how to make the request successful. applicable, suggestions as to how to make the request successful. If
The IANA escalation process is followed when the Designated Experts the designated experts are not responsive, the registration
are not responsive within 14 days. requesters should contact IANA to escalate the process.
Criteria that should be applied by the Designated Experts includes Designated experts should apply the following criteria when reviewing
determining whether the proposed registration duplicates existing proposed registrations: They must be unique -- that is, they should
functionality, determining whether it is likely to be of general not duplicate existing functionality; they are likely generally
applicability or whether it is useful only for a single application, applicable, as opposed to being used for a single application; and
and whether the registration makes sense. they are clear and fit the purpose of the registry.
IANA must only accept registry updates from the Designated Experts IANA must only accept registry updates from the designated experts
and should direct all requests for registration to the review mailing and should direct all requests for registration to the review mailing
list. list.
It is suggested that multiple Designated Experts be appointed who are In order to enable broadly informed review of registration decisions,
able to represent the perspectives of different applications using there should be multiple designated experts to represent the
this specification, in order to enable broadly-informed review of perspectives of different applications using this specification. In
registration decisions. In cases where a registration decision could cases where registration may be perceived as a conflict of interest
be perceived as creating a conflict of interest for a particular for a particular expert, that expert should defer to the judgment of
Expert, that Expert should defer to the judgment of the other the other experts.
Experts.
The reason for the use of the mailing list is to enable public review The mailing list is used to enable public review of registration
of registration requests, enabling both Designated Experts and other requests, which enables both designated experts and other interested
interested parties to provide feedback on proposed registrations. parties to provide feedback on proposed registrations. Designated
The reason to allow the Designated Experts to allocate values prior experts may allocate values prior to publication of the final
to publication as a final specification is to enable giving authors specification. This allows authors to receive guidance from the
of specifications proposing registrations the benefit of review by designated experts early, so any identified issues can be fixed
the Designated Experts before the specification is completely done, before the final specification is published.
so that if problems are identified, the authors can iterate and fix
them before publication of the final specification.
8.1. OAuth Protected Resource Metadata Registry 8.1. OAuth Protected Resource Metadata Registry
This specification establishes the IANA "OAuth Protected Resource This specification establishes the "OAuth Protected Resource
Metadata" registry for OAuth 2.0 protected resource metadata names. Metadata" registry for OAuth 2.0 protected resource metadata names.
The registry records the protected resource metadata parameter and a The registry records the protected resource metadata parameter and a
reference to the specification that defines it. reference to the specification that defines it.
8.1.1. Registration Template 8.1.1. Registration Template
Metadata Name: Metadata Name:
The name requested (e.g., "resource"). This name is case- The name requested (e.g., "resource"). This name is case
sensitive. Names may not match other registered names in a case- sensitive. Names may not match other registered names in a case-
insensitive manner unless the Designated Experts state that there insensitive manner unless the designated experts state that there
is a compelling reason to allow an exception. is a compelling reason to allow an exception.
Metadata Description: Metadata Description:
Brief description of the metadata (e.g., "Resource identifier Brief description of the metadata (e.g., "Resource identifier
URL"). URL").
Change Controller: Change Controller:
For IETF stream RFCs, list the "IETF". For others, give the name For IETF Stream RFCs, list "IETF". For others, give the name of
of the responsible party. Other details (e.g., postal address, the responsible party. Other details (e.g., postal address, email
email address, home page URI) may also be included. address, home page URI) may also be included.
Specification Document(s): Specification Document(s):
Reference to the document or documents that specify the parameter, Reference to the document or documents that specify the parameter,
preferably including URIs that can be used to retrieve copies of preferably including URIs that can be used to retrieve copies of
the documents. An indication of the relevant sections may also be the documents. An indication of the relevant sections may also be
included but is not required. included but is not required.
8.1.2. Initial Registry Contents 8.1.2. Initial Registry Contents
* Metadata Name: resource Metadata Name: resource
* Metadata Description: Protected resource's resource identifier URL Metadata Description: Protected resource's resource identifier URL
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: authorization_servers Metadata Name: authorization_servers
* Metadata Description: JSON array containing a list of OAuth Metadata Description: JSON array containing a list of OAuth
authorization server issuer identifiers authorization server issuer identifiers
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: jwks_uri Metadata Name: jwks_uri
* Metadata Description: URL of the protected resource's JWK Set Metadata Description: URL of the protected resource's JWK Set
document document
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: scopes_supported Metadata Name: scopes_supported
* Metadata Description: JSON array containing a list of the OAuth Metadata Description: JSON array containing a list of the OAuth 2.0
2.0 scope values that are used in authorization requests to scope values that are used in authorization requests to request
request access to this protected resource access to this protected resource
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: bearer_methods_supported Metadata Name: bearer_methods_supported
* Metadata Description: JSON array containing a list of the OAuth Metadata Description: JSON array containing a list of the OAuth 2.0
2.0 Bearer Token presentation methods that this protected resource bearer token presentation methods that this protected resource
supports supports
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: resource_signing_alg_values_supported Metadata Name: resource_signing_alg_values_supported
* Metadata Description: JSON array containing a list of the JWS Metadata Description: JSON array containing a list of the JWS
signing algorithms (alg values) supported by the protected signing algorithms (alg values) supported by the protected
resource for signed content resource for signed content
Change Controller: IETF
Specification Document(s): Section 2 of RFC 9728
* Change Controller: IETF Metadata Name: resource_name
* Specification Document(s): Section 2 of [[ this specification ]] Metadata Description: Human-readable name of the protected resource
Change Controller: IETF
* Metadata Name: resource_name Specification Document(s): Section 2 of RFC 9728
* Metadata Description: Human-readable name of the protected
resource
* Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]]
* Metadata Name: resource_documentation Metadata Name: resource_documentation
* Metadata Description: URL of a page containing human-readable Metadata Description: URL of a page containing human-readable
information that developers might want or need to know when using information that developers might want or need to know when using
the protected resource the protected resource
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: resource_policy_uri Metadata Name: resource_policy_uri
* Metadata Description: URL of a page containing human-readable Metadata Description: URL of a page containing human-readable
information about the protected resource's requirements on how the information about the protected resource's requirements on how the
client can use the data provided by the protected resource client can use the data provided by the protected resource
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: resource_tos_uri Metadata Name: resource_tos_uri
* Metadata Description: URL of a page containing human-readable Metadata Description: URL of a page containing human-readable
information about the protected resource's terms of service information about the protected resource's terms of service
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: tls_client_certificate_bound_access_tokens Metadata Name: tls_client_certificate_bound_access_tokens
* Metadata Description: Boolean value indicating protected resource Metadata Description: Boolean value indicating protected resource
support for mutual-TLS client certificate-bound access tokens support for mutual-TLS client certificate-bound access tokens
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: authorization_details_types_supported Metadata Name: authorization_details_types_supported
* Metadata Description: JSON array containing a list of the Metadata Description: JSON array containing a list of the
authorization details type values supported by the resource server authorization details type values supported by the resource server
when the authorization_details request parameter is used when the authorization_details request parameter is used
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: dpop_signing_alg_values_supported Metadata Name: dpop_signing_alg_values_supported
* Metadata Description: JSON array containing a list of the JWS alg Metadata Description: JSON array containing a list of the JWS alg
values supported by the resource server for validating DPoP proof values supported by the resource server for validating DPoP proof
JWTs JWTs
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]] Specification Document(s): Section 2 of RFC 9728
* Metadata Name: dpop_bound_access_tokens_required
* Metadata Description: Boolean value specifying whether the
protected resource always requires the use of DPoP-bound access
tokens
* Change Controller: IETF
* Specification Document(s): Section 2 of [[ this specification ]]
* Metadata Name: signed_metadata Metadata Name: dpop_bound_access_tokens_required
* Metadata Description: Signed JWT containing metadata parameters Metadata Description: Boolean value specifying whether the protected
resource always requires the use of DPoP-bound access tokens
Change Controller: IETF
Specification Document(s): Section 2 of RFC 9728
Metadata Name: signed_metadata
Metadata Description: Signed JWT containing metadata parameters
about the protected resource as claims about the protected resource as claims
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 2.2 of [[ this specification ]] Specification Document(s): Section 2.2 of RFC 9728
8.2. OAuth Authorization Server Metadata Registry 8.2. OAuth Authorization Server Metadata Registry
The following authorization server metadata parameter is registered IANA has registered the following authorization server metadata
in the IANA "OAuth Authorization Server Metadata" registry parameter in the "OAuth Authorization Server Metadata" registry
established in OAuth 2.0 Authorization Server Metadata [RFC8414]. established in "OAuth 2.0 Authorization Server Metadata" [RFC8414].
8.2.1. Registry Contents 8.2.1. Registry Contents
* Metadata Name: protected_resources Metadata Name: protected_resources
* Metadata Description: JSON array containing a list of resource Metadata Description: JSON array containing a list of resource
identifiers for OAuth protected resources identifiers for OAuth protected resources
* Change Controller: IETF Change Controller: IETF
* Specification Document(s): Section 4 of [[ this specification ]] Specification Document(s): Section 4 of RFC 9728
8.3. Well-Known URI Registry 8.3. Well-Known URIs Registry
This specification registers the well-known URI defined in Section 3 This specification registers the well-known URI defined in Section 3
in the IANA "Well-Known URIs" registry [IANA.well-known]. in the "Well-Known URIs" registry [IANA.well-known].
8.3.1. Registry Contents 8.3.1. Registry Contents
* URI Suffix: oauth-protected-resource URI Suffix: oauth-protected-resource
* Reference: Section 3 of [[ this specification ]] Reference: Section 3 of RFC 9728
* Status: permanent Status: permanent
* Change Controller: IETF Change Controller: IETF
* Related Information: (none) Related Information: (none)
9. References 9. References
9.1. Normative References 9.1. Normative References
[BCP195] Best Current Practice 195,
<https://www.rfc-editor.org/info/bcp195>.
At the time of writing, this BCP comprises the following:
Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS
1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021,
<https://www.rfc-editor.org/info/rfc8996>.
Sheffer, Y., Saint-Andre, P., and T. Fossati,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November
2022, <https://www.rfc-editor.org/info/rfc9325>.
[BCP47] Best Current Practice 47,
<https://www.rfc-editor.org/info/bcp47>.
At the time of writing, this BCP comprises the following:
Phillips, A., Ed. and M. Davis, Ed., "Matching of Language
Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September
2006, <https://www.rfc-editor.org/info/rfc4647>.
Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[IANA.Language] [IANA.Language]
IANA, "Language Subtag Registry", IANA, "Language Subtag Registry",
<https://www.iana.org/assignments/language-subtag- <https://www.iana.org/assignments/language-subtag-
registry>. registry>.
[JWA] Jones, M.B., "JSON Web Algorithms (JWA)", RFC 7518, [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015, DOI 10.17487/RFC7518, May 2015,
<https://tools.ietf.org/html/rfc7518>. <https://www.rfc-editor.org/info/rfc7518>.
[JWE] Jones, M.B. and J. Hildebrand, "JSON Web Encryption [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
(JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015, RFC 7516, DOI 10.17487/RFC7516, May 2015,
<https://tools.ietf.org/html/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[JWK] Jones, M.B., "JSON Web Key (JWK)", RFC 7517, [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015, DOI 10.17487/RFC7517, May 2015,
<https://tools.ietf.org/html/rfc7517>. <https://www.rfc-editor.org/info/rfc7517>.
[JWS] Jones, M.B., Bradley, J., and N. Sakimura, "JSON Web [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://tools.ietf.org/html/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[JWT] Jones, M.B., Bradley, J., and N. Sakimura, "JSON Web Token [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://tools.ietf.org/html/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
RFC 6749, DOI 10.17487/RFC6749, October 2012, RFC 6749, DOI 10.17487/RFC6749, October 2012,
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, Framework: Bearer Token Usage", RFC 6750,
DOI 10.17487/RFC6750, October 2012, DOI 10.17487/RFC6750, October 2012,
<https://www.rfc-editor.org/info/rfc6750>. <https://www.rfc-editor.org/info/rfc6750>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>.
[RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and
P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol",
RFC 7591, DOI 10.17487/RFC7591, July 2015, RFC 7591, DOI 10.17487/RFC7591, July 2015,
<https://www.rfc-editor.org/info/rfc7591>. <https://www.rfc-editor.org/info/rfc7591>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
skipping to change at page 26, line 38 skipping to change at line 1175
[RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T. [RFC8705] Campbell, B., Bradley, J., Sakimura, N., and T.
Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication
and Certificate-Bound Access Tokens", RFC 8705, and Certificate-Bound Access Tokens", RFC 8705,
DOI 10.17487/RFC8705, February 2020, DOI 10.17487/RFC8705, February 2020,
<https://www.rfc-editor.org/info/rfc8705>. <https://www.rfc-editor.org/info/rfc8705>.
[RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource [RFC8707] Campbell, B., Bradley, J., and H. Tschofenig, "Resource
Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707, Indicators for OAuth 2.0", RFC 8707, DOI 10.17487/RFC8707,
February 2020, <https://www.rfc-editor.org/info/rfc8707>. February 2020, <https://www.rfc-editor.org/info/rfc8707>.
[RFC8996] Moriarty, K. and S. Farrell, "Deprecating TLS 1.0 and TLS
1.1", BCP 195, RFC 8996, DOI 10.17487/RFC8996, March 2021,
<https://www.rfc-editor.org/info/rfc8996>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110, Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
[RFC9325] Sheffer, Y., Saint-Andre, P., and T. Fossati, [RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
"Recommendations for Secure Use of Transport Layer Ed., "HTTP Caching", STD 98, RFC 9111,
Security (TLS) and Datagram Transport Layer Security DOI 10.17487/RFC9111, June 2022,
(DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November <https://www.rfc-editor.org/info/rfc9111>.
2022, <https://www.rfc-editor.org/info/rfc9325>.
[RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", RFC 9396, Rich Authorization Requests", RFC 9396,
DOI 10.17487/RFC9396, May 2023, DOI 10.17487/RFC9396, May 2023,
<https://www.rfc-editor.org/info/rfc9396>. <https://www.rfc-editor.org/info/rfc9396>.
[RFC9449] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., [RFC9449] Fett, D., Campbell, B., Bradley, J., Lodderstedt, T.,
Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of
Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449,
September 2023, <https://www.rfc-editor.org/info/rfc9449>. September 2023, <https://www.rfc-editor.org/info/rfc9449>.
[RFC9525] Saint-Andre, P. and R. Salz, "Service Identity in TLS", [RFC9525] Saint-Andre, P. and R. Salz, "Service Identity in TLS",
RFC 9525, DOI 10.17487/RFC9525, November 2023, RFC 9525, DOI 10.17487/RFC9525, November 2023,
<https://www.rfc-editor.org/info/rfc9525>. <https://www.rfc-editor.org/info/rfc9525>.
[UNICODE] The Unicode Consortium, "The Unicode Standard", [UNICODE] The Unicode Consortium, "The Unicode Standard",
<https://www.unicode.org/versions/latest/>. <https://www.unicode.org/versions/latest/>.
[USA15] Davis, M. and K. Whistler, "Unicode Normalization Forms", [USA15] Whistler, K., Ed., "Unicode Normalization Forms", Unicode
Unicode Standard Annex 15, 1 June 2015, Standard Annex #15, 14 August 2024,
<https://www.unicode.org/reports/tr15/>. <https://www.unicode.org/reports/tr15/>.
9.2. Informative References 9.2. Informative References
[FAPI.MessageSigning] [FAPI.MessageSigning]
Tonge, D. and D. Fett, "FAPI 2.0 Message Signing", 24 Tonge, D. and D. Fett, "FAPI 2.0 Message Signing (Draft)",
March 2023, 24 March 2023,
<https://openid.net/specs/fapi-2_0-message-signing.html>. <https://openid.net/specs/fapi-2_0-message-signing.html>.
[I-D.ietf-oauth-security-topics]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"OAuth 2.0 Security Best Current Practice", Work in
Progress, Internet-Draft, draft-ietf-oauth-security-
topics-29, 3 June 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-oauth-
security-topics-29>.
[IANA.JOSE] [IANA.JOSE]
IANA, "JSON Object Signing and Encryption (JOSE)", IANA, "JSON Web Signature and Encryption Algorithms",
<https://www.iana.org/assignments/jose>. <https://www.iana.org/assignments/jose>.
[IANA.well-known] [IANA.well-known]
IANA, "Well-Known URIs", IANA, "Well-Known URIs",
<https://www.iana.org/assignments/well-known-uris>. <https://www.iana.org/assignments/well-known-uris>.
[OpenID.Discovery] [OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M.B., and E. Jay, Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
"OpenID Connect Discovery 1.0", 15 December 2023, Connect Discovery 1.0 incorporating errata set 2", 15
<https://openid.net/specs/openid-connect-discovery- December 2023, <https://openid.net/specs/openid-connect-
1_0.html>. discovery-1_0.html>.
[OWASP.SSRF] [OWASP.SSRF]
OWASP, "OWASP SSRF Prevention Cheat Sheet", OWASP Foundation, "OWASP Server-Side Request Forgery
Prevention Cheat Sheet",
<https://cheatsheetseries.owasp.org/cheatsheets/ <https://cheatsheetseries.owasp.org/cheatsheets/
Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html>. Server_Side_Request_Forgery_Prevention_Cheat_Sheet.html>.
[RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr,
"WebFinger", RFC 7033, DOI 10.17487/RFC7033, September "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September
2013, <https://www.rfc-editor.org/info/rfc7033>. 2013, <https://www.rfc-editor.org/info/rfc7033>.
[RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application [RFC8620] Jenkins, N. and C. Newman, "The JSON Meta Application
Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July Protocol (JMAP)", RFC 8620, DOI 10.17487/RFC8620, July
2019, <https://www.rfc-editor.org/info/rfc8620>. 2019, <https://www.rfc-editor.org/info/rfc8620>.
[RFC9470] Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up [RFC9470] Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up
Authentication Challenge Protocol", RFC 9470, Authentication Challenge Protocol", RFC 9470,
DOI 10.17487/RFC9470, September 2023, DOI 10.17487/RFC9470, September 2023,
<https://www.rfc-editor.org/info/rfc9470>. <https://www.rfc-editor.org/info/rfc9470>.
Appendix A. Acknowledgements [RFC9700] Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett,
"Best Current Practice for OAuth 2.0 Security", BCP 240,
RFC 9700, DOI 10.17487/RFC9700, January 2025,
<https://www.rfc-editor.org/info/rfc9700>.
Acknowledgements
The authors of this specification would like to thank the attendees The authors of this specification would like to thank the attendees
of the IETF 115 OAuth and HTTP API Working Group meetings and the of the IETF 115 OAuth and HTTP API Working Group meetings and the
attendees of subsequent OAuth Working Group meetings for their input attendees of subsequent OAuth Working Group meetings for their input
on this specification. We would would also like to thank Amanda on this specification. We would also like to thank Amanda Baber,
Baber, Mike Bishop, Ralph Bragg, Brian Campbell, Deb Cooley, Roman Mike Bishop, Ralph Bragg, Brian Campbell, Deb Cooley, Gabriel Corona,
Danyliw, Gabriel Corona, Vladimir Dzhuvinov, George Fletcher, Arnt Roman Danyliw, Vladimir Dzhuvinov, George Fletcher, Arnt Gulbrandsen,
Gulbrandsen, Pieter Kasselman, Murray Kucherawy, David Mandelberg, Pieter Kasselman, Murray Kucherawy, David Mandelberg, Tony Nadalin,
Tony Nadalin, Francesca Palombini, John Scudder, Rifaat Shekh-Yusef, Francesca Palombini, John Scudder, Rifaat Shekh-Yusef, Filip Skokan,
Filip Skokan, Orie Steele, Atul Tulshibagwale, Éric Vyncke, Paul Orie Steele, Atul Tulshibagwale, Éric Vyncke, Paul Wouters, and Bo Wu
Wouters, and Bo Wu for their contributions to the specification. for their contributions to the specification.
Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]]
-13
* Described motivations for the IANA registration procedure, per
additional comments by Murray Kucherawy.
-12
* Incorporated responses to IESG review comments by John Scudder,
Murray Kucherawy, Francesca Palombini, and Éric Vyncke. The IANA
registration procedure was updated per the discussion on the IESG
telechat.
-11
* Incorporated responses to HttpDir review comments by Mike Bishop.
* Incorporated responses to IESG review comments by Roman Danyliw.
* Incorporated responses to IESG review comments by Orie Steele.
Particularly, the specification now allows resource identifiers to
contain a query component (but still discourages it).
* Consistently use the term "metadata parameter". The terms
"metadata value" and "claim" were previously inconsistently used
for the same thing.
-10
* Added metadata parameter declaring RAR types supported.
-09
* Added metadata values declaring support for DPoP and mutual-TLS
client certificate-bound access tokens.
* Added missing word caught during IANA review.
* Addressed ART, SecDir, and OpsDir review comments by Arnt
Gulbrandsen, David Mandelberg, and Bo Wu, resulting in the
following changes.
* Added step numbers to sequence diagram.
* Defined meaning of omitting bearer_methods_supported metadata
parameter.
* Added internationalization of human-readable metadata values using
the mechanism from [RFC7591].
* Added resource_name metadata parameter, paralleling client_name in
[RFC7591].
* Added Security Considerations section on metadata caching.
* Used and referenced Resource Identifier definition.
* Added motivating example of an email client to intro.
-08
* Added Security Considerations about the differences between
unsigned and signed metadata, as suggested by Deb Cooley.
* Updated obsolete references.
-07
* Removed extraneous paragraph about downgrade attacks discussing an
issue that's already addressed elsewhere in the specification.
-06
* Addressed shepherd review comments by Rifaat Shekh-Yusef.
-05
* Added SVG diagram
-04
* Applied working group last call suggestions by Atul Tulshibagwale.
* Better described the purpose of
resource_signing_alg_values_supported and removed
resource_encryption_alg_values_supported and
resource_encryption_enc_values_supported, per WGLC comments by
Vladimir Dzhuvinov and Brian Campbell.
* Applied suggestions by Pieter Kasselman.
-03
* Applied correction by Filip Skokan.
-02
* Switched from concatenating .well-known to the end of the resource
identifier to inserting it between the host and path components of
it.
* Have WWW-Authenticate return resource_metadata rather than
resource.
-01
* Renamed scopes_provided to scopes_supported.
* Added security consideration for scopes_supported.
* Use BCP 195 for TLS recommendations.
* Clarified that resource metadata can be used by clients and
authorization servers.
* Updated references.
* Added security consideration recommending audience-restricted
access tokens.
* Mention FAPI Message Signing as a use case for publishing signing
keys.
-00
* Initial working group version based on draft-jones-oauth-resource-
metadata-04.
Authors' Addresses Authors' Addresses
Michael B. Jones Michael B. Jones
Self-Issued Consulting Self-Issued Consulting
Email: michael_b_jones@hotmail.com Email: michael_b_jones@hotmail.com
URI: https://self-issued.info/ URI: https://self-issued.info/
Phil Hunt Phil Hunt
Independent Identity, Inc. Independent Identity, Inc.
 End of changes. 139 change blocks. 
565 lines changed or deleted 441 lines changed or added

This html diff was produced by rfcdiff 1.48.