idnits 2.17.1 draft-ietf-oauth-dyn-reg-18.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 3, 2014) is 3582 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) ** 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 6125 (Obsoleted by RFC 9525) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track M. Jones 5 Expires: January 4, 2015 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 July 3, 2014 14 OAuth 2.0 Dynamic Client Registration Protocol 15 draft-ietf-oauth-dyn-reg-18 17 Abstract 19 This specification defines mechanisms for dynamically registering 20 OAuth 2.0 clients with authorization servers. Registration requests 21 send a set of desired client metadata values to the authorization 22 server and the resulting registration responses return a client 23 identifier to use at the authorization server and the client metadata 24 values registered for the client. The client can then use this 25 registration information to communicate with the authorization server 26 using the OAuth 2.0 protocol. This specification also defines a set 27 of common client metadata fields and values for clients to use during 28 registration. 30 Status of this Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on January 4, 2015. 47 Copyright Notice 48 Copyright (c) 2014 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 67 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 68 2.1. Relationship between Grant Types and Response Types . . . 11 69 2.2. Human Readable Client Metadata . . . . . . . . . . . . . . 12 70 2.3. Software Statement . . . . . . . . . . . . . . . . . . . . 13 71 3. Client Registration Endpoint . . . . . . . . . . . . . . . . . 14 72 3.1. Client Registration Request . . . . . . . . . . . . . . . 14 73 3.2. Client Registration Response . . . . . . . . . . . . . . . 17 74 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 4.1. Client Information Response . . . . . . . . . . . . . . . 17 76 4.2. Client Registration Error Response . . . . . . . . . . . . 18 77 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 78 5.1. OAuth Dynamic Registration Client Metadata Registry . . . 20 79 5.1.1. Registration Template . . . . . . . . . . . . . . . . 21 80 5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21 81 5.2. OAuth Token Endpoint Authentication Methods Registry . . . 24 82 5.2.1. Registration Template . . . . . . . . . . . . . . . . 24 83 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 25 84 6. Security Considerations . . . . . . . . . . . . . . . . . . . 25 85 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 86 7.1. Normative References . . . . . . . . . . . . . . . . . . . 28 87 7.2. Informative References . . . . . . . . . . . . . . . . . . 29 88 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 29 89 A.1. Open versus Protected Dynamic Client Registration . . . . 29 90 A.1.1. Open Dynamic Client Registration . . . . . . . . . . . 29 91 A.1.2. Protected Dynamic Client Registration . . . . . . . . 29 92 A.2. Registration Without or With Software Statements . . . . . 30 93 A.2.1. Registration Without a Software Statement . . . . . . 30 94 A.2.2. Registration With a Software Statement . . . . . . . . 30 95 A.3. Registration by the Client or Developer . . . . . . . . . 30 96 A.3.1. Registration by the Client . . . . . . . . . . . . . . 30 97 A.3.2. Registration by the Developer . . . . . . . . . . . . 30 98 A.4. Client ID per Client Instance or per Client Software . . . 30 99 A.4.1. Client ID per Client Software Instance . . . . . . . . 30 100 A.4.2. Client ID Shared Among All Instances of Client 101 Software . . . . . . . . . . . . . . . . . . . . . . . 31 102 A.5. Stateful or Stateless Registration . . . . . . . . . . . . 31 103 A.5.1. Stateful Client Registration . . . . . . . . . . . . . 31 104 A.5.2. Stateless Client Registration . . . . . . . . . . . . 31 105 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 31 106 Appendix C. Document History . . . . . . . . . . . . . . . . . . 32 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 109 1. Introduction 111 In order for an OAuth 2.0 client to utilize an OAuth 2.0 112 authorization server, the client needs specific information to 113 interact with the server, including an OAuth 2.0 client identifier to 114 use at that server. This specification describes how an OAuth 2.0 115 client can be dynamically registered with an authorization server to 116 obtain this information. 118 As part of the registration process, this specification also defines 119 a mechanism for the client to present the authorization server with a 120 set of metadata, such as a set of valid redirection URIs. This 121 metadata can either be communicated in a self-asserted fashion or as 122 a set of metadata called a software statement, which is digitally 123 signed or MACed; in the case of a software statement, the issuer is 124 vouching for the validity of the data about the client. 126 Traditionally, registration of a client with an authorization server 127 is performed manually. The mechanisms defined in this specification 128 can be used either for a client to dynamically register itself with 129 authorization servers or for a client developer to programmatically 130 register the client with authorization servers. 132 1.1. Notational Conventions 134 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 135 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 136 document are to be interpreted as described in [RFC2119]. 138 Unless otherwise noted, all the protocol parameter names and values 139 are case sensitive. 141 1.2. Terminology 143 This specification uses the terms "access token", "authorization 144 code", "authorization endpoint", "authorization grant", 145 "authorization server", "client", "client identifier", "client 146 secret", "grant type", "protected resource", "redirection URI", 147 "refresh token", "resource owner", "resource server", "response 148 type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and uses 149 the term "Claim" defined by JSON Web Token (JWT) [JWT]. 151 This specification defines the following terms: 153 Client Developer 154 The person or organization that builds a client software package 155 and prepares it for distribution. 157 Client Instance 158 A deployed instance of a piece of client software. 160 Client Software 161 Software implementing an OAuth 2.0 client. 163 Client Registration Endpoint 164 OAuth 2.0 endpoint through which a client can be registered at an 165 authorization server. The means by which the URL for this 166 endpoint is obtained are out of scope for this specification. 168 Initial Access Token 169 OAuth 2.0 access token optionally issued by an authorization 170 server to a developer or client and used to authorize calls to the 171 client registration endpoint. The type and format of this token 172 are likely service-specific and are out of scope for this 173 specification. The means by which the authorization server issues 174 this token as well as the means by which the registration endpoint 175 validates this token are out of scope for this specification. Use 176 of an initial access token is required when the authorization 177 server limits the parties that can register a client. 179 Deployment Organization 180 An administrative security domain under which, a software API is 181 deployed and protected by an OAuth 2.0 framework. In simple cloud 182 deployments, the software API publisher and the deployment 183 organization may be the same. In other scenarios, a software 184 publisher may be working with many different deployment 185 organizations. 187 Software API Deployment 188 A deployed instance of a software API that is protected by OAuth 189 2.0 in a particular deployment organization domain. For any 190 particular software API, there may be one or more deployments. A 191 software API deployment typically has an associated OAuth 2.0 192 authorization server as well as a client registration endpoint. 193 The means by which endpoints are obtained are out of scope for 194 this specification. 196 Software API Publisher 197 The organization that defines a particular web accessible API that 198 may deployed in one or more deployment environments. A publisher 199 may be any commercial, public, private, or open source 200 organization that is responsible for publishing and distributing 201 software that may be protected via OAuth 2.0. In some cases a 202 software API publisher and a client developer may be the same 203 organization. 205 Software Statement 206 Digitally signed or MACed JSON Web Token (JWT) [JWT] that asserts 207 metadata values about the client software. In some cases, a 208 software statement will be issued directly by the organization or 209 developer that creates the client software. In other cases, a 210 software statement will be issued by a third party organization 211 for use by the organization or developer that creates the client 212 software. In both cases, the trust relationship the authorization 213 server has with the issuer of the software statement is intended 214 to be used as an input to the evaluation of whether the 215 registration request is accepted. A software statement can be 216 presented to an authorization server as part of a client 217 registration request. 219 1.3. Protocol Flow 221 +--------(A)- Initial Access Token (OPTIONAL) 222 | 223 | +----(B)- Software Statement (OPTIONAL) 224 | | 225 v v 226 +-----------+ +---------------+ 227 | |--(C)- Client Registration Request -->| Client | 228 | Client or | | Registration | 229 | Developer |<-(D)- Client Information Response ---| Endpoint | 230 | | +---------------+ 231 +-----------+ 233 Figure 1: Abstract Dynamic Client Registration Flow 235 The abstract OAuth 2.0 client dynamic registration flow illustrated 236 in Figure 1 describes the interaction between the client or developer 237 and the endpoint defined in this specification. This figure does not 238 demonstrate error conditions. This flow includes the following 239 steps: 241 (A) Optionally, the client or developer is issued an initial access 242 token giving access to the client registration endpoint. The 243 method by which the initial access token is issued to the client 244 or developer is out of scope for this specification. 246 (B) Optionally, the client or developer is issued a software 247 statement for use with the client registration endpoint. The 248 method by which the software statement is issued to the client or 249 developer is out of scope for this specification. 251 (C) The client or developer calls the client registration endpoint 252 with its desired registration metadata, optionally including the 253 initial access token from (A) if one is required by the 254 authorization server. 256 (D) The authorization server registers the client and returns the 257 client's registered metadata, a client identifier that is unique 258 at the server, a set of client credentials such as a client secret 259 if applicable for this client, and possibly other values. 261 2. Client Metadata 263 Clients have a set of metadata values associated with their client 264 identifier at an authorization server, such as the list of valid 265 redirection URIs or a display name. 267 The client metadata values are used in two ways: 269 o as input values to registration requests, and 271 o as output values in registration responses. 273 The following client metadata fields are defined by this 274 specification. The implementation and use of all client metadata 275 fields is OPTIONAL, other than "redirect_uris". 277 redirect_uris 278 Array of redirection URIs for use in redirect-based flows such as 279 the authorization code and implicit flows. As required by Section 280 2 of OAuth 2.0 [RFC6749], clients using flows with redirection 281 MUST register their redirection URI values. Authorization servers 282 MUST implement support for this metadata value. 284 token_endpoint_auth_method 285 The requested authentication method for the token endpoint. 286 Values defined by this specification are: 288 * "none": The client is a public client as defined in OAuth 2.0 289 and does not have a client secret. 291 * "client_secret_post": The client uses the HTTP POST parameters 292 defined in OAuth 2.0 section 2.3.1. 294 * "client_secret_basic": the client uses HTTP Basic defined in 295 OAuth 2.0 section 2.3.1 297 Additional values can be defined via the IANA OAuth Token Endpoint 298 Authentication Methods Registry established in Section 5.2. 299 Absolute URIs can also be used as values for this parameter 300 without being registered. If unspecified or omitted, the default 301 is "client_secret_basic", denoting HTTP Basic Authentication 302 Scheme as specified in Section 2.3.1 of OAuth 2.0. 304 grant_types 305 Array of OAuth 2.0 grant types that the client may use. These 306 grant types are defined as follows: 308 * "authorization_code": The Authorization Code Grant described in 309 OAuth 2.0 Section 4.1 311 * "implicit": The Implicit Grant described in OAuth 2.0 Section 312 4.2 314 * "password": The Resource Owner Password Credentials Grant 315 described in OAuth 2.0 Section 4.3 317 * "client_credentials": The Client Credentials Grant described in 318 OAuth 2.0 Section 4.4 320 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 321 Section 6. 323 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 324 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 326 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 327 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 328 [OAuth.SAML2]. 330 Authorization Servers MAY allow for other values as defined in 331 grant type extensions to OAuth 2.0. The extension process is 332 described in OAuth 2.0 Section 2.5. If the token endpoint is used 333 in the grant type, the value of this parameter MUST be the same as 334 the value of the "grant_type" parameter passed to the token 335 endpoint defined in the extension. If omitted, the default is 336 that the client will use only the "authorization_code" Grant Type. 338 application_type 339 OPTIONAL. Kind of the application. The default, if omitted, is 340 "web". The defined values are "native" or "web". 342 response_types 343 Array of the OAuth 2.0 response types that the client may use. 344 These response types are defined as follows: 346 * "code": The Authorization Code response described in OAuth 2.0 347 Section 4.1. 349 * "token": The Implicit response described in OAuth 2.0 Section 350 4.2. 352 Authorization servers MAY allow for other values as defined in 353 response type extensions to OAuth 2.0. The extension process is 354 described in OAuth 2.0 Section 2.5. If the authorization endpoint 355 is used by the grant type, the value of this parameter MUST be the 356 same as the value of the "response_type" parameter passed to the 357 authorization endpoint defined in the extension. If omitted, the 358 default is that the client will use only the "code" response type. 360 client_name 361 Human-readable name of the client to be presented to the user 362 during authorization. If omitted, the authorization server MAY 363 display the raw "client_id" value to the user instead. It is 364 RECOMMENDED that clients always send this field. The value of 365 this field MAY be internationalized, as described in Section 2.2. 367 client_uri 368 URL of a Web page providing information about the client. If 369 present, the server SHOULD display this URL to the end user in a 370 clickable fashion. It is RECOMMENDED that clients always send 371 this field. The value of this field MUST point to a valid web 372 page. The value of this field MAY be internationalized, as 373 described in Section 2.2. 375 logo_uri 376 URL that references a logo for the client. If present, the server 377 SHOULD display this image to the end user during approval. The 378 value of this field MUST point to a valid image file. The value 379 of this field MAY be internationalized, as described in 380 Section 2.2. 382 scope 383 Space separated list of scope values (as described in Section 3.3 384 of OAuth 2.0 [RFC6749]) that the client can use when requesting 385 access tokens. The semantics of values in this list is service 386 specific. If omitted, an authorization server MAY register a 387 client with a default set of scopes. 389 contacts 390 Array of strings representing ways to contact people responsible 391 for this client, typically email addresses. The authorization 392 server MAY make these addresses available to end users for support 393 requests for the client. 395 tos_uri 396 URL that points to a human-readable Terms of Service document for 397 the client. The authorization server SHOULD display this URL to 398 the end-user if it is given. The Terms of Service usually 399 describe a contractual relationship between the end-user and the 400 client that the end-user accepts when authorizing the client. The 401 value of this field MUST point to a valid web page. The value of 402 this field MAY be internationalized, as described in Section 2.2. 404 policy_uri 405 URL that points to a human-readable Policy document for the 406 client. The authorization server SHOULD display this URL to the 407 end-user if it is given. The policy usually describes how an end- 408 user's data will be used by the client. The value of this field 409 MUST point to a valid web page. The value of this field MAY be 410 internationalized, as described in Section 2.2. 412 jwks_uri 413 URL of the client's JSON Web Key Set [JWK] document containing the 414 client's public keys. The value of this field MUST point to a 415 valid JWK Set document. These keys can be used by higher level 416 protocols that use signing or encryption. 418 jwks 419 JSON Web Key Set [JWK] value containing the client's public keys. 420 The value of this field MUST be a JSON object containing a valid 421 JWK Set. These keys can be used by higher level protocols that use 422 signing or encryption. This parameter is intended to be used by 423 clients that cannot use the "jwks_uri" parameter. For instance, a 424 native application might not have a location to host the contents 425 of the JWK Set that would be reachable by the authorization 426 server. The "jwks_uri" and "jwks" parameters MUST NOT be used 427 together. 429 software_id 430 Identifier for the software that comprises a client. Unlike 431 "client_id", which is issued by the authorization server and may 432 vary between instances, the "software_id" is asserted by the 433 client software on behalf of the software developer and is 434 intended to be shared among all instances of the client software. 435 The identifier SHOULD NOT change when software version changes or 436 when a new installation occurs. 438 software_version 439 Version identifier for the software that comprises a client. The 440 value of this field is a string that is intended to be compared 441 using string equality matching. The value of the 442 "software_version" SHOULD change on any update to the client 443 software. 445 Extensions and profiles of this specification MAY expand this list. 446 The authorization server MUST ignore any client metadata values sent 447 by the client that it does not understand. 449 Client metadata values can either be communicated directly in the 450 body of a registration request, as described in Section 3.1, or 451 included as claims in a software statement, as described in 452 Section 2.3, or a mixture of both. If the same client metadata name 453 is present in both locations and the software statement is trusted by 454 the authorization server, the value of a claim in the software 455 statement MUST take precedence. 457 2.1. Relationship between Grant Types and Response Types 459 The "grant_types" and "response_types" values described above are 460 partially orthogonal, as they refer to arguments passed to different 461 endpoints in the OAuth protocol. However, they are related in that 462 the "grant_types" available to a client influence the 463 "response_types" that the client is allowed to use, and vice versa. 464 For instance, a "grant_types" value that includes 465 "authorization_code" implies a "response_types" value that includes 466 "code", as both values are defined as part of the OAuth 2.0 467 authorization code grant. As such, a server supporting these fields 468 SHOULD take steps to ensure that a client cannot register itself into 469 an inconsistent state, for example by returning an 470 "invalid_client_metadata" error response to an inconsistent 471 registration request. 473 The correlation between the two fields is listed in the table below. 475 +-----------------------------------------------+-------------------+ 476 | grant_types value includes: | response_types | 477 | | value includes: | 478 +-----------------------------------------------+-------------------+ 479 | authorization_code | code | 480 | implicit | token | 481 | password | (none) | 482 | client_credentials | (none) | 483 | refresh_token | (none) | 484 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 485 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 486 +-----------------------------------------------+-------------------+ 488 Extensions and profiles of this document that introduce new values to 489 either the "grant_types" or "response_types" parameter MUST document 490 all correspondences between these two parameter types. 492 2.2. Human Readable Client Metadata 494 Human-readable client metadata values and client metadata values that 495 reference human-readable values MAY be represented in multiple 496 languages and scripts. For example, the values of fields such as 497 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 498 might have multiple locale-specific values in some client 499 registrations to facilitate use in different locations. 501 To specify the languages and scripts, BCP47 [RFC5646] language tags 502 are added to client metadata member names, delimited by a # 503 character. Since JSON [RFC7159] member names are case sensitive, it 504 is RECOMMENDED that language tag values used in Claim Names be 505 spelled using the character case with which they are registered in 506 the IANA Language Subtag Registry [IANA.Language]. In particular, 507 normally language names are spelled with lowercase characters, region 508 names are spelled with uppercase characters, and languages are 509 spelled with mixed case characters. However, since BCP47 language 510 tag values are case insensitive, implementations SHOULD interpret the 511 language tag values supplied in a case insensitive manner. Per the 512 recommendations in BCP47, language tag values used in metadata member 513 names should only be as specific as necessary. For instance, using 514 "fr" might be sufficient in many contexts, rather than "fr-CA" or 515 "fr-FR". 517 For example, a client could represent its name in English as 518 ""client_name#en": "My Client"" and its name in Japanese as 519 ""client_name#ja-Jpan-JP": 520 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 521 registration request. The authorization server MAY display any or 522 all of these names to the resource owner during the authorization 523 step, choosing which name to display based on system configuration, 524 user preferences or other factors. 526 If any human-readable field is sent without a language tag, parties 527 using it MUST NOT make any assumptions about the language, character 528 set, or script of the string value, and the string value MUST be used 529 as-is wherever it is presented in a user interface. To facilitate 530 interoperability, it is RECOMMENDED that clients and servers use a 531 human-readable field without any language tags in addition to any 532 language-specific fields, and it is RECOMMENDED that any human- 533 readable fields sent without language tags contain values suitable 534 for display on a wide variety of systems. 536 Implementer's Note: Many JSON libraries make it possible to reference 537 members of a JSON object as members of an object construct in the 538 native programming environment of the library. However, while the 539 "#" character is a valid character inside of a JSON object's member 540 names, it is not a valid character for use in an object member name 541 in many programming environments. Therefore, implementations will 542 need to use alternative access forms for these claims. For instance, 543 in JavaScript, if one parses the JSON as follows, "var j = 544 JSON.parse(json);", then the member "client_name#en-us" can be 545 accessed using the JavaScript syntax "j["client_name#en-us"]". 547 2.3. Software Statement 549 A software statement is a JSON Web Token (JWT) [JWT] that asserts 550 metadata values about the client software as a bundle. A set of 551 claims that can be used in a software statement are defined 552 Section 2. When presented to the authorization server as part of a 553 client registration request, the software statement MUST be digitally 554 signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer) 555 claim denoting the party attesting to the claims in the software 556 statement. It is RECOMMENDED that software statements be digitally 557 signed using the "RS256" signature algorithm, although particular 558 applications MAY specify the use of different algorithms. 560 The means by which a client or developer obtains a software statement 561 are outside the scope of this specification. Some common methods 562 could include a client developer generating a client-specific JWT 563 registering with a software API publisher to obtain a software 564 statement for a class of clients. The software statement is 565 typically distributed with all instances of a client application. 567 The criteria by which authorization servers determine whether to 568 trust and utilize the information in a software statement are beyond 569 the scope of this specification. 571 In some cases, authorization servers MAY choose to accept a software 572 statement value directly as a client identifier in an authorization 573 request, without a prior dynamic client registration having been 574 performed. The circumstances under which an authorization server 575 would do so, and the specific software statement characteristics 576 required in this case, are beyond the scope of this specification. 578 3. Client Registration Endpoint 580 The client registration endpoint is an OAuth 2.0 endpoint defined in 581 this document that is designed to allow a client to be registered 582 with the authorization server. The client registration endpoint MUST 583 accept HTTP POST messages with request parameters encoded in the 584 entity body using the "application/json" format. The client 585 registration endpoint MUST be protected by a transport-layer security 586 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] 587 and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer 588 mechanisms meeting its security requirements. When using TLS, the 589 client MUST perform a TLS/SSL server certificate check, per RFC 6125 590 [RFC6125]. 592 The client registration endpoint MAY be an OAuth 2.0 protected 593 resource and accept an initial access token in the form of an OAuth 594 2.0 [RFC6749] access token to limit registration to only previously 595 authorized parties. The method by which the initial access token is 596 obtained by the client or developer is generally out-of-band and is 597 out of scope for this specification. The method by which the initial 598 access token is verified and validated by the client registration 599 endpoint is out of scope for this specification. 601 To support open registration and facilitate wider interoperability, 602 the client registration endpoint SHOULD allow registration requests 603 with no authorization (which is to say, with no initial access token 604 in the request). These requests MAY be rate-limited or otherwise 605 limited to prevent a denial-of-service attack on the client 606 registration endpoint. 608 3.1. Client Registration Request 610 This operation registers a client with the authorization server. The 611 authorization server assigns this client a unique client identifier, 612 optionally assigns a client secret, and associates the metadata given 613 in the request with the issued client identifier. The request 614 includes any client metadata parameters being specified for the 615 client during the registration. The authorization server MAY 616 provision default values for any items omitted in the client 617 metadata. 619 To register, the client or developer sends an HTTP POST to the client 620 registration endpoint with a content type of "application/json". The 621 HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON 622 object and all requested client metadata values as top-level members 623 of that JSON object. 625 Client metadata values may also be provided in a software statement, 626 as described in Section 2.3. Software statements are included in the 627 requesting JSON object using this member: 629 software_statement 630 A software statement containing client metadata values about the 631 client software as claims. 633 For example, if the server supports open registration (with no 634 initial access token), the client could send the following 635 registration request to the client registration endpoint: 637 The following is a non-normative example request not using an initial 638 access token (with line wraps within values for display purposes 639 only): 641 POST /register HTTP/1.1 642 Content-Type: application/json 643 Accept: application/json 644 Host: server.example.com 646 { 647 "redirect_uris":[ 648 "https://client.example.org/callback", 649 "https://client.example.org/callback2"], 650 "client_name":"My Example Client", 651 "client_name#ja-Jpan-JP": 652 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 653 "token_endpoint_auth_method":"client_secret_basic", 654 "logo_uri":"https://client.example.org/logo.png", 655 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 656 "example_extension_parameter": "example_value" 657 } 659 Alternatively, if the server supports authorized registration, the 660 developer or the client will be provisioned with an initial access 661 token. (The method by which the initial access token is obtained is 662 out of scope for this specification.) The developer or client sends 663 the following authorized registration request to the client 664 registration endpoint. Note that the initial access token sent in 665 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 666 2.0 token type could be used by an authorization server. 668 The following is a non-normative example request using an initial 669 access token (with line wraps within values for display purposes 670 only): 672 POST /register HTTP/1.1 673 Content-Type: application/json 674 Accept: application/json 675 Authorization: Bearer ey23f2.adfj230.af32-developer321 676 Host: server.example.com 678 { 679 "redirect_uris":["https://client.example.org/callback", 680 "https://client.example.org/callback2"], 681 "client_name":"My Example Client", 682 "client_name#ja-Jpan-JP": 683 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 684 "token_endpoint_auth_method":"client_secret_basic", 685 "policy_uri":"https://client.example.org/policy.html", 686 "jwks":{"keys":[{...omitted for brevity...}]}, 687 "example_extension_parameter": "example_value" 688 } 690 In the following example, some registration parameters are conveyed 691 as claims in a software statement, while some values specific to the 692 client instance are conveyed as regular parameters (with line wraps 693 within values for display purposes only): 695 POST /register HTTP/1.1 696 Content-Type: application/json 697 Accept: application/json 698 Host: server.example.com 700 { 701 "redirect_uris":[ 702 "https://client.example.org/callback", 703 "https://client.example.org/callback2" 704 ], 705 "software_statement":"eyJhbGciOiJFUzI1NiJ9. 706 eyJpc3Mi[...omitted for brevity...]. 707 J9l-ZhwP[...omitted for brevity...]", 708 "scope":"read write", 709 "example_extension_parameter":"example_value" 710 } 712 3.2. Client Registration Response 714 Upon successful registration, the authorization server returns a 715 client identifier for the client. The server responds with an HTTP 716 201 Created code and a body of type "application/json" with content 717 as described in Section 4.1. 719 Upon an unsuccessful registration, the authorization server responds 720 with an error, as described in Section 4.2. 722 4. Responses 724 The following responses are sent in response to registration 725 requests. 727 4.1. Client Information Response 729 The response contains the client identifier as well as the client 730 secret, if the client is a confidential client. The response MAY 731 contain additional fields as specified by extensions to this 732 specification. 734 client_id 735 REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be 736 currently valid for any other registered client, though an 737 authorization server MAY issue the same client identifier to 738 multiple instances of a registered client, at its discretion. 740 client_secret 741 OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be 742 unique for each "client_id". This value is used by confidential 743 clients to authenticate to the token endpoint as described in 744 OAuth 2.0 [RFC6749] Section 2.3.1. 746 client_id_issued_at 747 OPTIONAL. Time at which the client identifier was issued. The 748 time is represented as the number of seconds from 1970-01- 749 01T0:0:0Z as measured in UTC until the date/time. 751 client_secret_expires_at 752 REQUIRED if "client_secret" is issued. Time at which the client 753 secret will expire or 0 if it will not expire. The time is 754 represented as the number of seconds from 1970-01-01T0:0:0Z as 755 measured in UTC until the date/time. 757 Additionally, the authorization server MUST return all registered 758 metadata about this client, including any fields provisioned by the 759 authorization server itself. The authorization server MAY reject or 760 replace any of the client's requested metadata values submitted 761 during the registration or update requests and substitute them with 762 suitable values. 764 The response is an "application/json" document with all parameters as 765 top-level members of a JSON object [RFC7159]. 767 If a software statement was used as part of the registration, its 768 value MUST be returned in the response along with other metadata. 769 Client metadata elements used from the software statement MUST also 770 be returned directly as top-level client metadata values in the 771 registration response (possibly with different values, since the 772 values requested and the values used may differ). 774 Following is a non-normative example response: 776 HTTP/1.1 201 Created 777 Content-Type: application/json 778 Cache-Control: no-store 779 Pragma: no-cache 781 { 782 "client_id":"s6BhdRkqt3", 783 "client_secret": "cf136dc3c1fc93f31185e5885805d", 784 "client_id_issued_at":2893256800, 785 "client_secret_expires_at":2893276800, 786 "redirect_uris":[ 787 "https://client.example.org/callback", 788 "https://client.example.org/callback2"], 789 "grant_types": ["authorization_code", "refresh_token"], 790 "client_name":"My Example Client", 791 "client_name#ja-Jpan-JP": 792 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 793 "token_endpoint_auth_method":"client_secret_basic", 794 "logo_uri":"https://client.example.org/logo.png", 795 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 796 "example_extension_parameter": "example_value" 797 } 799 4.2. Client Registration Error Response 801 When an OAuth 2.0 error condition occurs, such as the client 802 presenting an invalid initial access token, the authorization server 803 returns an error response appropriate to the OAuth 2.0 token type. 805 When a registration error condition occurs, the authorization server 806 returns an HTTP 400 status code (unless otherwise specified) with 807 content type "application/json" consisting of a JSON object [RFC7159] 808 describing the error in the response body. 810 Two members are defined for inclusion in the JSON object: 812 error 813 REQUIRED. Single ASCII error code string. 815 error_description 816 OPTIONAL. Human-readable ASCII text description of the error used 817 for debugging. 819 Other members MAY also be included, and if not understood, MUST be 820 ignored. 822 This specification defines the following error codes: 824 invalid_redirect_uri 825 The value of one or more redirection URIs is invalid. 827 invalid_client_metadata 828 The value of one of the client metadata fields is invalid and the 829 server has rejected this request. Note that an authorization 830 server MAY choose to substitute a valid value for any requested 831 parameter of a client's metadata. 833 invalid_software_statement 834 The software statement presented is invalid. 836 unapproved_software_statement 837 The software statement presented is not approved for use by this 838 authorization server. 840 Following is a non-normative example of an error response resulting 841 from a redirection URI that has been blacklisted by the authorization 842 server (with line wraps within values for display purposes only): 844 HTTP/1.1 400 Bad Request 845 Content-Type: application/json 846 Cache-Control: no-store 847 Pragma: no-cache 849 { 850 "error": "invalid_redirect_uri", 851 "error_description": "The redirection URI 852 http://sketchy.example.com is not allowed by this server." 853 } 855 Following is a non-normative example of an error response resulting 856 from an inconsistent combination of "response_types" and 857 "grant_types" values (with line wraps within values for display 858 purposes only): 860 HTTP/1.1 400 Bad Request 861 Content-Type: application/json 862 Cache-Control: no-store 863 Pragma: no-cache 865 { 866 "error": "invalid_client_metadata", 867 "error_description": "The grant type 'authorization_code' must be 868 registered along with the response type 'code' but found only 869 'implicit' instead." 870 } 872 5. IANA Considerations 874 5.1. OAuth Dynamic Registration Client Metadata Registry 876 This specification establishes the OAuth Dynamic Registration Client 877 Metadata registry. 879 OAuth registration client metadata values are registered with a 880 Specification Required ([RFC5226]) after a two-week review period on 881 the oauth-ext-review@ietf.org mailing list, on the advice of one or 882 more Designated Experts. However, to allow for the allocation of 883 values prior to publication, the Designated Expert(s) may approve 884 registration once they are satisfied that such a specification will 885 be published. 887 Registration requests must be sent to the oauth-ext-review@ietf.org 888 mailing list for review and comment, with an appropriate subject 889 (e.g., "Request to register OAuth Dynamic Registration Client 890 Metadata name: example"). 892 Within the review period, the Designated Expert(s) will either 893 approve or deny the registration request, communicating this decision 894 to the review list and IANA. Denials should include an explanation 895 and, if applicable, suggestions as to how to make the request 896 successful. 898 IANA must only accept registry updates from the Designated Expert(s) 899 and should direct all requests for registration to the review mailing 900 list. 902 5.1.1. Registration Template 904 Client Metadata Name: 905 The name requested (e.g., "example"). This name is case 906 sensitive. Names that match other registered names in a case 907 insensitive manner SHOULD NOT be accepted. 909 Client Metadata Description: 910 Brief description of the metadata value (e.g., "Example 911 description"). 913 Change controller: 914 For Standards Track RFCs, state "IETF". For others, give the name 915 of the responsible party. Other details (e.g., postal address, 916 email address, home page URI) may also be included. 918 Specification document(s): 919 Reference to the document(s) that specify the token endpoint 920 authorization method, preferably including a URI that can be used 921 to retrieve a copy of the document(s). An indication of the 922 relevant sections may also be included but is not required. 924 5.1.2. Initial Registry Contents 926 The initial contents of the OAuth Dynamic Registration Client 927 Metadata registry are: 929 o Client Metadata Name: "redirect_uris" 930 o Client Metadata Description: Array of redirection URIs for use in 931 redirect-based flows 932 o Change controller: IESG 933 o Specification document(s): [[ this document ]] 935 o Client Metadata Name: "token_endpoint_auth_method" 936 o Client Metadata Description: Requested authentication method for 937 the token endpoint 938 o Change controller: IESG 939 o Specification document(s): [[ this document ]] 941 o Client Metadata Name: "grant_types" 942 o Client Metadata Description: Array of OAuth 2.0 grant types that 943 the client may use 944 o Change controller: IESG 945 o Specification document(s): [[ this document ]] 947 o Client Metadata Name: "response_types" 948 o Client Metadata Description: Array of the OAuth 2.0 response types 949 that the client may use 950 o Change controller: IESG 951 o Specification document(s): [[ this document ]] 953 o Client Metadata Name: "client_name" 954 o Client Metadata Description: Human-readable name of the client to 955 be presented to the user 956 o Change Controller: IESG 957 o Specification Document(s): [[ this document ]] 959 o Client Metadata Name: "client_uri" 960 o Client Metadata Description: URL of a Web page providing 961 information about the client 962 o Change Controller: IESG 963 o Specification Document(s): [[ this document ]] 965 o Client Metadata Name: "logo_uri" 966 o Client Metadata Description: URL that references a logo for the 967 client 968 o Change Controller: IESG 969 o Specification Document(s): [[ this document ]] 971 o Client Metadata Name: "scope" 972 o Client Metadata Description: Space separated list of scope values 973 o Change Controller: IESG 974 o Specification Document(s): [[ this document ]] 976 o Client Metadata Name: "contacts" 977 o Client Metadata Description: Array of strings representing ways to 978 contact people responsible for this client, typically email 979 addresses 980 o Change Controller: IESG 981 o Specification document(s): [[ this document ]] 983 o Client Metadata Name: "tos_uri" 984 o Client Metadata Description: URL that points to a human-readable 985 Terms of Service document for the client 986 o Change Controller: IESG 987 o Specification Document(s): [[ this document ]] 989 o Client Metadata Name: "policy_uri" 990 o Client Metadata Description: URL that points to a human-readable 991 Policy document for the client 992 o Change Controller: IESG 993 o Specification Document(s): [[ this document ]] 994 o Client Metadata Name: "jwks_uri" 995 o Client Metadata Description: URL for the client's JSON Web Key Set 996 [JWK] document representing the client's public keys 997 o Change Controller: IESG 998 o Specification Document(s): [[ this document ]] 999 o Client Metadata Name: "jwks" 1000 o Client Metadata Description: The client's JSON Web Key Set [JWK] 1001 document representing the client's public keys 1002 o Change Controller: IESG 1003 o Specification Document(s): [[ this document ]] 1005 o Client Metadata Name: "software_id" 1006 o Client Metadata Description: Identifier for the software that 1007 comprises a client 1008 o Change Controller: IESG 1009 o Specification Document(s): [[ this document ]] 1011 o Client Metadata Name: "software_version" 1012 o Client Metadata Description: Version identifier for the software 1013 that comprises a client 1014 o Change Controller: IESG 1015 o Specification Document(s): [[ this document ]] 1017 o Client Metadata Name: "client_id" 1018 o Client Metadata Description: Client identifier 1019 o Change Controller: IESG 1020 o Specification Document(s): [[ this document ]] 1022 o Client Metadata Name: "client_secret" 1023 o Client Metadata Description: Client secret 1024 o Change Controller: IESG 1025 o Specification Document(s): [[ this document ]] 1027 o Client Metadata Name: "client_id_issued_at" 1028 o Client Metadata Description: Time at which the client identifier 1029 was issued 1030 o Change Controller: IESG 1031 o Specification Document(s): [[ this document ]] 1033 o Client Metadata Name: "client_secret_expires_at" 1034 o Client Metadata Description: Time at which the client secret will 1035 expire 1036 o Change Controller: IESG 1037 o Specification Document(s): [[ this document ]] 1039 5.2. OAuth Token Endpoint Authentication Methods Registry 1041 This specification establishes the OAuth Token Endpoint 1042 Authentication Methods registry. 1044 Additional values for use as "token_endpoint_auth_method" metadata 1045 values are registered with a Specification Required ([RFC5226]) after 1046 a two-week review period on the oauth-ext-review@ietf.org mailing 1047 list, on the advice of one or more Designated Experts. However, to 1048 allow for the allocation of values prior to publication, the 1049 Designated Expert(s) may approve registration once they are satisfied 1050 that such a specification will be published. 1052 Registration requests must be sent to the oauth-ext-review@ietf.org 1053 mailing list for review and comment, with an appropriate subject 1054 (e.g., "Request to register token_endpoint_auth_method value: 1055 example"). 1057 Within the review period, the Designated Expert(s) will either 1058 approve or deny the registration request, communicating this decision 1059 to the review list and IANA. Denials should include an explanation 1060 and, if applicable, suggestions as to how to make the request 1061 successful. 1063 IANA must only accept registry updates from the Designated Expert(s) 1064 and should direct all requests for registration to the review mailing 1065 list. 1067 5.2.1. Registration Template 1069 Token Endpoint Authorization Method Name: 1070 The name requested (e.g., "example"). This name is case 1071 sensitive. Names that match other registered names in a case 1072 insensitive manner SHOULD NOT be accepted. 1074 Change controller: 1075 For Standards Track RFCs, state "IETF". For others, give the name 1076 of the responsible party. Other details (e.g., postal address, 1077 email address, home page URI) may also be included. 1079 Specification document(s): 1080 Reference to the document(s) that specify the token endpoint 1081 authorization method, preferably including a URI that can be used 1082 to retrieve a copy of the document(s). An indication of the 1083 relevant sections may also be included but is not required. 1085 5.2.2. Initial Registry Contents 1087 The initial contents of the OAuth Token Endpoint Authentication 1088 Methods registry are: 1090 o Token Endpoint Authorization Method Name: "none" 1091 o Change controller: IESG 1092 o Specification document(s): [[ this document ]] 1094 o Token Endpoint Authorization Method Name: "client_secret_post" 1095 o Change controller: IESG 1096 o Specification document(s): [[ this document ]] 1098 o Token Endpoint Authorization Method Name: "client_secret_basic" 1099 o Change controller: IESG 1100 o Specification document(s): [[ this document ]] 1102 6. Security Considerations 1104 Since requests to the client registration endpoint result in the 1105 transmission of clear-text credentials (in the HTTP request and 1106 response), the authorization server MUST require the use of a 1107 transport-layer security mechanism when sending requests to the 1108 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1109 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 1110 transport-layer mechanisms meeting its security requirements. When 1111 using TLS, the client MUST perform a TLS/SSL server certificate 1112 check, per RFC 6125 [RFC6125]. 1114 For clients that use redirect-based grant types such as 1115 "authorization_code" and "implicit", authorization servers MUST 1116 require clients to register their "redirect_uri" values. This can 1117 help mitigate attacks where rogue actors inject and impersonate a 1118 validly registered client and intercept its authorization code or 1119 tokens through an invalid redirection URI or open redirector. 1121 Public clients MAY register with an authorization server using this 1122 protocol, if the authorization server's policy allows them. Public 1123 clients use a "none" value for the "token_endpoint_auth_method" 1124 metadata field and are generally used with the "implicit" grant type. 1125 Often these clients will be short-lived in-browser applications 1126 requesting access to a user's resources and access is tied to a 1127 user's active session at the authorization server. Since such 1128 clients often do not have long-term storage, it's possible that such 1129 clients would need to re-register every time the browser application 1130 is loaded. Additionally, such clients may not have ample opportunity 1131 to unregister themselves using the delete action before the browser 1132 closes. To avoid the resulting proliferation of dead client 1133 identifiers, an authorization server MAY decide to expire 1134 registrations for existing clients meeting certain criteria after a 1135 period of time has elapsed. 1137 Since different OAuth 2.0 grant types have different security and 1138 usage parameters, an authorization server MAY require separate 1139 registrations for a piece of software to support multiple grant 1140 types. For instance, an authorization server might require that all 1141 clients using the "authorization_code" grant type make use of a 1142 client secret for the "token_endpoint_auth_method", but any clients 1143 using the "implicit" grant type do not use any authentication at the 1144 token endpoint. In such a situation, a server MAY disallow clients 1145 from registering for both the "authorization_code" and "implicit" 1146 grant types simultaneously. Similarly, the "authorization_code" 1147 grant type is used to represent access on behalf of an end user, but 1148 the "client_credentials" grant type represents access on behalf of 1149 the client itself. For security reasons, an authorization server 1150 could require that different scopes be used for these different use 1151 cases, and as a consequence it MAY disallow these two grant types 1152 from being registered together by the same client. In all of these 1153 cases, the authorization server would respond with an 1154 "invalid_client_metadata" error response. 1156 Unless used as a claim in a software statement, the authorization 1157 server MUST treat all client metadata as self-asserted. For 1158 instance, a rogue client might use the name and logo of a legitimate 1159 client that it is trying to impersonate. Additionally, a rogue 1160 client might try to use the software identifier or software version 1161 of a legitimate client to attempt to associate itself on the 1162 authorization server with instances of the legitimate client. To 1163 counteract this, an authorization server needs to take steps to 1164 mitigate this risk by looking at the entire registration request and 1165 client configuration. For instance, an authorization server could 1166 issue a warning if the domain/site of the logo doesn't match the 1167 domain/site of redirection URIs. An authorization server could also 1168 refuse registration requests from a known software identifier that is 1169 requesting different redirection URIs or a different client homepage 1170 URI. An authorization server can also present warning messages to 1171 end users about dynamically registered clients in all cases, 1172 especially if such clients have been recently registered or have not 1173 been trusted by any users at the authorization server before. 1175 In a situation where the authorization server is supporting open 1176 client registration, it must be extremely careful with any URL 1177 provided by the client that will be displayed to the user (e.g. 1178 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1179 instance, a rogue client could specify a registration request with a 1180 reference to a drive-by download in the "policy_uri". The 1181 authorization server SHOULD check to see if the "logo_uri", 1182 "tos_uri", "client_uri", and "policy_uri" have the same host and 1183 scheme as the those defined in the array of "redirect_uris" and that 1184 all of these URIs resolve to valid web pages. 1186 Clients MAY use both the direct JSON object and the JWT-encoded 1187 software statement to present client metadata to the authorization 1188 server as part of the registration request. A software statement is 1189 cryptographically protected and represents claims made by the issuer 1190 of the statement, while the JSON object represents the self-asserted 1191 claims made by the client or developer directly. If the software 1192 statement is valid and trusted, the values of client metadata within 1193 the software statement MUST take precedence over those metadata 1194 values presented in the plain JSON object, which could have been 1195 modified en route. 1197 The software statement is an item that is self-asserted by the 1198 client, even though its contents have been digitally signed or MACed 1199 by the issuer of the software statement. As such, presentation of 1200 the software statement is not sufficient in most cases to fully 1201 identity a piece of client software. An initial access token, in 1202 contrast, does not necessarily contain information about a particular 1203 piece of client software but instead represents authorization to use 1204 the registration endpoint. An authorization server MUST consider the 1205 full registration request, including the software statement, initial 1206 access token, and JSON client metadata values, when deciding whether 1207 to honor a given registration request. 1209 If an authorization server receives a registration request for a 1210 client that uses the same "software_id" and "software_version" values 1211 as another client, the server should treat the new registration as 1212 being suspect. It is possible that the new client is trying to 1213 impersonate the existing client. 1215 Since a client identifier is a public value that can be used to 1216 impersonate a client at the authorization endpoint, an authorization 1217 server that decides to issue the same client identifier to multiple 1218 instances of a registered client MUST be very particular about the 1219 circumstances under which this occurs. For instance, the 1220 authorization server can limit a given client identifier to clients 1221 using the same redirect-based flow and the same redirection URIs. An 1222 authorization server SHOULD NOT issue the same client secret to 1223 multiple instances of a registered client, even if they are issued 1224 the same client identifier, or else the client secret could be 1225 leaked, allowing malicious imposters to impersonate a confidential 1226 client. 1228 7. References 1230 7.1. Normative References 1232 [IANA.Language] 1233 Internet Assigned Numbers Authority (IANA), "Language 1234 Subtag Registry", 2005. 1236 [JWK] Jones, M., "JSON Web Key (JWK)", 1237 draft-ietf-jose-json-web-key (work in progress), 1238 July 2014. 1240 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1241 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1242 in progress), July 2014. 1244 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1245 (JWT)", draft-ietf-oauth-json-web-token (work in 1246 progress), July 2014. 1248 [OAuth.JWT] 1249 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1250 (JWT) Profile for OAuth 2.0 Client Authentication and 1251 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 1252 in progress), April 2014. 1254 [OAuth.SAML2] 1255 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1256 Profile for OAuth 2.0 Client Authentication and 1257 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 1258 in progress), April 2014. 1260 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1261 Requirement Levels", BCP 14, RFC 2119, March 1997. 1263 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1264 RFC 2246, January 1999. 1266 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1267 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1268 May 2008. 1270 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1271 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1273 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1274 Languages", BCP 47, RFC 5646, September 2009. 1276 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1277 Verification of Domain-Based Application Service Identity 1278 within Internet Public Key Infrastructure Using X.509 1279 (PKIX) Certificates in the Context of Transport Layer 1280 Security (TLS)", RFC 6125, March 2011. 1282 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 1283 RFC 6749, October 2012. 1285 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1286 Framework: Bearer Token Usage", RFC 6750, October 2012. 1288 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1289 Interchange Format", RFC 7159, March 2014. 1291 7.2. Informative References 1293 [OAuth.Registration.Management] 1294 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 1295 Hunt, "OAuth 2.0 Dynamic Client Registration Management 1296 Protocol", draft-ietf-oauth-dyn-reg-management (work in 1297 progress), July 2014. 1299 Appendix A. Use Cases 1301 This appendix describes different ways that this specification can be 1302 utilized, including describing some of the choices that may need to 1303 be made. Some of the choices are independent and can be used in 1304 combination, whereas some of the choices are interrelated. 1306 A.1. Open versus Protected Dynamic Client Registration 1308 A.1.1. Open Dynamic Client Registration 1310 Authorization servers that support open registration allow 1311 registrations to be made with no initial access token. This allows 1312 all client software to register with the authorization server. 1314 A.1.2. Protected Dynamic Client Registration 1316 Authorization servers that support protected registration require 1317 that an initial access token be used when making registration 1318 requests. While the method by which a client or developer receives 1319 this initial access token and the method by which the authorization 1320 server validates this initial access token are out of scope for this 1321 specification, a common approach is for the developer to use a manual 1322 pre-registration portal at the authorization server that issues an 1323 initial access token to the developer. 1325 A.2. Registration Without or With Software Statements 1327 A.2.1. Registration Without a Software Statement 1329 When a software statement is not used in the registration request, 1330 the authorization server must be willing to use client metadata 1331 values without them being digitally signed or MACed (and thereby 1332 attested to) by any authority. (Note that this choice is independent 1333 of the Open versus Protected choice, and that an initial access token 1334 is another possible form of attestation.) 1336 A.2.2. Registration With a Software Statement 1338 A software statement can be used in a registration request to provide 1339 attestation by an authority for a set of client metadata values. 1340 This can be useful when the authorization server wants to restrict 1341 registration to client software attested to by a set of authorities 1342 or when it wants to know that multiple registration requests refer to 1343 the same piece of client software. 1345 A.3. Registration by the Client or Developer 1347 A.3.1. Registration by the Client 1349 In some use cases, client software will dynamically register itself 1350 with an authorization server to obtain a client identifier and other 1351 information needed to interact with the authorization server. In 1352 this case, no client identifier for the authorization server is 1353 packaged with the client software. 1355 A.3.2. Registration by the Developer 1357 In some cases, the developer (or development software being used by 1358 the developer) will pre-register the client software with the 1359 authorization server or a set of authorization servers. In this 1360 case, the client identifier value(s) for the authorization server(s) 1361 can be packaged with the client software. 1363 A.4. Client ID per Client Instance or per Client Software 1365 A.4.1. Client ID per Client Software Instance 1367 In some cases, each deployed instance of a piece of client software 1368 will dynamically register and obtain distinct client identifier 1369 values. This can be advantageous, for instance, if the code flow is 1370 being used, as it also enables each client instance to have its own 1371 client secret. This can be useful for native clients, which cannot 1372 maintain the secrecy of a client secret value packaged with the 1373 software, but which may be able to maintain the secrecy of a per- 1374 instance client secret. 1376 A.4.2. Client ID Shared Among All Instances of Client Software 1378 In some cases, each deployed instance of a piece of client software 1379 will share a common client identifier value. For instance, this is 1380 often the case for in-browser clients using the implicit flow, when 1381 no client secret is involved. Particular authorization servers might 1382 choose, for instance, to maintain a mapping between software 1383 statement values and client identifier values, and return the same 1384 client identifier value for all registration requests for a 1385 particular piece of software. The circumstances under which an 1386 authorization server would do so, and the specific software statement 1387 characteristics required in this case, are beyond the scope of this 1388 specification. 1390 A.5. Stateful or Stateless Registration 1392 A.5.1. Stateful Client Registration 1394 In some cases, authorization servers will maintain state about 1395 registered clients, typically indexing this state using the client 1396 identifier value. This state would typically include the client 1397 metadata values associated with the client registration, and possibly 1398 other state specific to the authorization server's implementation. 1399 When stateful registration is used, operations to support retrieving 1400 and/or updating this state may be supported. One possible set of 1401 operations upon stateful registrations is described in the 1402 [OAuth.Registration.Management] specification. 1404 A.5.2. Stateless Client Registration 1406 In some cases, authorization servers will be implemented in a manner 1407 the enables them to not maintain any local state about registered 1408 clients. One means of doing this is to encode all the registration 1409 state in the returned client identifier value, and possibly 1410 encrypting the state to the authorization server to maintain the 1411 confidentiality and integrity of the state. 1413 Appendix B. Acknowledgments 1415 The authors thank the OAuth Working Group, the User-Managed Access 1416 Working Group, and the OpenID Connect Working Group participants for 1417 their input to this document. In particular, the following 1418 individuals have been instrumental in their review and contribution 1419 to various versions of this document: Amanda Anganes, Derek Atkins, 1420 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1421 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1422 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1423 Sakimura, Christian Scholz, and Hannes Tschofenig. 1425 Appendix C. Document History 1427 [[ to be removed by the RFC editor before publication as an RFC ]] 1429 -18 1431 o Corrected an example HTTP response status code to be 201 Created. 1433 o Said more about who issues and uses initial access tokens and 1434 software statements. 1436 o Stated that the use of an initial access token is required when 1437 the authorization server limits the parties that can register a 1438 client. 1440 o Stated that the implementation and use of all client metadata 1441 fields is OPTIONAL, other than "redirect_uris", which MUST be used 1442 for redirect-based flows and implemented to fulfill the 1443 requirement in Section 2 of OAuth 2.0. 1445 o Added the "application_type" metadata value, which had somehow 1446 been omitted. 1448 o Added missing default metadata values, which had somehow been 1449 omitted. 1451 o Clarified that the "software_id" is ultimately asserted by the 1452 client developer. 1454 o Clarified that the "error" member is required in error responses, 1455 "error_description" member is optional, and other members may be 1456 present. 1458 o Added security consideration about registrations with duplicate 1459 "software_id" and "software_version" values. 1461 -17 1463 o Merged draft-ietf-oauth-dyn-reg-metadata back into this document. 1465 o Removed "Core" from the document title. 1467 o Explicitly state that all metadata members are optional. 1469 o Clarified language around software statements for use in 1470 registration context. 1472 o Clarified that software statements need to be digitally signed or 1473 MACed. 1475 o Added a "jwks" metadata parameter to parallel the "jwks_uri" 1476 parameter. 1478 o Removed normative language from terminology. 1480 o Expanded abstract and introduction. 1482 o Addressed review comments from several working group members. 1484 -16 1486 o Replaced references to draft-jones-oauth-dyn-reg-metadata and 1487 draft-jones-oauth-dyn-reg-management with 1488 draft-ietf-oauth-dyn-reg-metadata and 1489 draft-ietf-oauth-dyn-reg-management. 1491 o Addressed review comments by Phil Hunt and Tony Nadalin. 1493 -15 1495 o Partitioned the Dynamic Client Registration specification into 1496 core, metadata, and management specifications. This built on work 1497 first published as draft-richer-oauth-dyn-reg-core-00 and 1498 draft-richer-oauth-dyn-reg-management-00. 1500 o Added the ability to use Software Statements. This built on work 1501 first published as draft-hunt-oauth-software-statement-00 and 1502 draft-hunt-oauth-client-association-00. 1504 o Created the IANA OAuth Registration Client Metadata registry for 1505 registering Client Metadata values. 1507 o Defined Client Instance term and stated that multiple instances 1508 can use the same client identifier value under certain 1509 circumstances. 1511 o Rewrote the introduction. 1513 o Rewrote the Use Cases appendix. 1515 -14 1517 o Added software_id and software_version metadata fields 1519 o Added direct references to RFC6750 errors in read/update/delete 1520 methods 1522 -13 1524 o Fixed broken example text in registration request and in delete 1525 request 1527 o Added security discussion of separating clients of different grant 1528 types 1530 o Fixed error reference to point to RFC6750 instead of RFC6749 1532 o Clarified that servers must respond to all requests to 1533 configuration endpoint, even if it's just an error code 1535 o Lowercased all Terms to conform to style used in RFC6750 1537 -12 1539 o Improved definition of Initial Access Token 1541 o Changed developer registration scenario to have the Initial Access 1542 Token gotten through a normal OAuth 2.0 flow 1544 o Moved non-normative client lifecycle examples to appendix 1546 o Marked differentiating between auth servers as out of scope 1548 o Added protocol flow diagram 1550 o Added credential rotation discussion 1552 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1553 Resource 1555 o Cleaned up several pieces of text 1557 -11 1558 o Added localized text to registration request and response 1559 examples. 1561 o Removed "client_secret_jwt" and "private_key_jwt". 1563 o Clarified "tos_uri" and "policy_uri" definitions. 1565 o Added the OAuth Token Endpoint Authentication Methods registry for 1566 registering "token_endpoint_auth_method" metadata values. 1568 o Removed uses of non-ASCII characters, per RFC formatting rules. 1570 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1571 to "client_id_issued_at" for greater clarity. 1573 o Added explanatory text for different credentials (Initial Access 1574 Token, Registration Access Token, Client Credentials) and what 1575 they're used for. 1577 o Added Client Lifecycle discussion and examples. 1579 o Defined Initial Access Token in Terminology section. 1581 -10 1583 o Added language to point out that scope values are service-specific 1585 o Clarified normative language around client metadata 1587 o Added extensibility to token_endpoint_auth_method using absolute 1588 URIs 1590 o Added security consideration about registering redirect URIs 1592 o Changed erroneous 403 responses to 401's with notes about token 1593 handling 1595 o Added example for initial registration credential 1597 -09 1599 o Added method of internationalization for Client Metadata values 1601 o Fixed SAML reference 1603 -08 1604 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1605 x509_encryption_uri into a single jwks_uri parameter 1607 o Renamed grant_type to grant_types since it's a plural value 1609 o Formalized name of "OAuth 2.0" throughout document 1611 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1612 grant types 1614 o Added response_types parameter and explanatory text on its use 1615 with and relationship to grant_types 1617 -07 1619 o Changed registration_access_url to registration_client_uri 1621 o Fixed missing text in 5.1 1623 o Added Pragma: no-cache to examples 1625 o Changed "no such client" error to 403 1627 o Renamed Client Registration Access Endpoint to Client 1628 Configuration Endpoint 1630 o Changed all the parameter names containing "_url" to instead use 1631 "_uri" 1633 o Updated example text for forming Client Configuration Endpoint URL 1635 -06 1637 o Removed secret_rotation as a client-initiated action, including 1638 removing client secret rotation endpoint and parameters. 1640 o Changed _links structure to single value registration_access_url. 1642 o Collapsed create/update/read responses into client info response. 1644 o Changed return code of create action to 201. 1646 o Added section to describe suggested generation and composition of 1647 Client Registration Access URL. 1649 o Added clarifying text to PUT and POST requests to specify JSON in 1650 the body. 1652 o Added Editor's Note to DELETE operation about its inclusion. 1654 o Added Editor's Note to registration_access_url about alternate 1655 syntax proposals. 1657 -05 1659 o changed redirect_uri and contact to lists instead of space 1660 delimited strings 1662 o removed operation parameter 1664 o added _links structure 1666 o made client update management more RESTful 1668 o split endpoint into three parts 1670 o changed input to JSON from form-encoded 1672 o added READ and DELETE operations 1674 o removed Requirements section 1676 o changed token_endpoint_auth_type back to 1677 token_endpoint_auth_method to match OIDC who changed to match us 1679 -04 1681 o removed default_acr, too undefined in the general OAuth2 case 1683 o removed default_max_auth_age, since there's no mechanism for 1684 supplying a non-default max_auth_age in OAuth2 1686 o clarified signing and encryption URLs 1688 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1689 match OIDC 1691 -03 1693 o added scope and grant_type claims 1695 o fixed various typos and changed wording for better clarity 1697 o endpoint now returns the full set of client information 1698 o operations on client_update allow for three actions on metadata: 1699 leave existing value, clear existing value, replace existing value 1700 with new value 1702 -02 1704 o Reorganized contributors and references 1706 o Moved OAuth references to RFC 1708 o Reorganized model/protocol sections for clarity 1710 o Changed terminology to "client register" instead of "client 1711 associate" 1713 o Specified that client_id must match across all subsequent requests 1715 o Fixed RFC2XML formatting, especially on lists 1717 -01 1719 o Merged UMA and OpenID Connect registrations into a single document 1721 o Changed to form-parameter inputs to endpoint 1723 o Removed pull-based registration 1725 -00 1727 o Imported original UMA draft specification 1729 Authors' Addresses 1731 Justin Richer 1732 The MITRE Corporation 1734 Email: jricher@mitre.org 1736 Michael B. Jones 1737 Microsoft 1739 Email: mbj@microsoft.com 1740 URI: http://self-issued.info/ 1741 John Bradley 1742 Ping Identity 1744 Email: ve7jtb@ve7jtb.com 1746 Maciej Machulak 1747 Newcastle University 1749 Email: m.p.machulak@ncl.ac.uk 1750 URI: http://ncl.ac.uk/ 1752 Phil Hunt 1753 Oracle Corporation 1755 Email: phil.hunt@yahoo.com