draft-ietf-oauth-discovery-10.txt   rfc8414.txt 
OAuth Working Group M. Jones Internet Engineering Task Force (IETF) M. Jones
Internet-Draft Microsoft Request for Comments: 8414 Microsoft
Intended status: Standards Track N. Sakimura Category: Standards Track N. Sakimura
Expires: September 5, 2018 NRI ISSN: 2070-1721 NRI
J. Bradley J. Bradley
Ping Identity Yubico
March 4, 2018 June 2018
OAuth 2.0 Authorization Server Metadata OAuth 2.0 Authorization Server Metadata
draft-ietf-oauth-discovery-10
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
can use to obtain the information needed to interact with an OAuth can use to obtain the information needed to interact with an
2.0 authorization server, including its endpoint locations and OAuth 2.0 authorization server, including its endpoint locations and
authorization server capabilities. authorization server capabilities.
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 September 5, 2018. 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/rfc8414.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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 Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction ....................................................2
1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.1. Requirements Notation and Conventions ......................3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Terminology ................................................3
2. Authorization Server Metadata . . . . . . . . . . . . . . . . 4 2. Authorization Server Metadata ...................................4
2.1. Signed Authorization Server Metadata . . . . . . . . . . 7 2.1. Signed Authorization Server Metadata .......................8
3. Obtaining Authorization Server Metadata . . . . . . . . . . . 8 3. Obtaining Authorization Server Metadata .........................8
3.1. Authorization Server Metadata Request . . . . . . . . . . 9 3.1. Authorization Server Metadata Request ......................9
3.2. Authorization Server Metadata Response . . . . . . . . . 9 3.2. Authorization Server Metadata Response ....................10
3.3. Authorization Server Metadata Validation . . . . . . . . 10 3.3. Authorization Server Metadata Validation ..................11
4. String Operations . . . . . . . . . . . . . . . . . . . . . . 11 4. String Operations ..............................................11
5. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 11 5. Compatibility Notes ............................................11
6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 6. Security Considerations ........................................12
6.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . 12 6.1. TLS Requirements ..........................................12
6.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 12 6.2. Impersonation Attacks .....................................12
6.3. Publishing Metadata in a Standard Format . . . . . . . . 13 6.3. Publishing Metadata in a Standard Format ..................13
6.4. Protected Resources . . . . . . . . . . . . . . . . . . . 13 6.4. Protected Resources .......................................13
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 7. IANA Considerations ............................................14
7.1. OAuth Authorization Server Metadata Registry . . . . . . 14 7.1. OAuth Authorization Server Metadata Registry ..............14
7.1.1. Registration Template . . . . . . . . . . . . . . . . 15 7.1.1. Registration Template ..............................15
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 15 7.1.2. Initial Registry Contents ..........................16
7.2. Updated Registration Instructions . . . . . . . . . . . . 18 7.2. Updated Registration Instructions .........................19
7.3. Well-Known URI Registry . . . . . . . . . . . . . . . . . 19 7.3. Well-Known URI Registry ...................................19
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 19 7.3.1. Registry Contents ..................................19
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 8. References .....................................................20
8.1. Normative References . . . . . . . . . . . . . . . . . . 19 8.1. Normative References ......................................20
8.2. Informative References . . . . . . . . . . . . . . . . . 21 8.2. Informative References ....................................22
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 22 Acknowledgements ..................................................23
Appendix B. Document History . . . . . . . . . . . . . . . . . . 22 Authors' Addresses ................................................23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
This specification generalizes the metadata format defined by "OpenID This specification generalizes the metadata format defined by "OpenID
Connect Discovery 1.0" [OpenID.Discovery] in a way that is compatible Connect Discovery 1.0" [OpenID.Discovery] in a way that is compatible
with OpenID Connect Discovery, while being applicable to a wider set with OpenID Connect Discovery while being applicable to a wider set
of OAuth 2.0 use cases. This is intentionally parallel to the way of OAuth 2.0 use cases. This is intentionally parallel to the way
that the "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591] that "OAuth 2.0 Dynamic Client Registration Protocol" [RFC7591]
specification generalized the dynamic client registration mechanisms generalized the dynamic client registration mechanisms defined by
defined by "OpenID Connect Dynamic Client Registration 1.0" "OpenID Connect Dynamic Client Registration 1.0"
[OpenID.Registration] in a way that was compatible with it. [OpenID.Registration] in a way that is compatible with it.
The metadata for an authorization server is retrieved from a well- The metadata for an authorization server is retrieved from a well-
known location as a JSON [RFC7159] document, which declares its known location as a JSON [RFC8259] document, which declares its
endpoint locations and authorization server capabilities. This endpoint locations and authorization server capabilities. This
process is described in Section 3. 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
by the server origin via HTTPS or as a set of signed metadata values by the server origin via HTTPS or as a set of signed metadata values
represented as claims in a JSON Web Token (JWT) [JWT]. In the JWT represented as claims in a JSON Web Token (JWT) [JWT]. In the JWT
case, the issuer is vouching for the validity of the data about the case, the issuer is vouching for the validity of the data about the
authorization server. This is analogous to the role that the authorization server. This is analogous to the role that the
Software Statement plays in OAuth Dynamic Client Registration Software Statement plays in OAuth Dynamic Client Registration
[RFC7591]. [RFC7591].
The means by which the client chooses an authorization server is out The means by which the client chooses an authorization server is out
of scope. In some cases, its issuer identifier may be manually of scope. In some cases, its issuer identifier may be manually
configured into the client. In other cases, it may be dynamically configured into the client. In other cases, it may be dynamically
discovered, for instance, through the use of WebFinger [RFC7033], as discovered, for instance, through the use of WebFinger [RFC7033], as
described in Section 2 of "OpenID Connect Discovery 1.0" described in Section 2 of "OpenID Connect Discovery 1.0"
[OpenID.Discovery]. [OpenID.Discovery].
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 uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption
(JWE) [JWE] data structures in this specification utilize the JWS (JWE) [JWE] data structures in this specification utilize the JWS
Compact Serialization or the JWE Compact Serialization; the JWS JSON Compact Serialization or the JWE Compact Serialization; the JWS JSON
Serialization and the JWE JSON Serialization are not used. Serialization and the JWE JSON Serialization are not used.
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 Endpoint", "Authorization Grant",
"Authorization Server", "Client", "Client Authentication", "Client "Authorization Server", "Client", "Client Authentication", "Client
Identifier", "Client Secret", "Grant Type", "Protected Resource", Identifier", "Client Secret", "Grant Type", "Protected Resource",
"Redirection URI", "Refresh Token", "Resource Owner", "Resource "Redirection URI", "Refresh Token", "Resource Owner", "Resource
Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0
[RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token [RFC6749]; the terms "Claim Name", "Claim Value", and "JSON Web Token
(JWT)" defined by JSON Web Token (JWT) [JWT], and the term "Response (JWT)" defined by JSON Web Token (JWT) [JWT]; and the term "Response
Mode" defined by OAuth 2.0 Multiple Response Type Encoding Practices Mode" defined by "OAuth 2.0 Multiple Response Type Encoding
[OAuth.Responses]. Practices" [OAuth.Responses].
2. Authorization Server Metadata 2. Authorization Server Metadata
Authorization servers can have metadata describing their Authorization servers can have metadata describing their
configuration. The following authorization server metadata values configuration. The following authorization server metadata values
are used by this specification and are registered in the IANA "OAuth are used by this specification and are registered in the IANA "OAuth
Authorization Server Metadata" registry established in Section 7.1: Authorization Server Metadata" registry established in Section 7.1:
issuer issuer
REQUIRED. The authorization server's issuer identifier, which is REQUIRED. The authorization server's issuer identifier, which is
a URL that uses the "https" scheme and has no query or fragment a URL that uses the "https" scheme and has no query or fragment
components. Authorization server metadata is published at a components. Authorization server metadata is published at a
".well-known" RFC 5785 [RFC5785] location derived from this issuer location that is ".well-known" according to RFC 5785 [RFC5785]
identifier, as described in Section 3. The issuer identifier is derived from this issuer identifier, as described in Section 3.
used to prevent authorization server mix-up attacks, as described The issuer identifier is used to prevent authorization server mix-
in "OAuth 2.0 Mix-Up Mitigation" up attacks, as described in "OAuth 2.0 Mix-Up Mitigation"
[I-D.ietf-oauth-mix-up-mitigation]. [MIX-UP].
authorization_endpoint authorization_endpoint
URL of the authorization server's authorization endpoint URL of the authorization server's authorization endpoint
[RFC6749]. This is REQUIRED unless no grant types are supported [RFC6749]. This is REQUIRED unless no grant types are supported
that use the authorization endpoint. that use the authorization endpoint.
token_endpoint token_endpoint
URL of the authorization server's token endpoint [RFC6749]. This URL of the authorization server's token endpoint [RFC6749]. This
is REQUIRED unless only the implicit grant type is supported. is REQUIRED unless only the implicit grant type is supported.
jwks_uri jwks_uri
OPTIONAL. URL of the authorization server's JWK Set [JWK] OPTIONAL. URL of the authorization server's JWK Set [JWK]
document. The referenced document contains the signing key(s) the document. The referenced document contains the signing key(s) the
client uses to validate signatures from the authorization server. client uses to validate signatures from the authorization server.
This URL MUST use the "https" scheme. The JWK Set MAY also This URL MUST use the "https" scheme. The JWK Set MAY also
contain the server's encryption key(s), which are used by clients contain the server's encryption key or keys, which are used by
to encrypt requests to the server. When both signing and clients to encrypt requests to the server. When both signing and
encryption keys are made available, a "use" (public key use) encryption keys are made available, a "use" (public key use)
parameter value is REQUIRED for all keys in the referenced JWK Set parameter value is REQUIRED for all keys in the referenced JWK Set
to indicate each key's intended usage. to indicate each key's intended usage.
registration_endpoint registration_endpoint
OPTIONAL. URL of the authorization server's OAuth 2.0 Dynamic OPTIONAL. URL of the authorization server's OAuth 2.0 Dynamic
Client Registration endpoint [RFC7591]. Client Registration endpoint [RFC7591].
scopes_supported scopes_supported
RECOMMENDED. JSON array containing a list of the OAuth 2.0 RECOMMENDED. JSON array containing a list of the OAuth 2.0
skipping to change at page 5, line 13 skipping to change at page 5, line 15
response_types_supported response_types_supported
REQUIRED. JSON array containing a list of the OAuth 2.0 REQUIRED. JSON array containing a list of the OAuth 2.0
"response_type" values that this authorization server supports. "response_type" values that this authorization server supports.
The array values used are the same as those used with the The array values used are the same as those used with the
"response_types" parameter defined by "OAuth 2.0 Dynamic Client "response_types" parameter defined by "OAuth 2.0 Dynamic Client
Registration Protocol" [RFC7591]. Registration Protocol" [RFC7591].
response_modes_supported response_modes_supported
OPTIONAL. JSON array containing a list of the OAuth 2.0 OPTIONAL. JSON array containing a list of the OAuth 2.0
"response_mode" values that this authorization server supports, as "response_mode" values that this authorization server supports, as
specified in OAuth 2.0 Multiple Response Type Encoding Practices specified in "OAuth 2.0 Multiple Response Type Encoding Practices"
[OAuth.Responses]. If omitted, the default is "["query", [OAuth.Responses]. If omitted, the default is "["query",
"fragment"]". The response mode value "form_post" is also defined "fragment"]". The response mode value "form_post" is also defined
in OAuth 2.0 Form Post Response Mode [OAuth.Post]. in "OAuth 2.0 Form Post Response Mode" [OAuth.Post].
grant_types_supported grant_types_supported
OPTIONAL. JSON array containing a list of the OAuth 2.0 grant OPTIONAL. JSON array containing a list of the OAuth 2.0 grant
type values that this authorization server supports. The array type values that this authorization server supports. The array
values used are the same as those used with the "grant_types" values used are the same as those used with the "grant_types"
parameter defined by "OAuth 2.0 Dynamic Client Registration parameter defined by "OAuth 2.0 Dynamic Client Registration
Protocol" [RFC7591]. If omitted, the default value is Protocol" [RFC7591]. If omitted, the default value is
"["authorization_code", "implicit"]". "["authorization_code", "implicit"]".
token_endpoint_auth_methods_supported token_endpoint_auth_methods_supported
skipping to change at page 6, line 7 skipping to change at page 6, line 10
service_documentation service_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
authorization server. In particular, if the authorization server authorization server. In particular, if the authorization server
does not support Dynamic Client Registration, then information on does not support Dynamic Client Registration, then information on
how to register clients needs to be provided in this how to register clients needs to be provided in this
documentation. documentation.
ui_locales_supported ui_locales_supported
OPTIONAL. Languages and scripts supported for the user interface, OPTIONAL. Languages and scripts supported for the user interface,
represented as a JSON array of BCP47 [RFC5646] language tag represented as a JSON array of language tag values from BCP 47
values. If omitted, the set of supported languages and scripts is [RFC5646]. If omitted, the set of supported languages and scripts
unspecified. is unspecified.
op_policy_uri op_policy_uri
OPTIONAL. URL that the authorization server provides to the OPTIONAL. URL that the authorization server provides to the
person registering the client to read about the authorization person registering the client to read about the authorization
server's requirements on how the client can use the data provided server's requirements on how the client can use the data provided
by the authorization server. The registration process SHOULD by the authorization server. The registration process SHOULD
display this URL to the person registering the client if it is display this URL to the person registering the client if it is
given. As described in Section 5, despite the identifier given. As described in Section 5, despite the identifier
"op_policy_uri", appearing to be OpenID-specific, its usage in "op_policy_uri" appearing to be OpenID-specific, its usage in this
this specification is actually referring to a general OAuth 2.0 specification is actually referring to a general OAuth 2.0 feature
feature that is not specific to OpenID Connect. that is not specific to OpenID Connect.
op_tos_uri op_tos_uri
OPTIONAL. URL that the authorization server provides to the OPTIONAL. URL that the authorization server provides to the
person registering the client to read about the authorization person registering the client to read about the authorization
server's terms of service. The registration process SHOULD server's terms of service. The registration process SHOULD
display this URL to the person registering the client if it is display this URL to the person registering the client if it is
given. As described in Section 5, despite the identifier given. As described in Section 5, despite the identifier
"op_tos_uri", appearing to be OpenID-specific, its usage in this "op_tos_uri", appearing to be OpenID-specific, its usage in this
specification is actually referring to a general OAuth 2.0 feature specification is actually referring to a general OAuth 2.0 feature
that is not specific to OpenID Connect. that is not specific to OpenID Connect.
skipping to change at page 7, line 34 skipping to change at page 7, line 38
algorithms ("alg" values) supported by the introspection endpoint algorithms ("alg" values) supported by the introspection endpoint
for the signature on the JWT [JWT] used to authenticate the client for the signature on the JWT [JWT] used to authenticate the client
at the introspection endpoint for the "private_key_jwt" and at the introspection endpoint for the "private_key_jwt" and
"client_secret_jwt" authentication methods. This metadata entry "client_secret_jwt" authentication methods. This metadata entry
MUST be present if either of these authentication methods are MUST be present if either of these authentication methods are
specified in the "introspection_endpoint_auth_methods_supported" specified in the "introspection_endpoint_auth_methods_supported"
entry. No default algorithms are implied if this entry is entry. No default algorithms are implied if this entry is
omitted. The value "none" MUST NOT be used. omitted. The value "none" MUST NOT be used.
code_challenge_methods_supported code_challenge_methods_supported
OPTIONAL. JSON array containing a list of PKCE [RFC7636] code OPTIONAL. JSON array containing a list of Proof Key for Code
challenge methods supported by this authorization server. Code Exchange (PKCE) [RFC7636] code challenge methods supported by this
challenge method values are used in the "code_challenge_method" authorization server. Code challenge method values are used in
parameter defined in Section 4.3 of [RFC7636]. The valid code the "code_challenge_method" parameter defined in Section 4.3 of
challenge method values are those registered in the IANA "PKCE [RFC7636]. The valid code challenge method values are those
Code Challenge Methods" registry [IANA.OAuth.Parameters]. If registered in the IANA "PKCE Code Challenge Methods" registry
omitted, the authorization server does not support PKCE. [IANA.OAuth.Parameters]. If omitted, the authorization server
does not support PKCE.
Additional authorization server metadata parameters MAY also be used. Additional authorization server metadata parameters MAY also be used.
Some are defined by other specifications, such as OpenID Connect Some are defined by other specifications, such as OpenID Connect
Discovery 1.0 [OpenID.Discovery]. Discovery 1.0 [OpenID.Discovery].
2.1. Signed Authorization Server Metadata 2.1. Signed Authorization Server 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 authorization server as a bundle. asserts metadata values about the authorization server as a bundle.
A set of claims that can be used in signed metadata are defined in A set of claims that can be used in signed metadata is defined in
Section 2. The signed metadata MUST be digitally signed or MACed Section 2. The signed metadata MUST be digitally signed or MACed
using JSON Web Signature (JWS) [JWS] and MUST contain an "iss" using JSON Web Signature (JWS) [JWS] and MUST contain an "iss"
(issuer) claim denoting the party attesting to the claims in the (issuer) claim denoting the party attesting to the claims in the
signed metadata. Consumers of the metadata MAY ignore the signed signed metadata. Consumers of the metadata MAY ignore the signed
metadata if they do not support this feature. If the consumer of the metadata if they do not support this feature. If the consumer of the
metadata supports signed metadata, metadata values conveyed in the metadata supports signed metadata, metadata values conveyed in the
signed metadata MUST take precedence over the corresponding values signed metadata MUST take precedence over the corresponding values
conveyed using plain JSON elements. conveyed using plain JSON elements.
Signed metadata is included in the authorization server metadata JSON Signed metadata is included in the authorization server metadata JSON
skipping to change at page 8, line 38 skipping to change at page 8, line 45
component, if any. By default, the well-known URI string used is component, if any. By default, the well-known URI string used is
"/.well-known/oauth-authorization-server". This path MUST use the "/.well-known/oauth-authorization-server". This path MUST use the
"https" scheme. The syntax and semantics of ".well-known" are "https" scheme. The syntax and semantics of ".well-known" are
defined in RFC 5785 [RFC5785]. The well-known URI suffix used MUST defined in RFC 5785 [RFC5785]. The well-known URI suffix used MUST
be registered in the IANA "Well-Known URIs" registry be registered in the IANA "Well-Known URIs" registry
[IANA.well-known]. [IANA.well-known].
Different applications utilizing OAuth authorization servers in Different applications utilizing OAuth authorization servers in
application-specific ways may define and register different well- application-specific ways may define and register different well-
known URI suffixes used to publish authorization server metadata as known URI suffixes used to publish authorization server metadata as
used by those applications. For instance, if the Example application used by those applications. For instance, if the example application
uses an OAuth authorization server in an Example-specific way, and uses an OAuth authorization server in an example-specific way, and
there are Example-specific metadata values that it needs to publish, there are example-specific metadata values that it needs to publish,
then it might register and use the "example-configuration" URI suffix then it might register and use the "example-configuration" URI suffix
and publish the metadata document at the path formed by inserting and publish the metadata document at the path formed by inserting
"/.well-known/example-configuration" between the host and path "/.well-known/example-configuration" between the host and path
components of the authorization server's issuer identifier. components of the authorization server's issuer identifier.
Alternatively, many such applications will use the default well-known Alternatively, many such applications will use the default well-known
URI string "/.well-known/oauth-authorization-server", which is the URI string "/.well-known/oauth-authorization-server", which is the
right choice for general-purpose OAuth authorization servers, and not right choice for general-purpose OAuth authorization servers, and not
register an application-specific one. 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
authorization server MAY choose to publish its metadata at multiple authorization server MAY choose to publish its metadata at multiple
well-known locations derived from its issuer identifier, for example, well-known locations derived from its issuer identifier, for example,
publishing metadata at both "/.well-known/example-configuration" and publishing metadata at both "/.well-known/example-configuration" and
"/.well-known/oauth-authorization-server". "/.well-known/oauth-authorization-server".
Some OAuth applications will choose to use the well-known URI suffix Some OAuth applications will choose to use the well-known URI suffix
"openid-configuration". As described in Section 5, despite the "openid-configuration". As described in Section 5, despite the
identifier "/.well-known/openid-configuration", appearing to be identifier "/.well-known/openid-configuration", appearing to be
OpenID-specific, its usage in this specification is actually OpenID specific, its usage in this specification is actually
referring to a general OAuth 2.0 feature that is not specific to referring to a general OAuth 2.0 feature that is not specific to
OpenID Connect. OpenID Connect.
3.1. Authorization Server Metadata Request 3.1. Authorization Server Metadata Request
An authorization server metadata document MUST be queried using an An authorization server metadata document MUST be queried using an
HTTP "GET" request at the previously specified path. HTTP "GET" request at the previously specified path.
The client would make the following request when the issuer The client would make the following request when the issuer
identifier is "https://example.com" and the well-known URI suffix is identifier is "https://example.com" and the well-known URI suffix is
skipping to change at page 11, line 18 skipping to change at page 11, line 24
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
"issuer". Comparing Unicode [UNICODE] strings, however, has "issuer". Comparing Unicode [UNICODE] strings, 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 described in
Section 8.3 of [RFC7159]. Section 8.3 of [RFC8259].
5. Compatibility Notes 5. Compatibility Notes
The identifiers "/.well-known/openid-configuration", "op_policy_uri", The identifiers "/.well-known/openid-configuration", "op_policy_uri",
and "op_tos_uri" contain strings referring to the OpenID Connect and "op_tos_uri" contain strings referring to the OpenID Connect
[OpenID.Core] family of specifications that were originally defined [OpenID.Core] family of specifications that were originally defined
by "OpenID Connect Discovery 1.0" [OpenID.Discovery]. Despite the by "OpenID Connect Discovery 1.0" [OpenID.Discovery]. Despite the
reuse of these identifiers that appear to be OpenID-specific, their reuse of these identifiers that appear to be OpenID specific, their
usage in this specification is actually referring to general OAuth usage in this specification is actually referring to general OAuth
2.0 features that are not specific to OpenID Connect. 2.0 features that are not specific to OpenID Connect.
The algorithm for transforming the issuer identifier to an The algorithm for transforming the issuer identifier to an
authorization server metadata location defined in Section 3 is authorization server metadata location defined in Section 3 is
equivalent to the corresponding transformation defined in Section 4 equivalent to the corresponding transformation defined in Section 4
of "OpenID Connect Discovery 1.0" [OpenID.Discovery], provided that of "OpenID Connect Discovery 1.0" [OpenID.Discovery], provided that
the issuer identifier contains no path component. However, they are the issuer identifier contains no path component. However, they are
different when there is a path component, because OpenID Connect different when there is a path component, because OpenID Connect
Discovery 1.0 specifies that the well-known URI string is appended to Discovery 1.0 specifies that the well-known URI string is appended to
the issuer identifier (e.g., "https://example.com/issuer1/.well- the issuer identifier (e.g.,
known/openid-configuration"), whereas this specification specifies "https://example.com/issuer1/.well-known/openid-configuration"),
that the well-known URI string is inserted before the path component whereas this specification specifies that the well-known URI string
of the issuer identifier (e.g., "https://example.com/.well-known/ is inserted before the path component of the issuer identifier (e.g.,
openid-configuration/issuer1"). "https://example.com/.well-known/openid-configuration/issuer1").
Going forward, OAuth authorization server metadata locations should Going forward, OAuth authorization server metadata locations should
use the transformation defined in this specification. However, when use the transformation defined in this specification. However, when
deployed in legacy environments in which the OpenID Connect Discovery deployed in legacy environments in which the OpenID Connect Discovery
1.0 transformation is already used, it may be necessary during a 1.0 transformation is already used, it may be necessary during a
transition period to publish metadata for issuer identifiers transition period to publish metadata for issuer identifiers
containing a path component at both locations. During this containing a path component at both locations. During this
transition period, applications should first apply the transformation transition period, applications should first apply the transformation
defined in this specification and attempt to retrieve the defined in this specification and attempt to retrieve the
authorization server metadata from the resulting location; only if authorization server metadata from the resulting location; only if
the retrieval from that location fails should they fall back to the retrieval from that location fails should they fall back to
attempting to retrive it from the alternate location obtained using attempting to retrieve it from the alternate location obtained using
the transformation defined by OpenID Connect Discovery 1.0. This the transformation defined by OpenID Connect Discovery 1.0. This
backwards-compatibility behavior should only be necessary when the backwards-compatible behavior should only be necessary when the well-
well-known URI suffix employed by the application is "openid- known URI suffix employed by the application is "openid-
configuration". configuration".
6. Security Considerations 6. Security Considerations
6.1. TLS Requirements 6.1. TLS Requirements
Implementations MUST support TLS. Which version(s) ought to be Implementations MUST support TLS. Which version(s) ought to be
implemented will vary over time and depend on the widespread implemented will vary over time and depend on the widespread
deployment and known security vulnerabilities at the time of deployment and known security vulnerabilities at the time of
implementation. The authorization server MUST support TLS version implementation. The authorization server MUST support TLS version
1.2 [RFC5246] and MAY support additional transport-layer security 1.2 [RFC5246] and MAY support additional TLS mechanisms meeting its
mechanisms meeting its security requirements. When using TLS, the security requirements. When using TLS, the client MUST perform a
client MUST perform a TLS/SSL server certificate check, per RFC 6125 TLS/SSL server certificate check, per RFC 6125 [RFC6125].
[RFC6125]. Implementation security considerations can be found in Implementation security considerations can be found in
Recommendations for Secure Use of TLS and DTLS [BCP195]. "Recommendations for Secure Use of Transport Layer Security (TLS) and
Datagram Transport Layer Security (DTLS)" [BCP195].
To protect against information disclosure and tampering, To protect against information disclosure and tampering,
confidentiality protection MUST be applied using TLS with a confidentiality protection MUST be applied using TLS with a
ciphersuite that provides confidentiality and integrity protection. ciphersuite that provides confidentiality and integrity protection.
6.2. Impersonation Attacks 6.2. Impersonation Attacks
TLS certificate checking MUST be performed by the client, as TLS certificate checking MUST be performed by the client, as
described in Section 6.1, when making an authorization server described in Section 6.1, when making an authorization server
metadata request. Checking that the server certificate is valid for metadata request. Checking that the server certificate is valid for
skipping to change at page 13, line 20 skipping to change at page 13, line 25
by the client. To prevent this, the client MUST ensure that the by the client. To prevent this, the client MUST ensure that the
issuer identifier URL it is using as the prefix for the metadata issuer identifier URL it is using as the prefix for the metadata
request exactly matches the value of the "issuer" metadata value in request exactly matches the value of the "issuer" metadata value in
the authorization server metadata document received by the client. the authorization server metadata document received by the client.
6.3. Publishing Metadata in a Standard Format 6.3. Publishing Metadata in a Standard Format
Publishing information about the authorization server in a standard Publishing information about the authorization server 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 authorization server. Whether an authorization server use the authorization server. Whether an authorization server
publishes its metadata in an ad-hoc manner or in the standard format publishes its metadata in an ad hoc manner or in the standard format
defined by this specification, the same defenses against attacks that defined by this specification, the same defenses against attacks that
might be mounted that use this information should be applied. might be mounted that use this information should be applied.
6.4. Protected Resources 6.4. Protected Resources
Secure determination of appropriate protected resources to use with Secure determination of appropriate protected resources to use with
an authorization server for all use cases is out of scope of this an authorization server for all use cases is out of scope of this
specification. This specification assumes that the client has a specification. This specification assumes that the client has a
means of determining appropriate protected resources to use with an means of determining appropriate protected resources to use with an
authorization server and that the client is using the correct authorization server and that the client is using the correct
metadata for each authorization server. Implementers need to be metadata for each authorization server. Implementers need to be
aware that if an inappropriate protected resource is used by the aware that if an inappropriate protected resource is used by the
client, that an attacker may be able to act as a man-in-the-middle client, that an attacker may be able to act as a man-in-the-middle
proxy to a valid protected resource without it being detected by the proxy to a valid protected resource without it being detected by the
authorization server or the client. authorization server or the client.
The ways to determine the appropriate protected resources to use with The ways to determine the appropriate protected resources to use with
an authorization server are in general, application-dependent. For an authorization server are, in general, application dependent. For
instance, some authorization servers are used with a fixed protected instance, some authorization servers are used with a fixed protected
resource or set of protected resources, the locations of which may be resource or set of protected resources, the locations of which may be
well known, or which could be published as metadata values by the well known or could be published as metadata values by the
authorization server. In other cases, the set of resources that can authorization server. In other cases, the set of resources that can
be used with an authorization server can by dynamically changed by be used with an authorization server can be dynamically changed by
administrative actions. Many other means of determining appropriate administrative actions. Many other means of determining appropriate
associations between authorization servers and protected resources associations between authorization servers and protected resources
are also possible. are also possible.
7. IANA Considerations 7. IANA Considerations
The following registration procedure is used for the registry The following registration procedure is used for the registry
established by this specification. established by this specification.
Values are registered on a Specification Required [RFC8126] basis Values are registered on a Specification Required [RFC8126] basis
skipping to change at page 14, line 24 skipping to change at page 14, line 29
Authorization Server Metadata: example"). Authorization Server 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.
Registration requests that are undetermined for a period longer than Registration requests that are undetermined for a period longer than
21 days can be brought to the IESG's attention (using the 21 days can be brought to the IESG's attention (using the
iesg@ietf.org mailing list) for resolution. iesg@ietf.org mailing list) for resolution.
Criteria that should be applied by the Designated Experts includes Criteria that should be applied by the Designated Experts include
determining whether the proposed registration duplicates existing determining whether the proposed registration duplicates existing
functionality, determining whether it is likely to be of general functionality, determining whether it is likely to be of general
applicability or whether it is useful only for a single application, applicability or whether it is useful only for a single application,
and whether the registration makes sense. and whether the registration makes sense.
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 It is suggested that multiple Designated Experts be appointed who are
able to represent the perspectives of different applications using able to represent the perspectives of different applications using
this specification, in order to enable broadly-informed review of this specification, in order to enable broadly-informed review of
registration decisions. In cases where a registration decision could registration decisions. In cases where a registration decision could
be perceived as creating a conflict of interest for a particular be perceived as creating a conflict of interest for a particular
Expert, that Expert should defer to the judgment of the other Designated Expert, that Designated Expert should defer to the
Experts. judgment of the other Designated Experts.
7.1. OAuth Authorization Server Metadata Registry 7.1. OAuth Authorization Server Metadata Registry
This specification establishes the IANA "OAuth Authorization Server This specification establishes the IANA "OAuth Authorization Server
Metadata" registry for OAuth 2.0 authorization server metadata names. Metadata" registry for OAuth 2.0 authorization server metadata names.
The registry records the authorization server metadata member and a The registry records the authorization server metadata member and a
reference to the specification that defines it. reference to the specification that defines it.
The Designated Experts must either: The Designated Experts must either:
(a) require that metadata names and values being registered use only (a) require that metadata names and values being registered use only
printable ASCII characters excluding double quote ('"') and backslash printable ASCII characters excluding double quote ('"') and backslash
('\') (the Unicode characters with code points U+0021, U+0023 through ('\') (the Unicode characters with code points U+0021, U+0023 through
U+005B, and U+005D through U+007E), or U+005B, and U+005D through U+007E), or
(b) if new metadata members or values are defined that use other code (b) if new metadata members or values are defined that use other code
points, require that their definitions specify the exact Unicode code points, require that their definitions specify the exact sequences of
point sequences used to represent them. Furthermore, proposed Unicode code points used to represent them. Furthermore, proposed
registrations that use Unicode code points that can only be registrations that use Unicode code points that can only be
represented in JSON strings as escaped characters must not be represented in JSON strings as escaped characters must not be
accepted. accepted.
7.1.1. Registration Template 7.1.1. Registration Template
Metadata Name: Metadata Name:
The name requested (e.g., "issuer"). This name is case-sensitive. The name requested (e.g., "issuer"). This name is case-sensitive.
Names may not match other registered names in a case-insensitive Names may not match other registered names in a case-insensitive
manner (one that would cause a match if the Unicode toLowerCase() manner (one that would cause a match if the Unicode toLowerCase()
skipping to change at page 15, line 40 skipping to change at page 16, line 7
address, email address, home page URI) may also be included. address, email 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.
7.1.2. Initial Registry Contents 7.1.2. Initial Registry Contents
o Metadata Name: "issuer" o Metadata Name: issuer
o Metadata Description: Authorization server's issuer identifier URL o Metadata Description: Authorization server's issuer identifier URL
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "authorization_endpoint" o Metadata Name: authorization_endpoint
o Metadata Description: URL of the authorization server's o Metadata Description: URL of the authorization server's
authorization endpoint authorization endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "token_endpoint" o Metadata Name: token_endpoint
o Metadata Description: URL of the authorization server's token o Metadata Description: URL of the authorization server's token
endpoint endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "jwks_uri" o Metadata Name: jwks_uri
o Metadata Description: URL of the authorization server's JWK Set o Metadata Description: URL of the authorization server's JWK Set
document document
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "registration_endpoint" o Metadata Name: registration_endpoint
o Metadata Description: URL of the authorization server's OAuth 2.0 o Metadata Description: URL of the authorization server's OAuth 2.0
Dynamic Client Registration Endpoint Dynamic Client Registration Endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "scopes_supported" o Metadata Name: scopes_supported
o Metadata Description: JSON array containing a list of the OAuth o Metadata Description: JSON array containing a list of the OAuth
2.0 "scope" values that this authorization server supports 2.0 "scope" values that this authorization server supports
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "response_types_supported" o Metadata Name: response_types_supported
o Metadata Description: JSON array containing a list of the OAuth o Metadata Description: JSON array containing a list of the OAuth
2.0 "response_type" values that this authorization server supports 2.0 "response_type" values that this authorization server supports
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "response_modes_supported" o Metadata Name: response_modes_supported
o Metadata Description: JSON array containing a list of the OAuth o Metadata Description: JSON array containing a list of the OAuth
2.0 "response_mode" values that this authorization server supports 2.0 "response_mode" values that this authorization server supports
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: grant_types_supported
o Metadata Name: "grant_types_supported"
o Metadata Description: JSON array containing a list of the OAuth o Metadata Description: JSON array containing a list of the OAuth
2.0 grant type values that this authorization server supports 2.0 grant type values that this authorization server supports
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "token_endpoint_auth_methods_supported" o Metadata Name: token_endpoint_auth_methods_supported
o Metadata Description: JSON array containing a list of client o Metadata Description: JSON array containing a list of client
authentication methods supported by this token endpoint authentication methods supported by this token endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "token_endpoint_auth_signing_alg_values_supported" o Metadata Name: token_endpoint_auth_signing_alg_values_supported
o Metadata Description: JSON array containing a list of the JWS o Metadata Description: JSON array containing a list of the JWS
signing algorithms supported by the token endpoint for the signing algorithms supported by the token endpoint for the
signature on the JWT used to authenticate the client at the token signature on the JWT used to authenticate the client at the token
endpoint endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "service_documentation" o Metadata Name: service_documentation
o Metadata Description: URL of a page containing human-readable o 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 authorization server the authorization server
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "ui_locales_supported" o Metadata Name: ui_locales_supported
o Metadata Description: Languages and scripts supported for the user o Metadata Description: Languages and scripts supported for the user
interface, represented as a JSON array of BCP47 language tag interface, represented as a JSON array of language tag values from
values BCP 47
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "op_policy_uri" o Metadata Name: op_policy_uri
o Metadata Description: URL that the authorization server provides o Metadata Description: URL that the authorization server provides
to the person registering the client to read about the to the person registering the client to read about the
authorization server's requirements on how the client can use the authorization server's requirements on how the client can use the
data provided by the authorization server data provided by the authorization server
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "op_tos_uri" o Metadata Name: op_tos_uri
o Metadata Description: URL that the authorization server provides o Metadata Description: URL that the authorization server provides
to the person registering the client to read about the to the person registering the client to read about the
authorization server's terms of service authorization server's terms of service
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: revocation_endpoint
o Metadata Name: "revocation_endpoint"
o Metadata Description: URL of the authorization server's OAuth 2.0 o Metadata Description: URL of the authorization server's OAuth 2.0
revocation endpoint revocation endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "revocation_endpoint_auth_methods_supported" o Metadata Name: revocation_endpoint_auth_methods_supported
o Metadata Description: JSON array containing a list of client o Metadata Description: JSON array containing a list of client
authentication methods supported by this revocation endpoint authentication methods supported by this revocation endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: o Metadata Name:
"revocation_endpoint_auth_signing_alg_values_supported" revocation_endpoint_auth_signing_alg_values_supported
o Metadata Description: JSON array containing a list of the JWS o Metadata Description: JSON array containing a list of the JWS
signing algorithms supported by the revocation endpoint for the signing algorithms supported by the revocation endpoint for the
signature on the JWT used to authenticate the client at the signature on the JWT used to authenticate the client at the
revocation endpoint revocation endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "introspection_endpoint" o Metadata Name: introspection_endpoint
o Metadata Description: URL of the authorization server's OAuth 2.0 o Metadata Description: URL of the authorization server's OAuth 2.0
introspection endpoint introspection endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "introspection_endpoint_auth_methods_supported" o Metadata Name: introspection_endpoint_auth_methods_supported
o Metadata Description: JSON array containing a list of client o Metadata Description: JSON array containing a list of client
authentication methods supported by this introspection endpoint authentication methods supported by this introspection endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: o Metadata Name:
"introspection_endpoint_auth_signing_alg_values_supported" introspection_endpoint_auth_signing_alg_values_supported
o Metadata Description: JSON array containing a list of the JWS o Metadata Description: JSON array containing a list of the JWS
signing algorithms supported by the introspection endpoint for the signing algorithms supported by the introspection endpoint for the
signature on the JWT used to authenticate the client at the signature on the JWT used to authenticate the client at the
introspection endpoint introspection endpoint
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: "code_challenge_methods_supported" o Metadata Name: code_challenge_methods_supported
o Metadata Description: PKCE code challenge methods supported by o Metadata Description: PKCE code challenge methods supported by
this authorization server this authorization server
o Change Controller: IESG o Change Controller: IESG
o Specification Document(s): Section 2 of [[ this specification ]] o Specification Document(s): Section 2 of RFC 8414
o Metadata Name: signed_metadata
o Metadata Description: Signed JWT containing metadata values about
the authorization server as claims
o Change Controller: IESG
o Specification Document(s): Section 2.1 of RFC 8414
7.2. Updated Registration Instructions 7.2. Updated Registration Instructions
This specification adds to the instructions for the Designated This specification adds to the instructions for the Designated
Experts of the following IANA registries, both of which are in the Experts of the following IANA registries, both of which are in the
"OAuth Parameters" registry [IANA.OAuth.Parameters]: "OAuth Parameters" registry [IANA.OAuth.Parameters]:
o OAuth Access Token Types o OAuth Access Token Types
o OAuth Token Endpoint Authentication Methods o OAuth Token Endpoint Authentication Methods
IANA has added a link to this specification in the Reference sections IANA has added a link to this specification in the Reference sections
of these registries. [[ RFC Editor: The above sentence is written in of these registries.
the past tense as it would appear in the final specification, even
though these links won't actually be created until after the IESG has
requested publication of the specification. Please delete this note
after the links are in place. ]]
For these registries, the designated experts must reject registration For these registries, the Designated Experts must reject registration
requests in one registry for values already occurring in the other requests in one registry for values already occurring in the other
registry. This is necessary because the registry. This is necessary because the
"introspection_endpoint_auth_methods_supported" parameter allows for "introspection_endpoint_auth_methods_supported" parameter allows for
the use of values from either registry. That way, because the values the use of values from either registry. That way, because the values
in the two registries will continue to be mutually exclusive, no in the two registries will continue to be mutually exclusive, no
ambiguities will arise. ambiguities will arise.
7.3. Well-Known URI Registry 7.3. Well-Known URI 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] established in the IANA "Well-Known URIs" registry [IANA.well-known] established
by RFC 5785 [RFC5785]. by RFC 5785 [RFC5785].
7.3.1. Registry Contents 7.3.1. Registry Contents
o URI suffix: "oauth-authorization-server" o URI suffix: oauth-authorization-server
o Change controller: IESG o Change controller: IESG
o Specification document: Section 3 of [[ this specification ]] o Specification document: Section 3 of RFC 8414
o Related information: (none) o Related information: (none)
8. References 8. References
8.1. Normative References 8.1. Normative References
[BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer "Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security Security (TLS) and Datagram Transport Layer Security
(DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May (DTLS)", BCP 195, RFC 7525, May 2015,
2015, <http://www.rfc-editor.org/info/bcp195>. <http://www.rfc-editor.org/info/bcp195>.
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>. <https://www.iana.org/assignments/oauth-parameters>.
[JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)",
RFC 7516, DOI 10.17487/RFC7516, May 2015, RFC 7516, DOI 10.17487/RFC7516, May 2015,
<http://tools.ietf.org/html/rfc7516>. <https://www.rfc-editor.org/info/rfc7516>.
[JWK] Jones, M., "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,
<http://tools.ietf.org/html/rfc7517>. <https://www.rfc-editor.org/info/rfc7517>.
[JWS] Jones, M., 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, <http://tools.ietf.org/html/rfc7515>. 2015, <https://www.rfc-editor.org/info/rfc7515>.
[JWT] Jones, M., 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,
<http://tools.ietf.org/html/rfc7519>. <https://www.rfc-editor.org/info/rfc7519>.
[OAuth.Post] [OAuth.Post]
Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response
Mode", April 2015, <http://openid.net/specs/ Mode", April 2015, <http://openid.net/specs/
oauth-v2-form-post-response-mode-1_0.html>. oauth-v2-form-post-response-mode-1_0.html>.
[OAuth.Responses] [OAuth.Responses]
de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M. de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M.
Jones, "OAuth 2.0 Multiple Response Type Encoding Jones, "OAuth 2.0 Multiple Response Type Encoding
Practices", February 2014, <http://openid.net/specs/ Practices", February 2014, <http://openid.net/specs/
skipping to change at page 21, line 13 skipping to change at page 21, line 38
<https://www.rfc-editor.org/info/rfc6749>. <https://www.rfc-editor.org/info/rfc6749>.
[RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009,
August 2013, <https://www.rfc-editor.org/info/rfc7009>. August 2013, <https://www.rfc-editor.org/info/rfc7009>.
[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>.
[RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March
2014, <https://www.rfc-editor.org/info/rfc7159>.
[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>.
[RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key
for Code Exchange by OAuth Public Clients", RFC 7636, for Code Exchange by OAuth Public Clients", RFC 7636,
DOI 10.17487/RFC7636, September 2015, DOI 10.17487/RFC7636, September 2015,
<https://www.rfc-editor.org/info/rfc7636>. <https://www.rfc-editor.org/info/rfc7636>.
skipping to change at page 21, line 40 skipping to change at page 22, line 14
[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>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[UNICODE] The Unicode Consortium, "The Unicode Standard", [UNICODE] The Unicode Consortium, "The Unicode Standard",
<http://www.unicode.org/versions/latest/>. <http://www.unicode.org/versions/latest/>.
[USA15] Davis, M. and K. Whistler, "Unicode Normalization Forms", [USA15] Davis, M., Ed. and K. Whistler, Ed., "Unicode
Unicode Standard Annex 15, June 2015, Normalization Forms", Unicode Standard Annex #15, May
<http://www.unicode.org/reports/tr15/>. 2018, <http://www.unicode.org/reports/tr15/>.
8.2. Informative References 8.2. Informative References
[I-D.ietf-oauth-mix-up-mitigation]
Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up
Mitigation", draft-ietf-oauth-mix-up-mitigation-01 (work
in progress), July 2016.
[IANA.well-known] [IANA.well-known]
IANA, "Well-Known URIs", IANA, "Well-Known URIs",
<http://www.iana.org/assignments/well-known-uris>. <https://www.iana.org/assignments/well-known-uris>.
[MIX-UP] Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up
Mitigation", Work in Progress, draft-ietf-oauth-mix-up-
mitigation-01, July 2016.
[OpenID.Core] [OpenID.Core]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and
C. Mortimore, "OpenID Connect Core 1.0", November 2014, C. Mortimore, "OpenID Connect Core 1.0", November 2014,
<http://openid.net/specs/openid-connect-core-1_0.html>. <http://openid.net/specs/openid-connect-core-1_0.html>.
[OpenID.Discovery] [OpenID.Discovery]
Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID
Connect Discovery 1.0", November 2014, Connect Discovery 1.0", November 2014,
<http://openid.net/specs/ <http://openid.net/specs/
openid-connect-discovery-1_0.html>. openid-connect-discovery-1_0.html>.
[OpenID.Registration] [OpenID.Registration]
Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect
Dynamic Client Registration 1.0", November 2014, Dynamic Client Registration 1.0", November 2014,
<http://openid.net/specs/ <http://openid.net/specs/
openid-connect-registration-1_0.html>. openid-connect-registration-1_0.html>.
Appendix A. Acknowledgements Acknowledgements
This specification is based on the OpenID Connect Discovery 1.0 This specification is based on the OpenID Connect Discovery 1.0
specification, which was produced by the OpenID Connect working group specification, which was produced by the OpenID Connect working group
of the OpenID Foundation. This specification standardizes the de of the OpenID Foundation. This specification standardizes the de
facto usage of the metadata format defined by OpenID Connect facto usage of the metadata format defined by OpenID Connect
Discovery to publish OAuth authorization server metadata. Discovery to publish OAuth authorization server metadata.
The authors would like to thank the following people for their The authors would like to thank the following people for their
reviews of this specification: Shwetha Bhandari, Ben Campbell, Brian reviews of this specification: Shwetha Bhandari, Ben Campbell, Brian
Campbell, Brian Carpenter, William Denniss, Vladimir Dzhuvinov, Campbell, Brian Carpenter, William Denniss, Vladimir Dzhuvinov,
Donald Eastlake, Samuel Erdtman, George Fletcher, Dick Hardt, Phil Donald Eastlake, Samuel Erdtman, George Fletcher, Dick Hardt, Phil
Hunt, Alexey Melnikov, Tony Nadalin, Mark Nottingham, Eric Rescorla, Hunt, Alexey Melnikov, Tony Nadalin, Mark Nottingham, Eric Rescorla,
Justin Richer, Adam Roach, Hannes Tschofenig, and Hans Zandbelt. Justin Richer, Adam Roach, Hannes Tschofenig, and Hans Zandbelt.
Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]]
-10
o Clarified the meaning of "case-insensitive", as suggested by
Alexey Melnikov.
-09
o Revised the transformation between the issuer identifier and the
authorization server metadata location to conform to BCP 190, as
suggested by Adam Roach.
o Defined the characters allowed in registered metadata names and
values, as suggested by Alexey Melnikov.
o Changed to using the RFC 8174 boilerplate instead of the RFC 2119
boilerplate, as suggested by Ben Campbell.
o Acknowledged additional reviewers.
-08
o Changed the "authorization_endpoint" to be REQUIRED only when
grant types are supported that use the authorization endpoint.
o Added the statement, to provide historical context, that this
specification standardizes the de facto usage of the metadata
format defined by OpenID Connect Discovery to publish OAuth
authorization server metadata.
o Applied clarifications suggested by Mark Nottingham about when
application-specific well-known suffixes are and are not
appropriate.
o Acknowledged additional reviewers.
-07
o Applied clarifications suggested by EKR.
-06
o Incorporated resolutions to working group last call comments.
-05
o Removed the "protected_resources" element and the reference to
draft-jones-oauth-resource-metadata.
-04
o Added the ability to list protected resources with the
"protected_resources" element.
o Added ability to provide signed metadata with the
"signed_metadata" element.
o Removed "Discovery" from the name, since this is now just about
authorization server metadata.
-03
o Changed term "issuer URL" to "issuer identifier" for terminology
consistency, paralleling the same terminology consistency change
in the mix-up mitigation spec.
-02
o Changed the title to OAuth 2.0 Authorization Server Discovery
Metadata.
o Made "jwks_uri" and "registration_endpoint" OPTIONAL.
o Defined the well-known URI string "/.well-known/oauth-
authorization-server".
o Added security considerations about publishing authorization
server discovery metadata in a standard format.
o Added security considerations about protected resources.
o Added more information to the "grant_types_supported" and
"response_types_supported" definitions.
o Referenced the working group Mix-Up Mitigation draft.
o Changed some example metadata values.
o Acknowledged individuals for their contributions to the
specification.
-01
o Removed WebFinger discovery.
o Clarified the relationship between the issuer identifier URL and
the well-known URI path relative to it at which the discovery
metadata document is located.
-00
o Created the initial working group version based on draft-jones-
oauth-discovery-01, with no normative changes.
Authors' Addresses Authors' Addresses
Michael B. Jones Michael B. Jones
Microsoft Microsoft
Email: mbj@microsoft.com Email: mbj@microsoft.com
URI: http://self-issued.info/ URI: http://self-issued.info/
Nat Sakimura Nat Sakimura
Nomura Research Institute, Ltd. Nomura Research Institute, Ltd.
Email: n-sakimura@nri.co.jp Email: n-sakimura@nri.co.jp
URI: http://nat.sakimura.org/ URI: http://nat.sakimura.org/
John Bradley John Bradley
Ping Identity Yubico
Email: ve7jtb@ve7jtb.com Email: RFC8414@ve7jtb.com
URI: http://www.thread-safe.com/ URI: http://www.thread-safe.com/
 End of changes. 102 change blocks. 
302 lines changed or deleted 193 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/