draft-ietf-oauth-discovery-01.txt   draft-ietf-oauth-discovery-02.txt 
OAuth Working Group M. Jones OAuth Working Group M. Jones
Internet-Draft Microsoft Internet-Draft Microsoft
Intended status: Standards Track N. Sakimura Intended status: Standards Track N. Sakimura
Expires: August 20, 2016 NRI Expires: September 22, 2016 NRI
J. Bradley J. Bradley
Ping Identity Ping Identity
February 17, 2016 March 21, 2016
OAuth 2.0 Discovery OAuth 2.0 Authorization Server Discovery Metadata
draft-ietf-oauth-discovery-01 draft-ietf-oauth-discovery-02
Abstract Abstract
This specification defines a discovery metadata format that an OAuth This specification defines a discovery metadata format that an OAuth
2.0 client can use to obtain the information needed to interact with 2.0 client can use to obtain the information needed to interact with
an OAuth 2.0 authorization server, including its endpoint locations an OAuth 2.0 authorization server, including its endpoint locations
and authorization server capabilities. and authorization server capabilities.
Status of this Memo Status of this Memo
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 20, 2016. This Internet-Draft will expire on September 22, 2016.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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
(http://trustee.ietf.org/license-info) in effect on the date of (http://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
skipping to change at page 2, line 15 skipping to change at page 2, line 15
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
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
3. Obtaining Authorization Server Discovery Metadata . . . . . . 7 3. Obtaining Authorization Server Discovery Metadata . . . . . . 7
3.1. Authorization Server Discovery Metadata Request . . . . . 8 3.1. Authorization Server Discovery Metadata Request . . . . . 8
3.2. Authorization Server Discovery Metadata Response . . . . . 8 3.2. Authorization Server Discovery Metadata Response . . . . . 9
3.3. Authorization Server Discovery Metadata Validation . . . . 9 3.3. Authorization Server Discovery Metadata Validation . . . . 10
4. String Operations . . . . . . . . . . . . . . . . . . . . . . 10 4. String Operations . . . . . . . . . . . . . . . . . . . . . . 10
5. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 10 5. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 11
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 11
6.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 10 6.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 11
6.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 11 6.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 12
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.3. Publishing Metadata in a Standard Format . . . . . . . . . 12
7.1. OAuth Discovery Metadata Registry . . . . . . . . . . . . 12 6.4. Protected Resources . . . . . . . . . . . . . . . . . . . 12
7.1.1. Registration Template . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 13 7.1. OAuth Authorization Server Discovery Metadata Registry . . 14
7.2. Updated Registration Instructions . . . . . . . . . . . . 16 7.1.1. Registration Template . . . . . . . . . . . . . . . . 14
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 7.1.2. Initial Registry Contents . . . . . . . . . . . . . . 14
8.1. Normative References . . . . . . . . . . . . . . . . . . . 17 7.2. Updated Registration Instructions . . . . . . . . . . . . 18
8.2. Informative References . . . . . . . . . . . . . . . . . . 19 7.3. Well-Known URI Registry . . . . . . . . . . . . . . . . . 18
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 20 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
Appendix B. Document History . . . . . . . . . . . . . . . . . . 20 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 8.1. Normative References . . . . . . . . . . . . . . . . . . . 18
8.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 22
Appendix B. Document History . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23
1. Introduction 1. Introduction
This specification generalizes the discovery metadata format defined This specification generalizes the discovery metadata format defined
by "OpenID Connect Discovery 1.0" [OpenID.Discovery] in a way that is by "OpenID Connect Discovery 1.0" [OpenID.Discovery] in a way that is
compatible with OpenID Connect Discovery, while being applicable to a compatible with OpenID Connect Discovery, while being applicable to a
wider set of OAuth 2.0 use cases. This is intentionally parallel to wider set of OAuth 2.0 use cases. This is intentionally parallel to
the way that the "OAuth 2.0 Dynamic Client Registration Protocol" the way that the "OAuth 2.0 Dynamic Client Registration Protocol"
[RFC7591] specification generalized the dynamic client registration [RFC7591] specification generalized the dynamic client registration
mechanisms defined by "OpenID Connect Dynamic Client Registration mechanisms defined by "OpenID Connect Dynamic Client Registration
skipping to change at page 4, line 8 skipping to change at page 4, line 8
"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 Practices
[OAuth.Responses]. [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. These authorization server metadata values are used configuration. The following authorization server metadata values
by this specification: are used by this specification and are registered in the IANA "OAuth
Authorization Server Discovery 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. This is the location where ".well-known" RFC 5785 components. This is the location where ".well-known" RFC 5785
[RFC5785] resources containing information about the authorization [RFC5785] resources containing information about the authorization
server are published. Using these well-known resources is server are published. Using these well-known resources is
described in Section 3. The issuer identifier is used to prevent described in Section 3. The issuer identifier is used to prevent
authorization server mix-up attacks, as described in "OAuth 2.0 authorization server mix-up attacks, as described in "OAuth 2.0
Mix-Up Mitigation" [I-D.jones-oauth-mix-up-mitigation]. Mix-Up Mitigation" [I-D.ietf-oauth-mix-up-mitigation].
authorization_endpoint authorization_endpoint
REQUIRED. URL of the authorization server's authorization REQUIRED. URL of the authorization server's authorization
endpoint [RFC6749]. endpoint [RFC6749].
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 used. is REQUIRED unless only the implicit grant type is used.
jwks_uri jwks_uri
REQUIRED. URL of the authorization server's JWK Set [JWK] OPTIONAL. URL of the authorization server's JWK Set [JWK]
document. This contains the signing key(s) the client uses to document. This contains the signing key(s) the client uses to
validate signatures from the authorization server. The JWK Set validate signatures from the authorization server. The JWK Set
MAY also contain the server's encryption key(s), which are used by MAY also contain the server's encryption key(s), which are used by
clients 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. Although some algorithms to indicate each key's intended usage. Although some algorithms
allow the same key to be used for both signatures and encryption, allow the same key to be used for both signatures and encryption,
doing so is NOT RECOMMENDED, as it is less secure. The JWK "x5c" doing so is NOT RECOMMENDED, as it is less secure. The JWK "x5c"
parameter MAY be used to provide X.509 representations of keys parameter MAY be used to provide X.509 representations of keys
provided. When used, the bare key values MUST still be present provided. When used, the bare key values MUST still be present
and MUST match those in the certificate. and MUST match those in the certificate.
registration_endpoint registration_endpoint
RECOMMENDED. 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
[RFC6749] "scope" values that this authorization server supports. [RFC6749] "scope" values that this authorization server supports.
Servers MAY choose not to advertise some supported scope values Servers MAY choose not to advertise some supported scope values
even when this parameter is used. even when this parameter is used.
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
"response_types" parameter defined by "OAuth 2.0 Dynamic Client
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. If omitted, type values that this authorization server supports. The array
the default value is "["authorization_code", "implicit"]". values used are the same as those used with the "grant_types"
parameter defined by "OAuth 2.0 Dynamic Client Registration
Protocol" [RFC7591]. If omitted, the default value is
"["authorization_code", "implicit"]".
token_endpoint_auth_methods_supported token_endpoint_auth_methods_supported
OPTIONAL. JSON array containing a list of client authentication OPTIONAL. JSON array containing a list of client authentication
methods supported by this token endpoint. Client authentication methods supported by this token endpoint. Client authentication
method values are used in the "token_endpoint_auth_method" method values are used in the "token_endpoint_auth_method"
parameter defined in Section 2 of [RFC7591]. If omitted, the parameter defined in Section 2 of [RFC7591]. If omitted, the
default is "client_secret_basic" -- the HTTP Basic Authentication default is "client_secret_basic" -- the HTTP Basic Authentication
Scheme specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. Scheme specified in Section 2.3.1 of OAuth 2.0 [RFC6749].
token_endpoint_auth_signing_alg_values_supported token_endpoint_auth_signing_alg_values_supported
skipping to change at page 7, line 34 skipping to change at page 7, line 51
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].
3. Obtaining Authorization Server Discovery Metadata 3. Obtaining Authorization Server Discovery Metadata
Authorization servers supporting discovery MUST make a JSON document Authorization servers supporting discovery MUST make a JSON document
containing discovery metadata as specified in Section 2 available at containing discovery metadata as specified in Section 2 available at
a path formed by concatenating a well-known URI string such as a path formed by concatenating a well-known URI string such as
"/.well-known/openid-configuration" to the authorization server's "/.well-known/oauth-authorization-server" to the authorization
issuer identifier. The syntax and semantics of ".well-known" are server's issuer identifier. The syntax and semantics of
defined in RFC 5785 [RFC5785]. The well-known URI path suffix used ".well-known" are defined in RFC 5785 [RFC5785]. The well-known URI
MUST be registered in the IANA "Well-Known URIs" registry path suffix used MUST be registered in the IANA "Well-Known URIs"
[IANA.well-known]. registry [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 path suffixes used to publish authorization server metadata known URI path suffixes used to publish authorization server metadata
as used by those applications. For instance, if the Example as used by those applications. For instance, if the Example
application uses an OAuth authorization server in an Example-specific application uses an OAuth authorization server in an Example-specific
way, and there are Example-specific metadata values that it needs to way, and there are Example-specific metadata values that it needs to
publish, then it might register and use the "example" URI path suffix publish, then it might register and use the "example-configuration"
and publish the metadata document at the path formed by concatenating URI path suffix and publish the metadata document at the path formed
"/.well-known/example-configuration" to the authorization server's by concatenating "/.well-known/example-configuration" to the
issuer identifier. authorization server's issuer identifier.
By default, for historical reasons, unless an application-specific An OAuth 2.0 application using this specification MUST specify what
well-known URI path suffix is registered and used for an application, well-known URI string it will use for this purpose. The same
the client for that application SHOULD use the well-known URI path authorization server MAY choose to publish its metadata at multiple
well-known locations relative to its issuer identifier, for example,
publishing metadata at both "/.well-known/example-configuration" and
"/.well-known/oauth-authorization-server".
Some OAuth applications will choose to use the well-known URI path
suffix "openid-configuration" and publish the metadata document at suffix "openid-configuration" and publish the metadata document at
the path formed by concatenating "/.well-known/openid-configuration" the path formed by concatenating "/.well-known/openid-configuration"
to the authorization server's issuer identifier. As described in to the authorization server's issuer identifier. As described in
Section 5, despite the identifier Section 5, despite the identifier
"/.well-known/openid-configuration", appearing to be OpenID-specific, "/.well-known/openid-configuration", appearing to be OpenID-specific,
its usage in this specification is actually referring to a general its usage in this specification is actually referring to a general
OAuth 2.0 feature that is not specific to OpenID Connect. OAuth 2.0 feature that is not specific to OpenID Connect.
3.1. Authorization Server Discovery Metadata Request 3.1. Authorization Server Discovery Metadata Request
An authorization server discovery metadata document MUST be queried An authorization server discovery metadata document MUST be queried
using an HTTP "GET" request at the previously specified path. using an 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 path identifier is "https://example.com" and the well-known URI path
suffix is "openid-configuration" to obtain the discovery metadata, suffix is "oauth-authorization-server" to obtain the discovery
since the issuer identifier contains no path component: metadata, since the issuer identifier contains no path component:
GET /.well-known/openid-configuration HTTP/1.1 GET /.well-known/oauth-authorization-server HTTP/1.1
Host: example.com Host: example.com
If the issuer identifier value contains a path component, any If the issuer identifier value contains a path component, any
terminating "/" MUST be removed before appending "/.well-known/" and terminating "/" MUST be removed before appending "/.well-known/" and
the well-known URI path suffix. The client would make the following the well-known URI path suffix. The client would make the following
request when the issuer identifier is "https://example.com/issuer1" request when the issuer identifier is "https://example.com/issuer1"
and the well-known URI path suffix is "openid-configuration" to and the well-known URI path suffix is "oauth-authorization-server" to
obtain the discovery metadata, since the issuer identifier contains a obtain the discovery metadata, since the issuer identifier contains a
path component: path component:
GET /issuer1/.well-known/openid-configuration HTTP/1.1 GET /issuer1/.well-known/oauth-authorization-server HTTP/1.1
Host: example.com Host: example.com
Using path components enables supporting multiple issuers per host. Using path components enables supporting multiple issuers 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 issuers per host; use of ".well-known" is for supporting multiple issuers per host;
unlike its use in RFC 5785 [RFC5785], it does not provide general unlike its use in RFC 5785 [RFC5785], it does not provide general
information about the host. information about the host.
3.2. Authorization Server Discovery Metadata Response 3.2. Authorization Server Discovery Metadata Response
skipping to change at page 9, line 23 skipping to change at page 10, line 14
The following is a non-normative example response: The following is a non-normative example response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
{ {
"issuer": "issuer":
"https://server.example.com", "https://server.example.com",
"authorization_endpoint": "authorization_endpoint":
"https://server.example.com/connect/authorize", "https://server.example.com/authorize",
"token_endpoint": "token_endpoint":
"https://server.example.com/connect/token", "https://server.example.com/token",
"token_endpoint_auth_methods_supported": "token_endpoint_auth_methods_supported":
["client_secret_basic", "private_key_jwt"], ["client_secret_basic", "private_key_jwt"],
"token_endpoint_auth_signing_alg_values_supported": "token_endpoint_auth_signing_alg_values_supported":
["RS256", "ES256"], ["RS256", "ES256"],
"userinfo_endpoint": "userinfo_endpoint":
"https://server.example.com/connect/userinfo", "https://server.example.com/userinfo",
"jwks_uri": "jwks_uri":
"https://server.example.com/jwks.json", "https://server.example.com/jwks.json",
"registration_endpoint": "registration_endpoint":
"https://server.example.com/connect/register", "https://server.example.com/register",
"scopes_supported": "scopes_supported":
["openid", "profile", "email", "address", ["openid", "profile", "email", "address",
"phone", "offline_access"], "phone", "offline_access"],
"response_types_supported": "response_types_supported":
["code", "code token"], ["code", "code token"],
"service_documentation": "service_documentation":
"http://server.example.com/connect/service_documentation.html", "http://server.example.com/service_documentation.html",
"ui_locales_supported": "ui_locales_supported":
["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"] ["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"]
} }
3.3. Authorization Server Discovery Metadata Validation 3.3. Authorization Server Discovery Metadata Validation
The "issuer" value returned MUST be identical to the authorization The "issuer" value returned MUST be identical to the authorization
server's issuer identifier value that was concatenated with the well- server's issuer identifier value that was concatenated with the well-
known URI path suffix to create the URL used to retrieve the known URI path suffix to create the URL used to retrieve the
discovery metadata. If these values are not identical, the data discovery metadata. If these values are not identical, the data
skipping to change at page 10, line 30 skipping to change at page 11, line 21
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 to 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.
5. Compatibility Notes 5. Compatibility Notes
The identifiers "/.well-known/openid-configuration", The identifiers "/.well-known/openid-configuration", "op_policy_uri",
"http://openid.net/specs/connect/1.0/issuer", "op_policy_uri", and and "op_tos_uri" contain strings referring to the OpenID Connect
"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.
6. Security Considerations 6. Security Considerations
6.1. TLS Requirements 6.1. TLS Requirements
skipping to change at page 11, line 36 skipping to change at page 12, line 29
by publishing a discovery document that contains an "issuer" claim by publishing a discovery document that contains an "issuer" claim
using the issuer identifier URL of the authorization server being using the issuer identifier URL of the authorization server being
impersonated, but with its own endpoints and signing keys. This impersonated, but with its own endpoints and signing keys. This
would enable it to impersonate that authorization server, if accepted would enable it to impersonate that authorization server, if accepted
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 discovery issuer identifier URL it is using as the prefix for the discovery
metadata request exactly matches the value of the "issuer" metadata metadata request exactly matches the value of the "issuer" metadata
value in the authorization server discovery metadata document value in the authorization server discovery metadata document
received by the client. received by the client.
6.3. Publishing Metadata in a Standard Format
Publishing information about the authorization server in a standard
format makes it easier for both legitimate clients and attackers to
use the authorization server. Whether an authorization server
publishes its metadata in an ad-hoc manner or in the standard format
defined by this specification, the same defenses against attacks that
might be mounted that use this information should be applied.
6.4. Protected Resources
Secure determination of appropriate protected resource endpoints to
use with an authorization server is out of scope of this
specification. This specification assumes that the client has a
means of determining appropriate resource endpoint(s) to use with an
authorization server and that the client is using the correct
discovery metadata for each authorization server. Implementers need
to be aware that if an inappropriate resource endpoint is used by the
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
authorization server or the client.
The ways to determine the appropriate protected resources to use with
an authorization server are in general, application-dependent. For
instance, some authorization servers are used with a fixed protected
resource or set of protected resources, the locations of which may be
well known, or which could be published as metadata values by the
authorization server. In other cases, the set of resources that can
be used with an authorization server can by dynamically changed by
administrative actions. Many other means of determining appropriate
associations between authorization servers and protected resources
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 [RFC5226] basis Values are registered on a Specification Required [RFC5226] basis
after a two-week review period on the oauth-ext-review@ietf.org after a two-week review period on the oauth-ext-review@ietf.org
mailing list, on the advice of one or more Designated Experts. mailing list, on the advice of one or more Designated Experts.
However, to allow for the allocation of values prior to publication, However, to allow for the allocation of values prior to publication,
the Designated Experts may approve registration once they are the Designated Experts may approve registration once they are
satisfied that such a specification will be published. satisfied that such a specification will be published.
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 Discovery an appropriate subject (e.g., "Request to register OAuth
Metadata: example"). Authorization Server Discovery 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 includes
skipping to change at page 12, line 31 skipping to change at page 14, line 8
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 Expert, that Expert should defer to the judgment of the other
Experts. Experts.
7.1. OAuth Discovery Metadata Registry 7.1. OAuth Authorization Server Discovery Metadata Registry
This specification establishes the IANA "OAuth Discovery Metadata" This specification establishes the IANA "OAuth Authorization Server
registry for OAuth 2.0 authorization server metadata names. The Discovery Metadata" registry for OAuth 2.0 authorization server
registry records the authorization server metadata member and a metadata names. The registry records the authorization server
reference to the specification that defines it. metadata member and a reference to the specification that defines it.
7.1.1. Registration Template 7.1.1. Registration Template
Discovery Metadata Name: Discovery 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 unless the Designated Experts state that there is a manner unless the Designated Experts state that there is a
compelling reason to allow an exception. compelling reason to allow an exception.
Discovery Metadata Description: Discovery Metadata Description:
skipping to change at page 16, line 50 skipping to change at page 18, line 31
after the links are in place. ]] 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
This specification registers the well-known URI defined in Section 3
in the IANA "Well-Known URIs" registry [IANA.well-known] established
by RFC 5785 [RFC5785].
7.3.1. Registry Contents
o URI suffix: "oauth-authorization-server"
o Change controller: IESG
o Specification document: Section 3 of [[ this specification ]]
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, (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525,
May 2015, <http://www.rfc-editor.org/info/bcp195>. May 2015, <http://www.rfc-editor.org/info/bcp195>.
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
skipping to change at page 19, line 33 skipping to change at page 21, line 28
[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. and K. Whistler, "Unicode Normalization Forms",
Unicode Standard Annex 15, June 2015, Unicode Standard Annex 15, June 2015,
<http://www.unicode.org/reports/tr15/>. <http://www.unicode.org/reports/tr15/>.
8.2. Informative References 8.2. Informative References
[I-D.jones-oauth-mix-up-mitigation] [I-D.ietf-oauth-mix-up-mitigation]
Jones, M. and J. Bradley, "OAuth 2.0 Mix-Up Mitigation", Jones, M., Bradley, J., and N. Sakimura, "OAuth 2.0 Mix-Up
draft-jones-oauth-mix-up-mitigation-01 (work in progress), Mitigation", draft-ietf-oauth-mix-up-mitigation-00 (work
January 2016. in progress), March 2016.
[IANA.well-known] [IANA.well-known]
IANA, "Well-Known URIs", IANA, "Well-Known URIs",
<http://www.iana.org/assignments/well-known-uris>. <http://www.iana.org/assignments/well-known-uris>.
[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>.
skipping to change at page 20, line 16 skipping to change at page 22, line 11
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, <http:// Dynamic Client Registration 1.0", November 2014, <http://
openid.net/specs/openid-connect-registration-1_0.html>. openid.net/specs/openid-connect-registration-1_0.html>.
Appendix A. Acknowledgements Appendix A. 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. of the OpenID Foundation.
Review comments resulting in substantive edits to the specification
were made by Brian Campbell, William Denniss, Vladimir Dzhuvinov,
Samuel Erdtman, George Fletcher, Phil Hunt, Tony Nadalin, and Justin
Richer.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-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 -01
o Removed WebFinger discovery. o Removed WebFinger discovery.
o Clarified the relationship between the issuer identifier URL and o Clarified the relationship between the issuer identifier URL and
the well-known URI path relative to it at which the discovery the well-known URI path relative to it at which the discovery
metadata document is located. metadata document is located.
-00 -00
 End of changes. 34 change blocks. 
65 lines changed or deleted 158 lines changed or added

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