idnits 2.17.1 draft-ietf-oauth-discovery-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 8, 2016) is 2998 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'JWA' is defined on line 861, but no explicit reference was found in the text == Unused Reference: 'RFC2246' is defined on line 896, but no explicit reference was found in the text == Unused Reference: 'RFC7565' is defined on line 947, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7525 (ref. 'BCP195') (Obsoleted by RFC 9325) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) -- Possible downref: Non-RFC (?) normative reference: ref. 'UNICODE' -- Possible downref: Non-RFC (?) normative reference: ref. 'USA15' Summary: 7 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group M. Jones 3 Internet-Draft Microsoft 4 Intended status: Standards Track N. Sakimura 5 Expires: August 11, 2016 NRI 6 J. Bradley 7 Ping Identity 8 February 8, 2016 10 OAuth 2.0 Discovery 11 draft-ietf-oauth-discovery-00 13 Abstract 15 This specification defines a mechanism for an OAuth 2.0 client to 16 discover the resource owner's OAuth 2.0 authorization server and 17 obtain information needed to interact with it, including its OAuth 18 2.0 endpoint locations and authorization server capabilities. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 11, 2016. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Authorization Server WebFinger Discovery . . . . . . . . . . . 4 58 3. Authorization Server Metadata . . . . . . . . . . . . . . . . 6 59 4. Obtaining Authorization Server Configuration Information . . . 10 60 4.1. Authorization Server Configuration Information Request . . 10 61 4.2. Authorization Server Configuration Information Response . 11 62 4.3. Authorization Server Configuration Information 63 Validation . . . . . . . . . . . . . . . . . . . . . . . . 12 64 5. String Operations . . . . . . . . . . . . . . . . . . . . . . 12 65 6. Compatibility Notes . . . . . . . . . . . . . . . . . . . . . 13 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 7.1. TLS Requirements . . . . . . . . . . . . . . . . . . . . . 13 68 7.2. Impersonation Attacks . . . . . . . . . . . . . . . . . . 14 69 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 70 8.1. OAuth Discovery Metadata Registry . . . . . . . . . . . . 15 71 8.1.1. Registration Template . . . . . . . . . . . . . . . . 15 72 8.1.2. Initial Registry Contents . . . . . . . . . . . . . . 16 73 8.2. Updated Registration Instructions . . . . . . . . . . . . 19 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 75 9.1. Normative References . . . . . . . . . . . . . . . . . . . 19 76 9.2. Informative References . . . . . . . . . . . . . . . . . . 22 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 22 78 Appendix B. Document History . . . . . . . . . . . . . . . . . . 22 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23 81 1. Introduction 83 This specification generalizes the discovery mechanisms defined by 84 "OpenID Connect Discovery 1.0" [OpenID.Discovery] in a way that is 85 compatible with OpenID Connect Discovery, while being applicable to a 86 wider set of OAuth 2.0 use cases. This is intentionally parallel to 87 the way that the "OAuth 2.0 Dynamic Client Registration Protocol" 88 [RFC7591] specification generalized the dynamic client registration 89 mechanisms defined by "OpenID Connect Dynamic Client Registration 90 1.0" [OpenID.Registration] in a way that was compatible with it. 92 In order for an OAuth client to utilize OAuth 2.0 services for a 93 resource owner, the client needs to know where the OAuth 2.0 94 authorization server is. This specification uses WebFinger [RFC7033] 95 to locate the authorization server for an resource owner. This 96 process is described in Section 2. 98 Once the authorization server has been identified, the configuration 99 information for that authorization server is retrieved from a well- 100 known location as a JSON [RFC7159] document, including its OAuth 2.0 101 endpoint locations and authorization server capabilities. This 102 process is described in Section 4. 104 1.1. Requirements Notation and Conventions 106 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 107 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 108 "OPTIONAL" in this document are to be interpreted as described in RFC 109 2119 [RFC2119]. 111 All uses of JSON Web Signature (JWS) [JWS] and JSON Web Encryption 112 (JWE) [JWE] data structures in this specification utilize the JWS 113 Compact Serialization or the JWE Compact Serialization; the JWS JSON 114 Serialization and the JWE JSON Serialization are not used. 116 1.2. Terminology 118 This specification uses the terms "Access Token", "Authorization 119 Code", "Authorization Endpoint", "Authorization Grant", 120 "Authorization Server", "Client", "Client Authentication", "Client 121 Identifier", "Client Secret", "Grant Type", "Protected Resource", 122 "Redirection URI", "Refresh Token", "Resource Owner", "Resource 123 Server", "Response Type", and "Token Endpoint" defined by OAuth 2.0 124 [RFC6749], the terms "Claim Name", "Claim Value", and "JSON Web Token 125 (JWT)" defined by JSON Web Token (JWT) [JWT], and the term "Response 126 Mode" defined by OAuth 2.0 Multiple Response Type Encoding Practices 127 [OAuth.Responses]. 129 This specification also defines the following terms: 131 Resource 132 Entity that is the target of a request in WebFinger. 134 Host 135 Server where a WebFinger service is hosted. 137 2. Authorization Server WebFinger Discovery 139 Authorization server WebFinger discovery is a means of determining 140 the location of the authorization server's configuration information. 142 WebFinger discovery is OPTIONAL; if a client knows the authorization 143 server's configuration information location through an out-of-band 144 mechanism, it can skip this step and proceed to Section 4. 146 WebFinger discovery requires the following information to make a 147 discovery request: 149 resource 150 Identifier for the target resource owner that is the subject of 151 the discovery request. 153 host 154 Server where the WebFinger service is hosted. 156 rel 157 URI identifying the type of service whose location is being 158 requested. 160 OAuth discovery uses the following "rel" value in WebFinger 161 [RFC7033]: 163 +----------------------+--------------------------------------------+ 164 | Rel Type | URI | 165 +----------------------+--------------------------------------------+ 166 | OAuth 2.0 | http://openid.net/specs/connect/1.0/issuer | 167 | Configuration | | 168 | Information Location | | 169 | URL | | 170 +----------------------+--------------------------------------------+ 172 To start discovery of OAuth 2.0 configuration information, the 173 resource owner supplies a URI to the client that can be used to 174 discover the corresponding authorization server. In some cases, the 175 client may know this URI without involvement of the resource owner. 177 This URI might, for instance, be an e-mail address, an account 178 identifier, a profile URL, or a service or tenant URL. 180 The host to which the WebFinger request will be made is obtained from 181 the URI. The client then makes an HTTP "GET" request to the host's 182 WebFinger [RFC7033] endpoint using the URI as the "resource" 183 parameter value and the "rel" value 184 "http://openid.net/specs/connect/1.0/issuer" to obtain the 185 authorization server's configuration information location. 187 The configuration information location MUST be returned in the 188 WebFinger response as the value of the "href" member of a "links" 189 array element with "rel" member value 190 "http://openid.net/specs/connect/1.0/issuer". As described in 191 Section 6, despite the identifier 192 "http://openid.net/specs/connect/1.0/issuer" appearing to be OpenID- 193 specific, its usage in this specification is actually referring to a 194 general OAuth 2.0 feature that is not specific to OpenID Connect. 195 (Per Section 7 of WebFinger [RFC7033], obtaining the WebFinger 196 response may first involve following some redirects.) 198 The returned configuration information location MUST be a URI RFC 199 3986 [RFC3986] with a scheme component that MUST be "https", a host 200 component, and optionally, port and path components and no query or 201 fragment components. Note that the WebFinger response can return a 202 configuration information location value using a completely different 203 scheme, host, port, and path from any contained in the input URI, and 204 no relationship can be assumed between the input URI and the 205 resulting configuration information location. 207 An example WebFinger discovery request follows. To find the 208 authorization server's configuration information location for the 209 account identified using the e-mail address syntax "joe@example.com" 210 and corresponding account URI "acct:joe@example.com", the WebFinger 211 parameters are as follows: 213 +---------------------+--------------------------------------------+ 214 | WebFinger Parameter | Value | 215 +---------------------+--------------------------------------------+ 216 | resource | acct:joe@example.com | 217 | host | example.com | 218 | rel | http://openid.net/specs/connect/1.0/issuer | 219 +---------------------+--------------------------------------------+ 220 The client would make the following WebFinger request to discover the 221 authorization server's configuration information location (with line 222 wraps within lines for display purposes only): 224 GET /.well-known/webfinger 225 ?resource=acct%3Ajoe%40example.com 226 &rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer 227 HTTP/1.1 228 Host: example.com 230 HTTP/1.1 200 OK 231 Content-Type: application/jrd+json 233 { 234 "subject": "acct:joe@example.com", 235 "links": 236 [ 237 { 238 "rel": "http://openid.net/specs/connect/1.0/issuer", 239 "href": "https://server.example.com" 240 } 241 ] 242 } 244 The discovered authorization server configuration information 245 location is "https://server.example.com". 247 3. Authorization Server Metadata 249 Authorization servers can have metadata describing their 250 configuration. These authorization server metadata values are used 251 by this specification: 253 issuer 254 REQUIRED. URL of the authorization server's configuration 255 information location, which uses the "https" scheme and has no 256 query or fragment components. This is the location where 257 ".well-known" RFC 5785 [RFC5785] resources containing information 258 about the authorization server are published, and in particular, 259 the "/.well-known/openid-configuration" resource defined in 260 Section 4. If WebFinger discovery is supported (see Section 2), 261 this value MUST be identical to the configuration information 262 location value returned by WebFinger. 264 authorization_endpoint 265 REQUIRED. URL of the authorization server's authorization 266 endpoint [RFC6749]. 268 token_endpoint 269 URL of the authorization server's token endpoint [RFC6749]. This 270 is REQUIRED unless only the implicit grant type is used. 272 jwks_uri 273 REQUIRED. URL of the authorization server's JWK Set [JWK] 274 document. This contains the signing key(s) the client uses to 275 validate signatures from the authorization server. The JWK Set 276 MAY also contain the Server's encryption key(s), which are used by 277 RPs to encrypt requests to the Server. When both signing and 278 encryption keys are made available, a "use" (public key use) 279 parameter value is REQUIRED for all keys in the referenced JWK Set 280 to indicate each key's intended usage. Although some algorithms 281 allow the same key to be used for both signatures and encryption, 282 doing so is NOT RECOMMENDED, as it is less secure. The JWK "x5c" 283 parameter MAY be used to provide X.509 representations of keys 284 provided. When used, the bare key values MUST still be present 285 and MUST match those in the certificate. 287 registration_endpoint 288 RECOMMENDED. URL of the authorization server's OAuth 2.0 Dynamic 289 Client Registration endpoint [RFC7591]. 291 scopes_supported 292 RECOMMENDED. JSON array containing a list of the OAuth 2.0 293 [RFC6749] "scope" values that this authorization server supports. 294 Servers MAY choose not to advertise some supported scope values 295 even when this parameter is used. 297 response_types_supported 298 REQUIRED. JSON array containing a list of the OAuth 2.0 299 "response_type" values that this authorization server supports. 301 response_modes_supported 302 OPTIONAL. JSON array containing a list of the OAuth 2.0 303 "response_mode" values that this authorization server supports, as 304 specified in OAuth 2.0 Multiple Response Type Encoding Practices 305 [OAuth.Responses]. If omitted, the default is "["query", 306 "fragment"]". The response mode value "form_post" is also defined 307 in OAuth 2.0 Form Post Response Mode [OAuth.Post]. 309 grant_types_supported 310 OPTIONAL. JSON array containing a list of the OAuth 2.0 grant 311 type values that this authorization server supports. If omitted, 312 the default value is "["authorization_code", "implicit"]". 314 token_endpoint_auth_methods_supported 315 OPTIONAL. JSON array containing a list of client authentication 316 methods supported by this token endpoint. Client authentication 317 method values are used in the "token_endpoint_auth_method" 318 parameter defined in Section 2 of [RFC7591]. If omitted, the 319 default is "client_secret_basic" -- the HTTP Basic Authentication 320 Scheme specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. 322 token_endpoint_auth_signing_alg_values_supported 323 OPTIONAL. JSON array containing a list of the JWS signing 324 algorithms ("alg" values) supported by the token endpoint for the 325 signature on the JWT [JWT] used to authenticate the client at the 326 token endpoint for the "private_key_jwt" and "client_secret_jwt" 327 authentication methods. Servers SHOULD support "RS256". The 328 value "none" MUST NOT be used. 330 service_documentation 331 OPTIONAL. URL of a page containing human-readable information 332 that developers might want or need to know when using the 333 authorization server. In particular, if the authorization server 334 does not support Dynamic Client Registration, then information on 335 how to register clients needs to be provided in this 336 documentation. 338 ui_locales_supported 339 OPTIONAL. Languages and scripts supported for the user interface, 340 represented as a JSON array of BCP47 [RFC5646] language tag 341 values. 343 op_policy_uri 344 OPTIONAL. URL that the authorization server provides to the 345 person registering the client to read about the authorization 346 server's requirements on how the client can use the data provided 347 by the authorization server. The registration process SHOULD 348 display this URL to the person registering the client if it is 349 given. As described in Section 6, despite the identifier 350 "op_policy_uri", appearing to be OpenID-specific, its usage in 351 this specification is actually referring to a general OAuth 2.0 352 feature that is not specific to OpenID Connect. 354 op_tos_uri 355 OPTIONAL. URL that the authorization server provides to the 356 person registering the client to read about authorization server's 357 terms of service. The registration process SHOULD display this 358 URL to the person registering the client if it is given. As 359 described in Section 6, despite the identifier "op_tos_uri", 360 appearing to be OpenID-specific, its usage in this specification 361 is actually referring to a general OAuth 2.0 feature that is not 362 specific to OpenID Connect. 364 revocation_endpoint 365 OPTIONAL. URL of the authorization server's OAuth 2.0 revocation 366 endpoint [RFC7009]. 368 revocation_endpoint_auth_methods_supported 369 OPTIONAL. JSON array containing a list of client authentication 370 methods supported by this revocation endpoint. The valid client 371 authentication method values are those registered in the IANA 372 "OAuth Token Endpoint Authentication Methods" registry 373 [IANA.OAuth.Parameters]. 375 revocation_endpoint_auth_signing_alg_values_supported 376 OPTIONAL. JSON array containing a list of the JWS signing 377 algorithms ("alg" values) supported by the revocation endpoint for 378 the signature on the JWT [JWT] used to authenticate the client at 379 the revocation endpoint for the "private_key_jwt" and 380 "client_secret_jwt" authentication methods. The value "none" MUST 381 NOT be used. 383 introspection_endpoint 384 OPTIONAL. URL of the authorization server's OAuth 2.0 385 introspection endpoint [RFC7662]. 387 introspection_endpoint_auth_methods_supported 388 OPTIONAL. JSON array containing a list of client authentication 389 methods supported by this introspection endpoint. The valid 390 client authentication method values are those registered in the 391 IANA "OAuth Token Endpoint Authentication Methods" registry 392 [IANA.OAuth.Parameters] or those registered in the IANA "OAuth 393 Access Token Types" registry [IANA.OAuth.Parameters]. (These 394 values are and will remain distinct, due to Section 8.2.) 396 introspection_endpoint_auth_signing_alg_values_supported 397 OPTIONAL. JSON array containing a list of the JWS signing 398 algorithms ("alg" values) supported by the introspection endpoint 399 for the signature on the JWT [JWT] used to authenticate the client 400 at the introspection endpoint for the "private_key_jwt" and 401 "client_secret_jwt" authentication methods. The value "none" MUST 402 NOT be used. 404 code_challenge_methods_supported 405 OPTIONAL. JSON array containing a list of PKCE [RFC7636] code 406 challenge methods supported by this authorization server. Code 407 challenge method values are used in the "code_challenge_method" 408 parameter defined in Section 4.3 of [RFC7636]. The valid code 409 challenge method values are those registered in the IANA "PKCE 410 Code Challenge Methods" registry [IANA.OAuth.Parameters]. 412 Additional authorization server metadata parameters MAY also be used. 413 Some are defined by other specifications, such as OpenID Connect 414 Discovery 1.0 [OpenID.Discovery]. 416 4. Obtaining Authorization Server Configuration Information 418 Using the configuration information location discovered as described 419 in Section 2 or by other means, the authorization server's 420 configuration information can be retrieved. 422 Authorization servers supporting discovery MUST make a JSON document 423 available at the path formed by concatenating the string 424 "/.well-known/openid-configuration" to the configuration information 425 location. The syntax and semantics of ".well-known" are defined in 426 RFC 5785 [RFC5785] and apply to the configuration information 427 location value when it contains no path component. 428 "openid-configuration" MUST point to a JSON document compliant with 429 this specification and MUST be returned using the "application/json" 430 content type. As described in Section 6, despite the identifier 431 "/.well-known/openid-configuration", appearing to be OpenID-specific, 432 its usage in this specification is actually referring to a general 433 OAuth 2.0 feature that is not specific to OpenID Connect. 435 4.1. Authorization Server Configuration Information Request 437 An authorization server configuration information document MUST be 438 queried using an HTTP "GET" request at the previously specified path. 440 The client would make the following request to the configuration 441 information location "https://example.com" to obtain its 442 configuration information, since the configuration information 443 location contains no path component: 445 GET /.well-known/openid-configuration HTTP/1.1 446 Host: example.com 448 If the configuration information location value contains a path 449 component, any terminating "/" MUST be removed before appending 450 "/.well-known/openid-configuration". The client would make the 451 following request to the configuration information location 452 "https://example.com/issuer1" to obtain its configuration 453 information, since the configuration information location contains a 454 path component: 456 GET /issuer1/.well-known/openid-configuration HTTP/1.1 457 Host: example.com 459 Using path components enables supporting multiple issuers per host. 460 This is required in some multi-tenant hosting configurations. This 461 use of ".well-known" is for supporting multiple issuers per host; 462 unlike its use in RFC 5785 [RFC5785], it does not provide general 463 information about the host. 465 4.2. Authorization Server Configuration Information Response 467 The response is a set of claims about the authorization server's 468 configuration, including all necessary endpoints and public key 469 location information. A successful response MUST use the 200 OK HTTP 470 status code and return a JSON object using the "application/json" 471 content type that contains a set of claims as its members that are a 472 subset of the metadata values defined in Section 3. Other claims MAY 473 also be returned. 475 Claims that return multiple values are represented as JSON arrays. 476 Claims with zero elements MUST be omitted from the response. 478 An error response uses the applicable HTTP status code value. 480 The following is a non-normative example response: 482 HTTP/1.1 200 OK 483 Content-Type: application/json 485 { 486 "issuer": 487 "https://server.example.com", 488 "authorization_endpoint": 489 "https://server.example.com/connect/authorize", 490 "token_endpoint": 491 "https://server.example.com/connect/token", 492 "token_endpoint_auth_methods_supported": 493 ["client_secret_basic", "private_key_jwt"], 494 "token_endpoint_auth_signing_alg_values_supported": 495 ["RS256", "ES256"], 496 "userinfo_endpoint": 497 "https://server.example.com/connect/userinfo", 498 "jwks_uri": 499 "https://server.example.com/jwks.json", 500 "registration_endpoint": 501 "https://server.example.com/connect/register", 502 "scopes_supported": 503 ["openid", "profile", "email", "address", 504 "phone", "offline_access"], 505 "response_types_supported": 506 ["code", "code token"], 507 "service_documentation": 508 "http://server.example.com/connect/service_documentation.html", 509 "ui_locales_supported": 510 ["en-US", "en-GB", "en-CA", "fr-FR", "fr-CA"] 511 } 513 4.3. Authorization Server Configuration Information Validation 515 If any of the validation procedures defined in this specification 516 fail, any operations requiring the information that failed to 517 correctly validate MUST be aborted and the information that failed to 518 validate MUST NOT be used. 520 The "issuer" value returned MUST be identical to the configuration 521 information location URL that was directly used to retrieve the 522 configuration information. 524 5. String Operations 526 Processing some OAuth 2.0 messages requires comparing values in the 527 messages to known values. For example, the member names in the 528 configuration information response might be compared to specific 529 member names such as "issuer". Comparing Unicode [UNICODE] strings, 530 however, has significant security implications. 532 Therefore, comparisons between JSON strings and other Unicode strings 533 MUST be performed as specified below: 535 1. Remove any JSON applied escaping to produce an array of Unicode 536 code points. 538 2. Unicode Normalization [USA15] MUST NOT be applied at any point to 539 either the JSON string or to the string it is to be compared 540 against. 542 3. Comparisons between the two strings MUST be performed as a 543 Unicode code point to code point equality comparison. 545 6. Compatibility Notes 547 The identifiers "/.well-known/openid-configuration", 548 "http://openid.net/specs/connect/1.0/issuer", "op_policy_uri", and 549 "op_tos_uri" contain strings referring to the OpenID Connect 550 [OpenID.Core] family of specifications that were originally defined 551 by "OpenID Connect Discovery 1.0" [OpenID.Discovery]. Despite the 552 reuse of these identifiers that appear to be OpenID-specific, their 553 usage in this specification is actually referring to general OAuth 554 2.0 features that are not specific to OpenID Connect. 556 7. Security Considerations 558 7.1. TLS Requirements 560 Implementations MUST support TLS. Which version(s) ought to be 561 implemented will vary over time, and depend on the widespread 562 deployment and known security vulnerabilities at the time of 563 implementation. The authorization server MUST support TLS version 564 1.2 [RFC5246] and MAY support additional transport-layer security 565 mechanisms meeting its security requirements. When using TLS, the 566 client MUST perform a TLS/SSL server certificate check, per RFC 6125 567 [RFC6125]. Implementation security considerations can be found in 568 Recommendations for Secure Use of TLS and DTLS [BCP195]. 570 To protect against information disclosure and tampering, 571 confidentiality protection MUST be applied using TLS with a 572 ciphersuite that provides confidentiality and integrity protection. 574 7.2. Impersonation Attacks 576 TLS certificate checking MUST be performed by the client, as 577 described in Section 7.1, when making an authorization server 578 configuration information request. Checking that the server 579 certificate is valid for the configuration information location URL 580 prevents man-in-middle and DNS-based attacks. These attacks could 581 cause a client to be tricked into using an attacker's keys and 582 endpoints, which would enable impersonation of the legitimate 583 authorization server. If an attacker can accomplish this, they can 584 access the resources that the affected client has access to using the 585 authorization server that they are impersonating. 587 An attacker may also attempt to impersonate an authorization server 588 by publishing a discovery document that contains an "issuer" claim 589 using the configuration information location URL of the authorization 590 server being impersonated, but with its own endpoints and signing 591 keys. This would enable it to impersonate that authorization server, 592 if accepted by the client. To prevent this, RPs MUST ensure that the 593 configuration information location URL they are using for the 594 configuration information request exactly matches the value of the 595 "issuer" metadata value in the authorization server configuration 596 information document received by the client. 598 8. IANA Considerations 600 The following registration procedure is used for the registry 601 established by this specification. 603 Values are registered on a Specification Required [RFC5226] basis 604 after a two-week review period on the oauth-ext-review@ietf.org 605 mailing list, on the advice of one or more Designated Experts. 606 However, to allow for the allocation of values prior to publication, 607 the Designated Experts may approve registration once they are 608 satisfied that such a specification will be published. 610 Registration requests sent to the mailing list for review should use 611 an appropriate subject (e.g., "Request to register OAuth Discovery 612 Metadata: example"). 614 Within the review period, the Designated Experts will either approve 615 or deny the registration request, communicating this decision to the 616 review list and IANA. Denials should include an explanation and, if 617 applicable, suggestions as to how to make the request successful. 618 Registration requests that are undetermined for a period longer than 619 21 days can be brought to the IESG's attention (using the 620 iesg@ietf.org mailing list) for resolution. 622 Criteria that should be applied by the Designated Experts includes 623 determining whether the proposed registration duplicates existing 624 functionality, determining whether it is likely to be of general 625 applicability or whether it is useful only for a single application, 626 and whether the registration makes sense. 628 IANA must only accept registry updates from the Designated Experts 629 and should direct all requests for registration to the review mailing 630 list. 632 It is suggested that multiple Designated Experts be appointed who are 633 able to represent the perspectives of different applications using 634 this specification, in order to enable broadly-informed review of 635 registration decisions. In cases where a registration decision could 636 be perceived as creating a conflict of interest for a particular 637 Expert, that Expert should defer to the judgment of the other 638 Experts. 640 8.1. OAuth Discovery Metadata Registry 642 This specification establishes the IANA "OAuth Discovery Metadata" 643 registry for OAuth 2.0 authorization server metadata names. The 644 registry records the authorization server metadata member and a 645 reference to the specification that defines it. 647 8.1.1. Registration Template 649 Discovery Metadata Name: 650 The name requested (e.g., "issuer"). This name is case-sensitive. 651 Names may not match other registered names in a case-insensitive 652 manner unless the Designated Experts state that there is a 653 compelling reason to allow an exception. 655 Discovery Metadata Description: 656 Brief description of the discovery metadata (e.g., "Issuer URL"). 658 Change Controller: 659 For Standards Track RFCs, list the "IESG". For others, give the 660 name of the responsible party. Other details (e.g., postal 661 address, email address, home page URI) may also be included. 663 Specification Document(s): 664 Reference to the document or documents that specify the parameter, 665 preferably including URIs that can be used to retrieve copies of 666 the documents. An indication of the relevant sections may also be 667 included but is not required. 669 8.1.2. Initial Registry Contents 671 o Discovery Metadata Name: "issuer" 672 o Discovery Metadata Description: URL of the authorization server's 673 configuration information location 674 o Change Controller: IESG 675 o Specification Document(s): Section 3 of [[ this specification ]] 677 o Discovery Metadata Name: "authorization_endpoint" 678 o Discovery Metadata Description: URL of the authorization server's 679 authorization endpoint 680 o Change Controller: IESG 681 o Specification Document(s): Section 3 of [[ this specification ]] 683 o Discovery Metadata Name: "token_endpoint" 684 o Discovery Metadata Description: URL of the authorization server's 685 token endpoint 686 o Change Controller: IESG 687 o Specification Document(s): Section 3 of [[ this specification ]] 689 o Discovery Metadata Name: "jwks_uri" 690 o Discovery Metadata Description: URL of the authorization server's 691 JWK Set document 692 o Change Controller: IESG 693 o Specification Document(s): Section 3 of [[ this specification ]] 695 o Discovery Metadata Name: "registration_endpoint" 696 o Discovery Metadata Description: URL of the authorization server's 697 OAuth 2.0 Dynamic Client Registration Endpoint 698 o Change Controller: IESG 699 o Specification Document(s): Section 3 of [[ this specification ]] 701 o Discovery Metadata Name: "scopes_supported" 702 o Discovery Metadata Description: JSON array containing a list of 703 the OAuth 2.0 "scope" values that this authorization server 704 supports 705 o Change Controller: IESG 706 o Specification Document(s): Section 3 of [[ this specification ]] 708 o Discovery Metadata Name: "response_types_supported" 709 o Discovery Metadata Description: JSON array containing a list of 710 the OAuth 2.0 "response_type" values that this authorization 711 server supports 712 o Change Controller: IESG 713 o Specification Document(s): Section 3 of [[ this specification ]] 714 o Discovery Metadata Name: "response_modes_supported" 715 o Discovery Metadata Description: JSON array containing a list of 716 the OAuth 2.0 "response_mode" values that this authorization 717 server supports 718 o Change Controller: IESG 719 o Specification Document(s): Section 3 of [[ this specification ]] 721 o Discovery Metadata Name: "grant_types_supported" 722 o Discovery Metadata Description: JSON array containing a list of 723 the OAuth 2.0 grant type values that this authorization server 724 supports 725 o Change Controller: IESG 726 o Specification Document(s): Section 3 of [[ this specification ]] 728 o Discovery Metadata Name: "token_endpoint_auth_methods_supported" 729 o Discovery Metadata Description: JSON array containing a list of 730 client authentication methods supported by this token endpoint 731 o Change Controller: IESG 732 o Specification Document(s): Section 3 of [[ this specification ]] 734 o Discovery Metadata Name: 735 "token_endpoint_auth_signing_alg_values_supported" 736 o Discovery Metadata Description: JSON array containing a list of 737 the JWS signing algorithms supported by the token endpoint for the 738 signature on the JWT used to authenticate the client at the token 739 endpoint 740 o Change Controller: IESG 741 o Specification Document(s): Section 3 of [[ this specification ]] 743 o Discovery Metadata Name: "service_documentation" 744 o Discovery Metadata Description: URL of a page containing human- 745 readable information that developers might want or need to know 746 when using the authorization server 747 o Change Controller: IESG 748 o Specification Document(s): Section 3 of [[ this specification ]] 750 o Discovery Metadata Name: "ui_locales_supported" 751 o Discovery Metadata Description: Languages and scripts supported 752 for the user interface, represented as a JSON array of BCP47 753 language tag values 754 o Change Controller: IESG 755 o Specification Document(s): Section 3 of [[ this specification ]] 757 o Discovery Metadata Name: "op_policy_uri" 758 o Discovery Metadata Description: URL that the authorization server 759 provides to the person registering the client to read about the 760 authorization server's requirements on how the client can use the 761 data provided by the authorization server 763 o Change Controller: IESG 764 o Specification Document(s): Section 3 of [[ this specification ]] 766 o Discovery Metadata Name: "op_tos_uri" 767 o Discovery Metadata Description: URL that the authorization server 768 provides to the person registering the client to read about 769 authorization server's terms of service 770 o Change Controller: IESG 771 o Specification Document(s): Section 3 of [[ this specification ]] 773 o Discovery Metadata Name: "revocation_endpoint" 774 o Discovery Metadata Description: URL of the authorization server's 775 OAuth 2.0 revocation endpoint 776 o Change Controller: IESG 777 o Specification Document(s): Section 3 of [[ this specification ]] 779 o Discovery Metadata Name: 780 "revocation_endpoint_auth_methods_supported" 781 o Discovery Metadata Description: JSON array containing a list of 782 client authentication methods supported by this revocation 783 endpoint 784 o Change Controller: IESG 785 o Specification Document(s): Section 3 of [[ this specification ]] 787 o Discovery Metadata Name: 788 "revocation_endpoint_auth_signing_alg_values_supported" 789 o Discovery Metadata Description: JSON array containing a list of 790 the JWS signing algorithms supported by the revocation endpoint 791 for the signature on the JWT used to authenticate the client at 792 the revocation endpoint 793 o Change Controller: IESG 794 o Specification Document(s): Section 3 of [[ this specification ]] 796 o Discovery Metadata Name: "introspection_endpoint" 797 o Discovery Metadata Description: URL of the authorization server's 798 OAuth 2.0 introspection endpoint 799 o Change Controller: IESG 800 o Specification Document(s): Section 3 of [[ this specification ]] 802 o Discovery Metadata Name: 803 "introspection_endpoint_auth_methods_supported" 804 o Discovery Metadata Description: JSON array containing a list of 805 client authentication methods supported by this introspection 806 endpoint 807 o Change Controller: IESG 808 o Specification Document(s): Section 3 of [[ this specification ]] 809 o Discovery Metadata Name: 810 "introspection_endpoint_auth_signing_alg_values_supported" 811 o Discovery Metadata Description: JSON array containing a list of 812 the JWS signing algorithms supported by the introspection endpoint 813 for the signature on the JWT used to authenticate the client at 814 the introspection endpoint 815 o Change Controller: IESG 816 o Specification Document(s): Section 3 of [[ this specification ]] 818 o Discovery Metadata Name: "code_challenge_methods_supported" 819 o Discovery Metadata Description: PKCE code challenge methods 820 supported by this authorization server 821 o Change Controller: IESG 822 o Specification Document(s): Section 3 of [[ this specification ]] 824 8.2. Updated Registration Instructions 826 This specification adds to the instructions for the Designated 827 Experts of the following IANA registries, both of which are in the 828 "OAuth Parameters" registry [IANA.OAuth.Parameters]: 829 o OAuth Access Token Types 830 o OAuth Token Endpoint Authentication Methods 832 IANA has added a link to this specification in the Reference sections 833 of these registries. [[ RFC Editor: The above sentence is written in 834 the past tense as it would appear in the final specification, even 835 though these links won't actually be created until after the IESG has 836 requested publication of the specification. Please delete this note 837 after the links are in place. ]] 839 For these registries, the designated experts must reject registration 840 requests in one registry for values already occurring in the other 841 registry. This is necessary because the 842 "introspection_endpoint_auth_methods_supported" parameter allows for 843 the use of values from either registry. That way, because the values 844 in the two registries will continue to be mutually exclusive, no 845 ambiguities will arise. 847 9. References 849 9.1. Normative References 851 [BCP195] Sheffer, Y., Holz, R., and P. Saint-Andre, 852 "Recommendations for Secure Use of Transport Layer 853 Security (TLS) and Datagram Transport Layer Security 854 (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, 855 May 2015, . 857 [IANA.OAuth.Parameters] 858 IANA, "OAuth Parameters", 859 . 861 [JWA] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 862 DOI 10.17487/RFC7518, May 2015, 863 . 865 [JWE] Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", 866 RFC 7516, DOI 10.17487/RFC7516, May 2015, 867 . 869 [JWK] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/ 870 RFC7517, May 2015, . 872 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 873 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, 874 May 2015, . 876 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 877 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 878 . 880 [OAuth.Post] 881 Jones, M. and B. Campbell, "OAuth 2.0 Form Post Response 882 Mode", April 2015, . 885 [OAuth.Responses] 886 de Medeiros, B., Ed., Scurtescu, M., Tarjan, P., and M. 887 Jones, "OAuth 2.0 Multiple Response Type Encoding 888 Practices", February 2014, . 891 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 892 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 893 RFC2119, March 1997, 894 . 896 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 897 RFC 2246, DOI 10.17487/RFC2246, January 1999, 898 . 900 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 901 Resource Identifier (URI): Generic Syntax", STD 66, 902 RFC 3986, DOI 10.17487/RFC3986, January 2005, 903 . 905 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 906 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 907 DOI 10.17487/RFC5226, May 2008, 908 . 910 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 911 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 912 RFC5246, August 2008, 913 . 915 [RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying 916 Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, 917 September 2009, . 919 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 920 Uniform Resource Identifiers (URIs)", RFC 5785, 921 DOI 10.17487/RFC5785, April 2010, 922 . 924 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 925 Verification of Domain-Based Application Service Identity 926 within Internet Public Key Infrastructure Using X.509 927 (PKIX) Certificates in the Context of Transport Layer 928 Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, 929 March 2011, . 931 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 932 RFC 6749, DOI 10.17487/RFC6749, October 2012, 933 . 935 [RFC7009] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth 936 2.0 Token Revocation", RFC 7009, DOI 10.17487/RFC7009, 937 August 2013, . 939 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 940 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, 941 September 2013, . 943 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 944 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, 945 March 2014, . 947 [RFC7565] Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565, 948 DOI 10.17487/RFC7565, May 2015, 949 . 951 [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 952 P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 953 RFC 7591, DOI 10.17487/RFC7591, July 2015, 954 . 956 [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 957 for Code Exchange by OAuth Public Clients", RFC 7636, 958 DOI 10.17487/RFC7636, September 2015, 959 . 961 [RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection", 962 RFC 7662, DOI 10.17487/RFC7662, October 2015, 963 . 965 [UNICODE] The Unicode Consortium, "The Unicode Standard", 966 . 968 [USA15] Davis, M. and K. Whistler, "Unicode Normalization Forms", 969 Unicode Standard Annex 15, June 2015, 970 . 972 9.2. Informative References 974 [OpenID.Core] 975 Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 976 C. Mortimore, "OpenID Connect Core 1.0", November 2014, 977 . 979 [OpenID.Discovery] 980 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 981 Connect Discovery 1.0", November 2014, . 984 [OpenID.Registration] 985 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 986 Dynamic Client Registration 1.0", November 2014, . 989 Appendix A. Acknowledgements 991 This specification is based on the OpenID Connect Discovery 1.0 992 specification, which was produced by the OpenID Connect working group 993 of the OpenID Foundation. 995 Appendix B. Document History 997 [[ to be removed by the RFC Editor before publication as an RFC ]] 998 -00 1000 o Created the initial working group version based on 1001 draft-jones-oauth-discovery-01, with no normative changes. 1003 Authors' Addresses 1005 Michael B. Jones 1006 Microsoft 1008 Email: mbj@microsoft.com 1009 URI: http://self-issued.info/ 1011 Nat Sakimura 1012 Nomura Research Institute, Ltd. 1014 Email: n-sakimura@nri.co.jp 1015 URI: http://nat.sakimura.org/ 1017 John Bradley 1018 Ping Identity 1020 Email: ve7jtb@ve7jtb.com 1021 URI: http://www.thread-safe.com/