idnits 2.17.1 draft-ietf-oauth-dyn-reg-20.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 (August 26, 2014) is 3528 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) == Outdated reference: A later version (-14) exists of draft-hardjono-oauth-umacore-10 Summary: 5 errors (**), 0 flaws (~~), 4 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: February 27, 2015 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 August 26, 2014 14 OAuth 2.0 Dynamic Client Registration Protocol 15 draft-ietf-oauth-dyn-reg-20 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. 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 February 27, 2015. 47 Copyright Notice 49 Copyright (c) 2014 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 66 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 67 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 68 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 6 69 2.1. Relationship between Grant Types and Response Types . . . 10 70 2.2. Human Readable Client Metadata . . . . . . . . . . . . . 10 71 2.3. Software Statement . . . . . . . . . . . . . . . . . . . 12 72 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 12 73 3.1. Client Registration Request . . . . . . . . . . . . . . . 13 74 3.2. Client Registration Response . . . . . . . . . . . . . . 16 75 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 16 76 4.1. Client Information Response . . . . . . . . . . . . . . . 16 77 4.2. Client Registration Error Response . . . . . . . . . . . 17 78 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 79 5.1. OAuth Dynamic Registration Client Metadata Registry . . . 19 80 5.1.1. Registration Template . . . . . . . . . . . . . . . . 20 81 5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 20 82 5.2. OAuth Token Endpoint Authentication Methods Registry . . 22 83 5.2.1. Registration Template . . . . . . . . . . . . . . . . 23 84 5.2.2. Initial Registry Contents . . . . . . . . . . . . . . 23 85 6. Security Considerations . . . . . . . . . . . . . . . . . . . 24 86 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 87 7.1. Normative References . . . . . . . . . . . . . . . . . . 27 88 7.2. Informative References . . . . . . . . . . . . . . . . . 28 89 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 28 90 A.1. Open versus Protected Dynamic Client Registration . . . . 28 91 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 28 92 A.1.2. Protected Dynamic Client Registration . . . . . . . . 29 93 A.2. Registration Without or With Software Statements . . . . 29 94 A.2.1. Registration Without a Software Statement . . . . . . 29 95 A.2.2. Registration With a Software Statement . . . . . . . 29 96 A.3. Registration by the Client or Developer . . . . . . . . . 29 97 A.3.1. Registration by the Client . . . . . . . . . . . . . 29 98 A.3.2. Registration by the Developer . . . . . . . . . . . . 29 99 A.4. Client ID per Client Instance or per Client Software . . 30 100 A.4.1. Client ID per Client Software Instance . . . . . . . 30 101 A.4.2. Client ID Shared Among All Instances of Client 102 Software . . . . . . . . . . . . . . . . . . . . . . 30 103 A.5. Stateful or Stateless Registration . . . . . . . . . . . 30 104 A.5.1. Stateful Client Registration . . . . . . . . . . . . 30 105 A.5.2. Stateless Client Registration . . . . . . . . . . . . 30 106 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 31 107 Appendix C. Document History . . . . . . . . . . . . . . . . . . 31 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 36 110 1. Introduction 112 In order for an OAuth 2.0 client to utilize an OAuth 2.0 113 authorization server, the client needs specific information to 114 interact with the server, including an OAuth 2.0 client identifier to 115 use at that server. This specification describes how an OAuth 2.0 116 client can be dynamically registered with an authorization server to 117 obtain this information. 119 As part of the registration process, this specification also defines 120 a mechanism for the client to present the authorization server with a 121 set of metadata, such as a set of valid redirection URIs. This 122 metadata can either be communicated in a self-asserted fashion or as 123 a set of metadata called a software statement, which is digitally 124 signed or MACed; in the case of a software statement, the issuer is 125 vouching for the validity of the data about the client. 127 Traditionally, registration of a client with an authorization server 128 is performed manually. The mechanisms defined in this specification 129 can be used either for a client to dynamically register itself with 130 authorization servers or for a client developer to programmatically 131 register the client with authorization servers. Multiple 132 applications using OAuth 2.0 have previously developed mechanisms for 133 accomplishing such registrations. This specficiation generalizes the 134 registration mechanisms defined by the OpenID Connect Dynamic Client 135 Registration 1.0 [OpenID.Registration] specification and used by the 136 User Managed Access (UMA) Profile of OAuth 2.0 137 [I-D.hardjono-oauth-umacore] specification in a way that is 138 compatible with both, while being applicable to a wider set of OAuth 139 2.0 use cases. 141 1.1. Notational Conventions 143 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 144 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 145 document are to be interpreted as described in [RFC2119]. 147 Unless otherwise noted, all the protocol parameter names and values 148 are case sensitive. 150 1.2. Terminology 152 This specification uses the terms "access token", "authorization 153 code", "authorization endpoint", "authorization grant", 154 "authorization server", "client", "client identifier", "client 155 secret", "grant type", "protected resource", "redirection URI", 156 "refresh token", "resource owner", "resource server", "response 157 type", and "token endpoint" defined by OAuth 2.0 [RFC6749] and uses 158 the term "Claim" defined by JSON Web Token (JWT) [JWT]. 160 This specification defines the following terms: 162 Client Developer 163 The person or organization that builds a client software package 164 and prepares it for distribution. 165 Client Instance 166 A deployed instance of a piece of client software. 167 Client Software 168 Software implementing an OAuth 2.0 client. 169 Client Registration Endpoint 170 OAuth 2.0 endpoint through which a client can be registered at an 171 authorization server. The means by which the URL for this 172 endpoint is obtained are out of scope for this specification. 173 Initial Access Token 174 OAuth 2.0 access token optionally issued by an authorization 175 server to a developer or client and used to authorize calls to the 176 client registration endpoint. The type and format of this token 177 are likely service-specific and are out of scope for this 178 specification. The means by which the authorization server issues 179 this token as well as the means by which the registration endpoint 180 validates this token are out of scope for this specification. Use 181 of an initial access token is required when the authorization 182 server limits the parties that can register a client. 183 Deployment Organization 184 An administrative security domain under which a software API is 185 deployed and protected by an OAuth 2.0 framework. In simple cloud 186 deployments, the software API publisher and the deployment 187 organization may be the same. In other scenarios, a software 188 publisher may be working with many different deployment 189 organizations. 190 Software API Deployment 191 A deployed instance of a software API that is protected by OAuth 192 2.0 in a particular deployment organization domain. For any 193 particular software API, there may be one or more deployments. A 194 software API deployment typically has an associated OAuth 2.0 195 authorization server as well as a client registration endpoint. 196 The means by which endpoints are obtained are out of scope for 197 this specification. 198 Software API Publisher 199 The organization that defines a particular web accessible API that 200 may deployed in one or more deployment environments. A publisher 201 may be any commercial, public, private, or open source 202 organization that is responsible for publishing and distributing 203 software that may be protected via OAuth 2.0. In some cases a 204 software API publisher and a client developer may be the same 205 organization. 206 Software Statement 207 Digitally signed or MACed JSON Web Token (JWT) [JWT] that asserts 208 metadata values about the client software. In some cases, a 209 software statement will be issued directly by the organization or 210 developer that creates the client software. In other cases, a 211 software statement will be issued by a third party organization 212 for use by the organization or developer that creates the client 213 software. In both cases, the trust relationship the authorization 214 server has with the issuer of the software statement is intended 215 to be used as an input to the evaluation of whether the 216 registration request is accepted. A software statement can be 217 presented to an authorization server as part of a client 218 registration request. 220 1.3. Protocol Flow 222 +--------(A)- Initial Access Token (OPTIONAL) 223 | 224 | +----(B)- Software Statement (OPTIONAL) 225 | | 226 v v 227 +-----------+ +---------------+ 228 | |--(C)- Client Registration Request -->| Client | 229 | Client or | | Registration | 230 | Developer |<-(D)- Client Information Response ---| Endpoint | 231 | | +---------------+ 232 +-----------+ 234 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. 245 (B) Optionally, the client or developer is issued a software 246 statement for use with the client registration endpoint. The 247 method by which the software statement is issued to the client or 248 developer is out of scope for this specification. 249 (C) The client or developer calls the client registration endpoint 250 with the client's desired registration metadata, optionally 251 including the initial access token from (A) if one is required by 252 the authorization server. 253 (D) The authorization server registers the client and returns the 254 client's registered metadata, a client identifier that is unique 255 at the server, a set of client credentials such as a client secret 256 if applicable for this client, and possibly other values. 258 2. Client Metadata 260 Clients have a set of metadata values associated with their client 261 identifier at an authorization server, such as the list of valid 262 redirection URIs or a display name. 264 The client metadata values are used in two ways: 266 o as input values to registration requests, and 267 o as output values in registration responses. 269 The following client metadata fields are defined by this 270 specification. The implementation and use of all client metadata 271 fields is OPTIONAL, unless stated otherwise. 273 redirect_uris 274 Array of redirection URI values for use in redirect-based flows 275 such as the authorization code and implicit flows. As required by 276 Section 2 of OAuth 2.0 [RFC6749], clients using flows with 277 redirection MUST register their redirection URI values. 278 Authorization servers that support dynamic registration for 279 redirect-based flows MUST implement support for this metadata 280 value. 281 token_endpoint_auth_method 282 The requested authentication method for the token endpoint. 283 Values defined by this specification are: 285 * "none": The client is a public client as defined in OAuth 2.0 286 and does not have a client secret. 287 * "client_secret_post": The client uses the HTTP POST parameters 288 defined in OAuth 2.0 section 2.3.1. 289 * "client_secret_basic": the client uses HTTP Basic defined in 290 OAuth 2.0 section 2.3.1 292 Additional values can be defined via the IANA OAuth Token Endpoint 293 Authentication Methods Registry established in Section 5.2. 294 Absolute URIs can also be used as values for this parameter 295 without being registered. If unspecified or omitted, the default 296 is "client_secret_basic", denoting HTTP Basic Authentication 297 Scheme as specified in Section 2.3.1 of OAuth 2.0. 298 grant_types 299 Array of OAuth 2.0 grant types that the client may use. These 300 grant types are defined as follows: 302 * "authorization_code": The Authorization Code Grant described in 303 OAuth 2.0 Section 4.1 304 * "implicit": The Implicit Grant described in OAuth 2.0 305 Section 4.2 306 * "password": The Resource Owner Password Credentials Grant 307 described in OAuth 2.0 Section 4.3 308 * "client_credentials": The Client Credentials Grant described in 309 OAuth 2.0 Section 4.4 310 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 311 Section 6. 312 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 313 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 314 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 315 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 316 [OAuth.SAML2]. 318 If the token endpoint is used in the grant type, the value of this 319 parameter MUST be the same as the value of the "grant_type" 320 parameter passed to the token endpoint defined in the grant type 321 definition. Authorization Servers MAY allow for other values as 322 defined in the grant type extension process described in OAuth 2.0 323 Section 2.5. If omitted, the default behavior is that the client 324 will use only the "authorization_code" Grant Type. 325 response_types 326 Array of the OAuth 2.0 response types that the client may use. 327 These response types are defined as follows: 329 * "code": The Authorization Code response described in OAuth 2.0 330 Section 4.1. 331 * "token": The Implicit response described in OAuth 2.0 332 Section 4.2. 334 If the authorization endpoint is used by the grant type, the value 335 of this parameter MUST be the same as the value of the 336 "response_type" parameter passed to the authorization endpoint 337 defined in the grant type definition. Authorization servers MAY 338 allow for other values as defined in the grant type extension 339 process is described in OAuth 2.0 Section 2.5. If omitted, the 340 default is that the client will use only the "code" response type. 341 client_name 342 Human-readable name of the client to be presented to the user 343 during authorization. If omitted, the authorization server MAY 344 display the raw "client_id" value to the user instead. It is 345 RECOMMENDED that clients always send this field. The value of 346 this field MAY be internationalized, as described in Section 2.2. 347 client_uri 348 URL of a web page providing information about the client. If 349 present, the server SHOULD display this URL to the end user in a 350 clickable fashion. It is RECOMMENDED that clients always send 351 this field. The value of this field MUST point to a valid web 352 page. The value of this field MAY be internationalized, as 353 described in Section 2.2. 354 logo_uri 355 URL that references a logo for the client. If present, the server 356 SHOULD display this image to the end user during approval. The 357 value of this field MUST point to a valid image file. The value 358 of this field MAY be internationalized, as described in 359 Section 2.2. 360 scope 361 Space separated list of scope values (as described in Section 3.3 362 of OAuth 2.0 [RFC6749]) that the client can use when requesting 363 access tokens. The semantics of values in this list is service 364 specific. If omitted, an authorization server MAY register a 365 client with a default set of scopes. 366 contacts 367 Array of strings representing ways to contact people responsible 368 for this client, typically email addresses. The authorization 369 server MAY make these addresses available to end users for support 370 requests for the client. 371 tos_uri 372 URL that points to a human-readable terms of service document for 373 the client that describes a contractual relationship between the 374 end-user and the client that the end-user accepts when authorizing 375 the client. The authorization server SHOULD display this URL to 376 the end-user if it is provided. The value of this field MUST 377 point to a valid web page. The value of this field MAY be 378 internationalized, as described in Section 2.2. 379 policy_uri 380 URL that points to a human-readable privacy policy document that 381 describes how the deployment organization collects, uses, retains, 382 and discloses personal data. The authorization server SHOULD 383 display this URL to the end-user if it is provided. The value of 384 this field MUST point to a valid web page. The value of this 385 field MAY be internationalized, as described in Section 2.2. 386 jwks_uri 387 URL referencing the client's JSON Web Key Set [JWK] document, 388 which contains the client's public keys. The value of this field 389 MUST point to a valid JWK Set document. These keys can be used by 390 higher level protocols that use signing or encryption. For 391 instance, these keys might be used by some applications for 392 validating signed requests made to the token endpoint when using 393 JWTs for client authentication [OAuth.JWT]. Use of this parameter 394 is preferred over the "jwks" parameter, as it allows for easier 395 key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both 396 be present in the same request or response. 397 jwks 398 Client's JSON Web Key Set [JWK] document value, which contains the 399 client's public keys. The value of this field MUST be a JSON 400 object containing a valid JWK Set. These keys can be used by 401 higher level protocols that use signing or encryption. This 402 parameter is intended to be used by clients that cannot use the 403 "jwks_uri" parameter, such as native clients that cannot host 404 public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both 405 be present in the same request or response. 406 software_id 407 Identifier for the software that comprises a client. Unlike 408 "client_id", which is issued by the authorization server and may 409 vary between instances, the "software_id" is asserted by the 410 client software on behalf of the software developer and is 411 intended to be shared among all instances of the client software. 412 The identifier SHOULD NOT change when software version changes or 413 when a new installation occurs. 414 software_version 415 Version identifier for the software that comprises a client. The 416 value of this field is a string that is intended to be compared 417 using string equality matching. The value of the 418 "software_version" SHOULD change on any update to the client 419 software. 421 Extensions and profiles of this specification MAY expand this list. 422 The authorization server MUST ignore any client metadata values sent 423 by the client that it does not understand. 425 Client metadata values can either be communicated directly in the 426 body of a registration request, as described in Section 3.1, or 427 included as claims in a software statement, as described in 428 Section 2.3, or a mixture of both. If the same client metadata name 429 is present in both locations and the software statement is trusted by 430 the authorization server, the value of a claim in the software 431 statement MUST take precedence. 433 2.1. Relationship between Grant Types and Response Types 435 The "grant_types" and "response_types" values described above are 436 partially orthogonal, as they refer to arguments passed to different 437 endpoints in the OAuth protocol. However, they are related in that 438 the "grant_types" available to a client influence the 439 "response_types" that the client is allowed to use, and vice versa. 440 For instance, a "grant_types" value that includes 441 "authorization_code" implies a "response_types" value that includes 442 "code", as both values are defined as part of the OAuth 2.0 443 authorization code grant. As such, a server supporting these fields 444 SHOULD take steps to ensure that a client cannot register itself into 445 an inconsistent state, for example by returning an 446 "invalid_client_metadata" error response to an inconsistent 447 registration request. 449 The correlation between the two fields is listed in the table below. 451 +-----------------------------------------------+-------------------+ 452 | grant_types value includes: | response_types | 453 | | value includes: | 454 +-----------------------------------------------+-------------------+ 455 | authorization_code | code | 456 | implicit | token | 457 | password | (none) | 458 | client_credentials | (none) | 459 | refresh_token | (none) | 460 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 461 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 462 +-----------------------------------------------+-------------------+ 464 Extensions and profiles of this document that introduce new values to 465 either the "grant_types" or "response_types" parameter MUST document 466 all correspondences between these two parameter types. 468 2.2. Human Readable Client Metadata 470 Human-readable client metadata values and client metadata values that 471 reference human-readable values MAY be represented in multiple 472 languages and scripts. For example, the values of fields such as 473 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 474 might have multiple locale-specific values in some client 475 registrations to facilitate use in different locations. 477 To specify the languages and scripts, BCP47 [RFC5646] language tags 478 are added to client metadata member names, delimited by a # 479 character. Since JSON [RFC7159] member names are case sensitive, it 480 is RECOMMENDED that language tag values used in Claim Names be 481 spelled using the character case with which they are registered in 482 the IANA Language Subtag Registry [IANA.Language]. In particular, 483 normally language names are spelled with lowercase characters, region 484 names are spelled with uppercase characters, and languages are 485 spelled with mixed case characters. However, since BCP47 language 486 tag values are case insensitive, implementations SHOULD interpret the 487 language tag values supplied in a case insensitive manner. Per the 488 recommendations in BCP47, language tag values used in metadata member 489 names should only be as specific as necessary. For instance, using 490 "fr" might be sufficient in many contexts, rather than "fr-CA" or 491 "fr-FR". 493 For example, a client could represent its name in English as 494 ""client_name#en": "My Client"" and its name in Japanese as 495 ""client_name#ja-Jpan-JP": 496 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 497 registration request. The authorization server MAY display any or 498 all of these names to the resource owner during the authorization 499 step, choosing which name to display based on system configuration, 500 user preferences or other factors. 502 If any human-readable field is sent without a language tag, parties 503 using it MUST NOT make any assumptions about the language, character 504 set, or script of the string value, and the string value MUST be used 505 as-is wherever it is presented in a user interface. To facilitate 506 interoperability, it is RECOMMENDED that clients and servers use a 507 human-readable field without any language tags in addition to any 508 language-specific fields, and it is RECOMMENDED that any human- 509 readable fields sent without language tags contain values suitable 510 for display on a wide variety of systems. 512 Implementer's Note: Many JSON libraries make it possible to reference 513 members of a JSON object as members of an object construct in the 514 native programming environment of the library. However, while the 515 "#" character is a valid character inside of a JSON object's member 516 names, it is not a valid character for use in an object member name 517 in many programming environments. Therefore, implementations will 518 need to use alternative access forms for these claims. For instance, 519 in JavaScript, if one parses the JSON as follows, "var j = 520 JSON.parse(json);", then as a workaround the member "client_name#en- 521 us" can be accessed using the JavaScript syntax "j["client_name#en- 522 us"]". 524 2.3. Software Statement 526 A software statement is a JSON Web Token (JWT) [JWT] that asserts 527 metadata values about the client software as a bundle. A set of 528 claims that can be used in a software statement are defined in 529 Section 2. When presented to the authorization server as part of a 530 client registration request, the software statement MUST be digitally 531 signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer) 532 claim denoting the party attesting to the claims in the software 533 statement. It is RECOMMENDED that software statements be digitally 534 signed using the "RS256" signature algorithm, although particular 535 applications MAY specify the use of different algorithms. 537 The means by which a client or developer obtains a software statement 538 are outside the scope of this specification. Some common methods 539 could include a client developer generating a client-specific JWT 540 registering with a software API publisher to obtain a software 541 statement for a class of clients. The software statement is 542 typically distributed with all instances of a client application. 544 The criteria by which authorization servers determine whether to 545 trust and utilize the information in a software statement are beyond 546 the scope of this specification. 548 In some cases, authorization servers MAY choose to accept a software 549 statement value directly as a client identifier in an authorization 550 request, without a prior dynamic client registration having been 551 performed. The circumstances under which an authorization server 552 would do so, and the specific software statement characteristics 553 required in this case, are beyond the scope of this specification. 555 3. Client Registration Endpoint 557 The client registration endpoint is an OAuth 2.0 endpoint defined in 558 this document that is designed to allow a client to be registered 559 with the authorization server. The client registration endpoint MUST 560 accept HTTP POST messages with request parameters encoded in the 561 entity body using the "application/json" format. The client 562 registration endpoint MUST be protected by a transport-layer security 563 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] 564 and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer 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]. 569 The client registration endpoint MAY be an OAuth 2.0 protected 570 resource and accept an initial access token in the form of an OAuth 571 2.0 [RFC6749] access token to limit registration to only previously 572 authorized parties. The method by which the initial access token is 573 obtained by the client or developer is generally out-of-band and is 574 out of scope for this specification. The method by which the initial 575 access token is verified and validated by the client registration 576 endpoint is out of scope for this specification. 578 To support open registration and facilitate wider interoperability, 579 the client registration endpoint SHOULD allow registration requests 580 with no authorization (which is to say, with no initial access token 581 in the request). These requests MAY be rate-limited or otherwise 582 limited to prevent a denial-of-service attack on the client 583 registration endpoint. 585 3.1. Client Registration Request 587 This operation registers a client with the authorization server. The 588 authorization server assigns this client a unique client identifier, 589 optionally assigns a client secret, and associates the metadata 590 provided in the request with the issued client identifier. The 591 request includes any client metadata parameters being specified for 592 the client during the registration. The authorization server MAY 593 provision default values for any items omitted in the client 594 metadata. 596 Client metadata values may also be provided in a software statement, 597 as described in Section 2.3. Software statements are included in the 598 requesting JSON object using this member: 600 software_statement 601 A software statement containing client metadata values about the 602 client software as claims. 604 To register, the client or developer sends an HTTP POST to the client 605 registration endpoint with a content type of "application/json". The 606 HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON 607 object and all requested client metadata values as top-level members 608 of that JSON object. 610 For example, if the server supports open registration (with no 611 initial access token), the client could send the following 612 registration request to the client registration endpoint: 614 The following is a non-normative example request not using an initial 615 access token (with line wraps within values for display purposes 616 only): 618 POST /register HTTP/1.1 619 Content-Type: application/json 620 Accept: application/json 621 Host: server.example.com 623 { 624 "redirect_uris":[ 625 "https://client.example.org/callback", 626 "https://client.example.org/callback2"], 627 "client_name":"My Example Client", 628 "client_name#ja-Jpan-JP": 629 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 630 "token_endpoint_auth_method":"client_secret_basic", 631 "logo_uri":"https://client.example.org/logo.png", 632 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 633 "example_extension_parameter": "example_value" 634 } 636 Alternatively, if the server supports authorized registration, the 637 developer or the client will be provisioned with an initial access 638 token. (The method by which the initial access token is obtained is 639 out of scope for this specification.) The developer or client sends 640 the following authorized registration request to the client 641 registration endpoint. Note that the initial access token sent in 642 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 643 2.0 token type could be used by an authorization server. 645 The following is a non-normative example request using an initial 646 access token (with line wraps within values for display purposes 647 only): 649 POST /register HTTP/1.1 650 Content-Type: application/json 651 Accept: application/json 652 Authorization: Bearer ey23f2.adfj230.af32-developer321 653 Host: server.example.com 655 { 656 "redirect_uris":["https://client.example.org/callback", 657 "https://client.example.org/callback2"], 658 "client_name":"My Example Client", 659 "client_name#ja-Jpan-JP": 660 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 661 "token_endpoint_auth_method":"client_secret_basic", 662 "policy_uri":"https://client.example.org/policy.html", 663 "jwks":{"keys":[{...omitted for brevity...}]}, 664 "example_extension_parameter": "example_value" 665 } 667 In the following example, some registration parameters are conveyed 668 as claims in a software statement, while some values specific to the 669 client instance are conveyed as regular parameters (with line wraps 670 within values for display purposes only): 672 POST /register HTTP/1.1 673 Content-Type: application/json 674 Accept: application/json 675 Host: server.example.com 677 { 678 "redirect_uris":[ 679 "https://client.example.org/callback", 680 "https://client.example.org/callback2" 681 ], 682 "software_statement":"eyJhbGciOiJFUzI1NiJ9. 683 eyJpc3Mi[...omitted for brevity...]. 684 J9l-ZhwP[...omitted for brevity...]", 685 "scope":"read write", 686 "example_extension_parameter":"example_value" 687 } 689 3.2. Client Registration Response 691 Upon successful registration, the authorization server returns a 692 client identifier for the client. The server responds with an HTTP 693 201 Created code and a body of type "application/json" with content 694 as described in Section 4.1. 696 Upon an unsuccessful registration, the authorization server responds 697 with an error, as described in Section 4.2. 699 4. Responses 701 The following responses are sent in response to registration 702 requests. 704 4.1. Client Information Response 706 The response contains the client identifier as well as the client 707 secret, if the client is a confidential client. The response MAY 708 contain additional fields as specified by extensions to this 709 specification. 711 client_id 712 REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be 713 currently valid for any other registered client, though an 714 authorization server MAY issue the same client identifier to 715 multiple instances of a registered client at its discretion. 716 client_secret 717 OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be 718 unique for each "client_id" and SHOULD be unique for multiple 719 instances of a client using the same "client_id". This value is 720 used by confidential clients to authenticate to the token endpoint 721 as described in OAuth 2.0 [RFC6749] Section 2.3.1. 722 client_id_issued_at 723 OPTIONAL. Time at which the client identifier was issued. The 724 time is represented as the number of seconds from 725 1970-01-01T0:0:0Z as measured in UTC until the date/time. 726 client_secret_expires_at 727 REQUIRED if "client_secret" is issued. Time at which the client 728 secret will expire or 0 if it will not expire. The time is 729 represented as the number of seconds from 1970-01-01T0:0:0Z as 730 measured in UTC until the date/time. 732 Additionally, the authorization server MUST return all registered 733 metadata about this client, including any fields provisioned by the 734 authorization server itself. The authorization server MAY reject or 735 replace any of the client's requested metadata values submitted 736 during the registration or update requests and substitute them with 737 suitable values. 739 The response is an "application/json" document with all parameters as 740 top-level members of a JSON object [RFC7159]. 742 If a software statement was used as part of the registration, its 743 value MUST be returned in the response along with other metadata. 744 Client metadata elements used from the software statement MUST also 745 be returned directly as top-level client metadata values in the 746 registration response (possibly with different values, since the 747 values requested and the values used may differ). 749 Following is a non-normative example response: 751 HTTP/1.1 201 Created 752 Content-Type: application/json 753 Cache-Control: no-store 754 Pragma: no-cache 756 { 757 "client_id":"s6BhdRkqt3", 758 "client_secret": "cf136dc3c1fc93f31185e5885805d", 759 "client_id_issued_at":2893256800, 760 "client_secret_expires_at":2893276800, 761 "redirect_uris":[ 762 "https://client.example.org/callback", 763 "https://client.example.org/callback2"], 764 "grant_types": ["authorization_code", "refresh_token"], 765 "client_name":"My Example Client", 766 "client_name#ja-Jpan-JP": 767 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 768 "token_endpoint_auth_method":"client_secret_basic", 769 "logo_uri":"https://client.example.org/logo.png", 770 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 771 "example_extension_parameter": "example_value" 772 } 774 4.2. Client Registration Error Response 776 When an OAuth 2.0 error condition occurs, such as the client 777 presenting an invalid initial access token, the authorization server 778 returns an error response appropriate to the OAuth 2.0 token type. 780 When a registration error condition occurs, the authorization server 781 returns an HTTP 400 status code (unless otherwise specified) with 782 content type "application/json" consisting of a JSON object [RFC7159] 783 describing the error in the response body. 785 Two members are defined for inclusion in the JSON object: 787 error 788 REQUIRED. Single ASCII error code string. 789 error_description 790 OPTIONAL. Human-readable ASCII text description of the error used 791 for debugging. 793 Other members MAY also be included, and if not understood, MUST be 794 ignored. 796 This specification defines the following error codes: 798 invalid_redirect_uri 799 The value of one or more redirection URIs is invalid. 800 invalid_client_metadata 801 The value of one of the client metadata fields is invalid and the 802 server has rejected this request. Note that an authorization 803 server MAY choose to substitute a valid value for any requested 804 parameter of a client's metadata. 805 invalid_software_statement 806 The software statement presented is invalid. 807 unapproved_software_statement 808 The software statement presented is not approved for use by this 809 authorization server. 811 Following is a non-normative example of an error response resulting 812 from a redirection URI that has been blacklisted by the authorization 813 server (with line wraps within values for display purposes only): 815 HTTP/1.1 400 Bad Request 816 Content-Type: application/json 817 Cache-Control: no-store 818 Pragma: no-cache 820 { 821 "error": "invalid_redirect_uri", 822 "error_description": "The redirection URI 823 http://sketchy.example.com is not allowed by this server." 824 } 826 Following is a non-normative example of an error response resulting 827 from an inconsistent combination of "response_types" and 828 "grant_types" values (with line wraps within values for display 829 purposes only): 831 HTTP/1.1 400 Bad Request 832 Content-Type: application/json 833 Cache-Control: no-store 834 Pragma: no-cache 836 { 837 "error": "invalid_client_metadata", 838 "error_description": "The grant type 'authorization_code' must be 839 registered along with the response type 'code' but found only 840 'implicit' instead." 841 } 843 5. IANA Considerations 845 5.1. OAuth Dynamic Registration Client Metadata Registry 847 This specification establishes the OAuth Dynamic Registration Client 848 Metadata registry. 850 OAuth registration client metadata values are registered with a 851 Specification Required ([RFC5226]) after a two-week review period on 852 the oauth-ext-review@ietf.org mailing list, on the advice of one or 853 more Designated Experts. However, to allow for the allocation of 854 values prior to publication, the Designated Expert(s) may approve 855 registration once they are satisfied that such a specification will 856 be published. 858 Registration requests must be sent to the oauth-ext-review@ietf.org 859 mailing list for review and comment, with an appropriate subject 860 (e.g., "Request to register OAuth Dynamic Registration Client 861 Metadata name: example"). 863 Within the review period, the Designated Expert(s) will either 864 approve or deny the registration request, communicating this decision 865 to the review list and IANA. Denials should include an explanation 866 and, if applicable, suggestions as to how to make the request 867 successful. 869 IANA must only accept registry updates from the Designated Expert(s) 870 and should direct all requests for registration to the review mailing 871 list. 873 5.1.1. Registration Template 875 Client Metadata Name: 876 The name requested (e.g., "example"). This name is case 877 sensitive. Names that match other registered names in a case 878 insensitive manner SHOULD NOT be accepted. 880 Client Metadata Description: 881 Brief description of the metadata value (e.g., "Example 882 description"). 884 Change controller: 885 For Standards Track RFCs, state "IESG". For others, give the name 886 of the responsible party. Other details (e.g., postal address, 887 email address, home page URI) may also be included. 889 Specification document(s): 890 Reference to the document(s) that specify the token endpoint 891 authorization method, preferably including a URI that can be used 892 to retrieve a copy of the document(s). An indication of the 893 relevant sections may also be included but is not required. 895 5.1.2. Initial Registry Contents 897 The initial contents of the OAuth Dynamic Registration Client 898 Metadata registry are: 900 o Client Metadata Name: "redirect_uris" 901 o Client Metadata Description: Array of redirection URIs for use in 902 redirect-based flows 903 o Change controller: IESG 904 o Specification document(s): [[ this document ]] 906 o Client Metadata Name: "token_endpoint_auth_method" 907 o Client Metadata Description: Requested authentication method for 908 the token endpoint 909 o Change controller: IESG 910 o Specification document(s): [[ this document ]] 912 o Client Metadata Name: "grant_types" 913 o Client Metadata Description: Array of OAuth 2.0 grant types that 914 the client may use 915 o Change controller: IESG 916 o Specification document(s): [[ this document ]] 918 o Client Metadata Name: "response_types" 919 o Client Metadata Description: Array of the OAuth 2.0 response types 920 that the client may use 922 o Change controller: IESG 923 o Specification document(s): [[ this document ]] 925 o Client Metadata Name: "client_name" 926 o Client Metadata Description: Human-readable name of the client to 927 be presented to the user 928 o Change Controller: IESG 929 o Specification Document(s): [[ this document ]] 931 o Client Metadata Name: "client_uri" 932 o Client Metadata Description: URL of a Web page providing 933 information about the client 934 o Change Controller: IESG 935 o Specification Document(s): [[ this document ]] 937 o Client Metadata Name: "logo_uri" 938 o Client Metadata Description: URL that references a logo for the 939 client 940 o Change Controller: IESG 941 o Specification Document(s): [[ this document ]] 943 o Client Metadata Name: "scope" 944 o Client Metadata Description: Space separated list of scope values 945 o Change Controller: IESG 946 o Specification Document(s): [[ this document ]] 948 o Client Metadata Name: "contacts" 949 o Client Metadata Description: Array of strings representing ways to 950 contact people responsible for this client, typically email 951 addresses 952 o Change Controller: IESG 953 o Specification document(s): [[ this document ]] 955 o Client Metadata Name: "tos_uri" 956 o Client Metadata Description: URL that points to a human-readable 957 Terms of Service document for the client 958 o Change Controller: IESG 959 o Specification Document(s): [[ this document ]] 961 o Client Metadata Name: "policy_uri" 962 o Client Metadata Description: URL that points to a human-readable 963 Policy document for the client 964 o Change Controller: IESG 965 o Specification Document(s): [[ this document ]] 967 o Client Metadata Name: "jwks_uri" 968 o Client Metadata Description: URL referencing the client's JSON Web 969 Key Set [JWK] document representing the client's public keys 971 o Change Controller: IESG 972 o Specification Document(s): [[ this document ]] 974 o Client Metadata Name: "jwks" 975 o Client Metadata Description: Client's JSON Web Key Set [JWK] 976 document representing the client's public keys 977 o Change Controller: IESG 978 o Specification Document(s): [[ this document ]] 980 o Client Metadata Name: "software_id" 981 o Client Metadata Description: Identifier for the software that 982 comprises a client 983 o Change Controller: IESG 984 o Specification Document(s): [[ this document ]] 986 o Client Metadata Name: "software_version" 987 o Client Metadata Description: Version identifier for the software 988 that comprises a client 989 o Change Controller: IESG 990 o Specification Document(s): [[ this document ]] 992 o Client Metadata Name: "client_id" 993 o Client Metadata Description: Client identifier 994 o Change Controller: IESG 995 o Specification Document(s): [[ this document ]] 997 o Client Metadata Name: "client_secret" 998 o Client Metadata Description: Client secret 999 o Change Controller: IESG 1000 o Specification Document(s): [[ this document ]] 1002 o Client Metadata Name: "client_id_issued_at" 1003 o Client Metadata Description: Time at which the client identifier 1004 was issued 1005 o Change Controller: IESG 1006 o Specification Document(s): [[ this document ]] 1008 o Client Metadata Name: "client_secret_expires_at" 1009 o Client Metadata Description: Time at which the client secret will 1010 expire 1011 o Change Controller: IESG 1012 o Specification Document(s): [[ this document ]] 1014 5.2. OAuth Token Endpoint Authentication Methods Registry 1016 This specification establishes the OAuth Token Endpoint 1017 Authentication Methods registry. 1019 Additional values for use as "token_endpoint_auth_method" metadata 1020 values are registered with a Specification Required ([RFC5226]) after 1021 a two-week review period on the oauth-ext-review@ietf.org mailing 1022 list, on the advice of one or more Designated Experts. However, to 1023 allow for the allocation of values prior to publication, the 1024 Designated Expert(s) may approve registration once they are satisfied 1025 that such a specification will be published. 1027 Registration requests must be sent to the oauth-ext-review@ietf.org 1028 mailing list for review and comment, with an appropriate subject 1029 (e.g., "Request to register token_endpoint_auth_method value: 1030 example"). 1032 Within the review period, the Designated Expert(s) will either 1033 approve or deny the registration request, communicating this decision 1034 to the review list and IANA. Denials should include an explanation 1035 and, if applicable, suggestions as to how to make the request 1036 successful. 1038 IANA must only accept registry updates from the Designated Expert(s) 1039 and should direct all requests for registration to the review mailing 1040 list. 1042 5.2.1. Registration Template 1044 Token Endpoint Authorization Method Name: 1045 The name requested (e.g., "example"). This name is case 1046 sensitive. Names that match other registered names in a case 1047 insensitive manner SHOULD NOT be accepted. 1049 Change controller: 1050 For Standards Track RFCs, state "IESG". For others, give the name 1051 of the responsible party. Other details (e.g., postal address, 1052 email address, home page URI) may also be included. 1054 Specification document(s): 1055 Reference to the document(s) that specify the token endpoint 1056 authorization method, preferably including a URI that can be used 1057 to retrieve a copy of the document(s). An indication of the 1058 relevant sections may also be included but is not required. 1060 5.2.2. Initial Registry Contents 1062 The initial contents of the OAuth Token Endpoint Authentication 1063 Methods registry are: 1065 o Token Endpoint Authorization Method Name: "none" 1066 o Change controller: IESG 1067 o Specification document(s): [[ this document ]] 1069 o Token Endpoint Authorization Method Name: "client_secret_post" 1070 o Change controller: IESG 1071 o Specification document(s): [[ this document ]] 1073 o Token Endpoint Authorization Method Name: "client_secret_basic" 1074 o Change controller: IESG 1075 o Specification document(s): [[ this document ]] 1077 6. Security Considerations 1079 Since requests to the client registration endpoint result in the 1080 transmission of clear-text credentials (in the HTTP request and 1081 response), the authorization server MUST require the use of a 1082 transport-layer security mechanism when sending requests to the 1083 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1084 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 1085 transport-layer mechanisms meeting its security requirements. When 1086 using TLS, the client MUST perform a TLS/SSL server certificate 1087 check, per RFC 6125 [RFC6125]. 1089 For clients that use redirect-based grant types such as 1090 "authorization_code" and "implicit", authorization servers MUST 1091 require clients to register their redirection URI values. This can 1092 help mitigate attacks where rogue actors inject and impersonate a 1093 validly registered client and intercept its authorization code or 1094 tokens through an invalid redirection URI or open redirector. 1095 Additionally, in order to prevent hijacking of the return values of 1096 the redirection, registered redirection URI values MUST be one of: 1098 o A remote web site protected by TLS (e.g., 1099 https://client.example.com/oauth_redirect) 1100 o A web site hosted on the local machine using an HTTP URI (e.g., 1101 http://localhost:8080/oauth_redirect) 1102 o A non-HTTP application-specific URL that is available only to the 1103 client application (e.g., exampleapp://oauth_redirect) 1105 Public clients MAY register with an authorization server using this 1106 protocol, if the authorization server's policy allows them. Public 1107 clients use a "none" value for the "token_endpoint_auth_method" 1108 metadata field and are generally used with the "implicit" grant type. 1109 Often these clients will be short-lived in-browser applications 1110 requesting access to a user's resources and access is tied to a 1111 user's active session at the authorization server. Since such 1112 clients often do not have long-term storage, it's possible that such 1113 clients would need to re-register every time the browser application 1114 is loaded. Additionally, such clients may not have ample opportunity 1115 to unregister themselves using the delete action before the browser 1116 closes. To avoid the resulting proliferation of dead client 1117 identifiers, an authorization server MAY decide to expire 1118 registrations for existing clients meeting certain criteria after a 1119 period of time has elapsed. 1121 Since different OAuth 2.0 grant types have different security and 1122 usage parameters, an authorization server MAY require separate 1123 registrations for a piece of software to support multiple grant 1124 types. For instance, an authorization server might require that all 1125 clients using the "authorization_code" grant type make use of a 1126 client secret for the "token_endpoint_auth_method", but any clients 1127 using the "implicit" grant type do not use any authentication at the 1128 token endpoint. In such a situation, a server MAY disallow clients 1129 from registering for both the "authorization_code" and "implicit" 1130 grant types simultaneously. Similarly, the "authorization_code" 1131 grant type is used to represent access on behalf of an end user, but 1132 the "client_credentials" grant type represents access on behalf of 1133 the client itself. For security reasons, an authorization server 1134 could require that different scopes be used for these different use 1135 cases, and as a consequence it MAY disallow these two grant types 1136 from being registered together by the same client. In all of these 1137 cases, the authorization server would respond with an 1138 "invalid_client_metadata" error response. 1140 Unless used as a claim in a software statement, the authorization 1141 server MUST treat all client metadata as self-asserted. For 1142 instance, a rogue client might use the name and logo of a legitimate 1143 client that it is trying to impersonate. Additionally, a rogue 1144 client might try to use the software identifier or software version 1145 of a legitimate client to attempt to associate itself on the 1146 authorization server with instances of the legitimate client. To 1147 counteract this, an authorization server needs to take steps to 1148 mitigate this risk by looking at the entire registration request and 1149 client configuration. For instance, an authorization server could 1150 issue a warning if the domain/site of the logo doesn't match the 1151 domain/site of redirection URIs. An authorization server could also 1152 refuse registration requests from a known software identifier that is 1153 requesting different redirection URIs or a different client homepage 1154 URI. An authorization server can also present warning messages to 1155 end users about dynamically registered clients in all cases, 1156 especially if such clients have been recently registered or have not 1157 been trusted by any users at the authorization server before. 1159 In a situation where the authorization server is supporting open 1160 client registration, it must be extremely careful with any URL 1161 provided by the client that will be displayed to the user (e.g. 1162 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1163 instance, a rogue client could specify a registration request with a 1164 reference to a drive-by download in the "policy_uri". The 1165 authorization server SHOULD check to see if the "logo_uri", 1166 "tos_uri", "client_uri", and "policy_uri" have the same host and 1167 scheme as the those defined in the array of "redirect_uris" and that 1168 all of these URIs resolve to valid web pages. 1170 Clients MAY use both the direct JSON object and the JWT-encoded 1171 software statement to present client metadata to the authorization 1172 server as part of the registration request. A software statement is 1173 cryptographically protected and represents claims made by the issuer 1174 of the statement, while the JSON object represents the self-asserted 1175 claims made by the client or developer directly. If the software 1176 statement is valid and trusted, the values of client metadata within 1177 the software statement MUST take precedence over those metadata 1178 values presented in the plain JSON object, which could have been 1179 modified en route. 1181 The software statement is an item that is self-asserted by the 1182 client, even though its contents have been digitally signed or MACed 1183 by the issuer of the software statement. As such, presentation of 1184 the software statement is not sufficient in most cases to fully 1185 identity a piece of client software. An initial access token, in 1186 contrast, does not necessarily contain information about a particular 1187 piece of client software but instead represents authorization to use 1188 the registration endpoint. An authorization server MUST consider the 1189 full registration request, including the software statement, initial 1190 access token, and JSON client metadata values, when deciding whether 1191 to honor a given registration request. 1193 If an authorization server receives a registration request for a 1194 client that uses the same "software_id" and "software_version" values 1195 as another client, the server should treat the new registration as 1196 being suspect. It is possible that the new client is trying to 1197 impersonate the existing client. 1199 Since a client identifier is a public value that can be used to 1200 impersonate a client at the authorization endpoint, an authorization 1201 server that decides to issue the same client identifier to multiple 1202 instances of a registered client needs to be very particular about 1203 the circumstances under which this occurs. For instance, the 1204 authorization server can limit a given client identifier to clients 1205 using the same redirect-based flow and the same redirection URIs. An 1206 authorization server SHOULD NOT issue the same client secret to 1207 multiple instances of a registered client, even if they are issued 1208 the same client identifier, or else the client secret could be 1209 leaked, allowing malicious imposters to impersonate a confidential 1210 client. 1212 7. References 1214 7.1. Normative References 1216 [IANA.Language] 1217 Internet Assigned Numbers Authority (IANA), "Language 1218 Subtag Registry", 2005. 1220 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1221 key (work in progress), July 2014. 1223 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1224 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1225 in progress), July 2014. 1227 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1228 (JWT)", draft-ietf-oauth-json-web-token (work in 1229 progress), July 2014. 1231 [OAuth.JWT] 1232 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1233 (JWT) Profile for OAuth 2.0 Client Authentication and 1234 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 1235 in progress), July 2014. 1237 [OAuth.SAML2] 1238 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1239 Profile for OAuth 2.0 Client Authentication and 1240 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 1241 in progress), July 2014. 1243 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1244 Requirement Levels", BCP 14, RFC 2119, March 1997. 1246 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1247 RFC 2246, January 1999. 1249 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1250 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1251 May 2008. 1253 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1254 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1256 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1257 Languages", BCP 47, RFC 5646, September 2009. 1259 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1260 Verification of Domain-Based Application Service Identity 1261 within Internet Public Key Infrastructure Using X.509 1262 (PKIX) Certificates in the Context of Transport Layer 1263 Security (TLS)", RFC 6125, March 2011. 1265 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1266 6749, October 2012. 1268 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1269 Framework: Bearer Token Usage", RFC 6750, October 2012. 1271 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1272 Interchange Format", RFC 7159, March 2014. 1274 7.2. Informative References 1276 [I-D.hardjono-oauth-umacore] 1277 Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 1278 2.0", draft-hardjono-oauth-umacore-10 (work in progress), 1279 July 2014. 1281 [OAuth.Registration.Management] 1282 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 1283 Hunt, "OAuth 2.0 Dynamic Client Registration Management 1284 Protocol", draft-ietf-oauth-dyn-reg-management (work in 1285 progress), August 2014. 1287 [OpenID.Registration] 1288 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 1289 Dynamic Client Registration 1.0", February 2014. 1291 Appendix A. Use Cases 1293 This appendix describes different ways that this specification can be 1294 utilized, including describing some of the choices that may need to 1295 be made. Some of the choices are independent and can be used in 1296 combination, whereas some of the choices are interrelated. 1298 A.1. Open versus Protected Dynamic Client Registration 1300 A.1.1. Open Dynamic Client Registration 1302 Authorization servers that support open registration allow 1303 registrations to be made with no initial access token. This allows 1304 all client software to register with the authorization server. 1306 A.1.2. Protected Dynamic Client Registration 1308 Authorization servers that support protected registration require 1309 that an initial access token be used when making registration 1310 requests. While the method by which a client or developer receives 1311 this initial access token and the method by which the authorization 1312 server validates this initial access token are out of scope for this 1313 specification, a common approach is for the developer to use a manual 1314 pre-registration portal at the authorization server that issues an 1315 initial access token to the developer. 1317 A.2. Registration Without or With Software Statements 1319 A.2.1. Registration Without a Software Statement 1321 When a software statement is not used in the registration request, 1322 the authorization server must be willing to use client metadata 1323 values without them being digitally signed or MACed (and thereby 1324 attested to) by any authority. (Note that this choice is independent 1325 of the Open versus Protected choice, and that an initial access token 1326 is another possible form of attestation.) 1328 A.2.2. Registration With a Software Statement 1330 A software statement can be used in a registration request to provide 1331 attestation by an authority for a set of client metadata values. 1332 This can be useful when the authorization server wants to restrict 1333 registration to client software attested to by a set of authorities 1334 or when it wants to know that multiple registration requests refer to 1335 the same piece of client software. 1337 A.3. Registration by the Client or Developer 1339 A.3.1. Registration by the Client 1341 In some use cases, client software will dynamically register itself 1342 with an authorization server to obtain a client identifier and other 1343 information needed to interact with the authorization server. In 1344 this case, no client identifier for the authorization server is 1345 packaged with the client software. 1347 A.3.2. Registration by the Developer 1349 In some cases, the developer (or development software being used by 1350 the developer) will pre-register the client software with the 1351 authorization server or a set of authorization servers. In this 1352 case, the client identifier value(s) for the authorization server(s) 1353 can be packaged with the client software. 1355 A.4. Client ID per Client Instance or per Client Software 1357 A.4.1. Client ID per Client Software Instance 1359 In some cases, each deployed instance of a piece of client software 1360 will dynamically register and obtain distinct client identifier 1361 values. This can be advantageous, for instance, if the code flow is 1362 being used, as it also enables each client instance to have its own 1363 client secret. This can be useful for native clients, which cannot 1364 maintain the secrecy of a client secret value packaged with the 1365 software, but which may be able to maintain the secrecy of a per- 1366 instance client secret. 1368 A.4.2. Client ID Shared Among All Instances of Client Software 1370 In some cases, each deployed instance of a piece of client software 1371 will share a common client identifier value. For instance, this is 1372 often the case for in-browser clients using the implicit flow, when 1373 no client secret is involved. Particular authorization servers might 1374 choose, for instance, to maintain a mapping between software 1375 statement values and client identifier values, and return the same 1376 client identifier value for all registration requests for a 1377 particular piece of software. The circumstances under which an 1378 authorization server would do so, and the specific software statement 1379 characteristics required in this case, are beyond the scope of this 1380 specification. 1382 A.5. Stateful or Stateless Registration 1384 A.5.1. Stateful Client Registration 1386 In some cases, authorization servers will maintain state about 1387 registered clients, typically indexing this state using the client 1388 identifier value. This state would typically include the client 1389 metadata values associated with the client registration, and possibly 1390 other state specific to the authorization server's implementation. 1391 When stateful registration is used, operations to support retrieving 1392 and/or updating this state may be supported. One possible set of 1393 operations upon stateful registrations is described in the 1394 [OAuth.Registration.Management] specification. 1396 A.5.2. Stateless Client Registration 1398 In some cases, authorization servers will be implemented in a manner 1399 the enables them to not maintain any local state about registered 1400 clients. One means of doing this is to encode all the registration 1401 state in the returned client identifier value, and possibly 1402 encrypting the state to the authorization server to maintain the 1403 confidentiality and integrity of the state. 1405 Appendix B. Acknowledgments 1407 The authors thank the OAuth Working Group, the User-Managed Access 1408 Working Group, and the OpenID Connect Working Group participants for 1409 their input to this document. In particular, the following 1410 individuals have been instrumental in their review and contribution 1411 to various versions of this document: Amanda Anganes, Derek Atkins, 1412 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1413 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1414 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1415 Sakimura, Christian Scholz, and Hannes Tschofenig. 1417 Appendix C. Document History 1419 [[ to be removed by the RFC editor before publication as an RFC ]] 1421 -20 1423 o Applied minor editorial fixes from working group comments. 1425 -19 1427 o Added informative references to the OpenID Connect Dynamic Client 1428 Registration and UMA specifications in the introduction. 1429 o Clarified the "jwks" and "jwks_uri" descriptions and included an 1430 example situation in which they might be used. 1431 o Removed "application_type". 1432 o Added redirection URI usage restrictions to the Security 1433 Considerations section, based on the client type. 1434 o Expanded the "tos_uri" and "policy_uri" descriptions. 1436 -18 1438 o Corrected an example HTTP response status code to be 201 Created. 1439 o Said more about who issues and uses initial access tokens and 1440 software statements. 1441 o Stated that the use of an initial access token is required when 1442 the authorization server limits the parties that can register a 1443 client. 1444 o Stated that the implementation and use of all client metadata 1445 fields is OPTIONAL, other than "redirect_uris", which MUST be used 1446 for redirect-based flows and implemented to fulfill the 1447 requirement in Section 2 of OAuth 2.0. 1448 o Added the "application_type" metadata value, which had somehow 1449 been omitted. 1451 o Added missing default metadata values, which had somehow been 1452 omitted. 1453 o Clarified that the "software_id" is ultimately asserted by the 1454 client developer. 1455 o Clarified that the "error" member is required in error responses, 1456 "error_description" member is optional, and other members may be 1457 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. 1464 o Removed "Core" from the document title. 1465 o Explicitly state that all metadata members are optional. 1466 o Clarified language around software statements for use in 1467 registration context. 1468 o Clarified that software statements need to be digitally signed or 1469 MACed. 1470 o Added a "jwks" metadata parameter to parallel the "jwks_uri" 1471 parameter. 1472 o Removed normative language from terminology. 1473 o Expanded abstract and introduction. 1474 o Addressed review comments from several working group members. 1476 -16 1478 o Replaced references to draft-jones-oauth-dyn-reg-metadata and 1479 draft-jones-oauth-dyn-reg-management with draft-ietf-oauth-dyn- 1480 reg-metadata and draft-ietf-oauth-dyn-reg-management. 1481 o Addressed review comments by Phil Hunt and Tony Nadalin. 1483 -15 1485 o Partitioned the Dynamic Client Registration specification into 1486 core, metadata, and management specifications. This built on work 1487 first published as draft-richer-oauth-dyn-reg-core-00 and draft- 1488 richer-oauth-dyn-reg-management-00. 1489 o Added the ability to use Software Statements. This built on work 1490 first published as draft-hunt-oauth-software-statement-00 and 1491 draft-hunt-oauth-client-association-00. 1492 o Created the IANA OAuth Registration Client Metadata registry for 1493 registering Client Metadata values. 1494 o Defined Client Instance term and stated that multiple instances 1495 can use the same client identifier value under certain 1496 circumstances. 1497 o Rewrote the introduction. 1498 o Rewrote the Use Cases appendix. 1500 -14 1502 o Added software_id and software_version metadata fields 1503 o Added direct references to RFC6750 errors in read/update/delete 1504 methods 1506 -13 1508 o Fixed broken example text in registration request and in delete 1509 request 1510 o Added security discussion of separating clients of different grant 1511 types 1512 o Fixed error reference to point to RFC6750 instead of RFC6749 1513 o Clarified that servers must respond to all requests to 1514 configuration endpoint, even if it's just an error code 1515 o Lowercased all Terms to conform to style used in RFC6750 1517 -12 1519 o Improved definition of Initial Access Token 1520 o Changed developer registration scenario to have the Initial Access 1521 Token gotten through a normal OAuth 2.0 flow 1522 o Moved non-normative client lifecycle examples to appendix 1523 o Marked differentiating between auth servers as out of scope 1524 o Added protocol flow diagram 1525 o Added credential rotation discussion 1526 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1527 Resource 1528 o Cleaned up several pieces of text 1530 -11 1532 o Added localized text to registration request and response 1533 examples. 1534 o Removed "client_secret_jwt" and "private_key_jwt". 1535 o Clarified "tos_uri" and "policy_uri" definitions. 1536 o Added the OAuth Token Endpoint Authentication Methods registry for 1537 registering "token_endpoint_auth_method" metadata values. 1538 o Removed uses of non-ASCII characters, per RFC formatting rules. 1539 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1540 to "client_id_issued_at" for greater clarity. 1541 o Added explanatory text for different credentials (Initial Access 1542 Token, Registration Access Token, Client Credentials) and what 1543 they're used for. 1544 o Added Client Lifecycle discussion and examples. 1545 o Defined Initial Access Token in Terminology section. 1547 -10 1548 o Added language to point out that scope values are service-specific 1549 o Clarified normative language around client metadata 1550 o Added extensibility to token_endpoint_auth_method using absolute 1551 URIs 1552 o Added security consideration about registering redirect URIs 1553 o Changed erroneous 403 responses to 401's with notes about token 1554 handling 1555 o Added example for initial registration credential 1557 -09 1559 o Added method of internationalization for Client Metadata values 1560 o Fixed SAML reference 1562 -08 1564 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1565 x509_encryption_uri into a single jwks_uri parameter 1566 o Renamed grant_type to grant_types since it's a plural value 1567 o Formalized name of "OAuth 2.0" throughout document 1568 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1569 grant types 1570 o Added response_types parameter and explanatory text on its use 1571 with and relationship to grant_types 1573 -07 1575 o Changed registration_access_url to registration_client_uri 1576 o Fixed missing text in 5.1 1577 o Added Pragma: no-cache to examples 1578 o Changed "no such client" error to 403 1579 o Renamed Client Registration Access Endpoint to Client 1580 Configuration Endpoint 1581 o Changed all the parameter names containing "_url" to instead use 1582 "_uri" 1583 o Updated example text for forming Client Configuration Endpoint URL 1585 -06 1587 o Removed secret_rotation as a client-initiated action, including 1588 removing client secret rotation endpoint and parameters. 1589 o Changed _links structure to single value registration_access_url. 1590 o Collapsed create/update/read responses into client info response. 1591 o Changed return code of create action to 201. 1592 o Added section to describe suggested generation and composition of 1593 Client Registration Access URL. 1594 o Added clarifying text to PUT and POST requests to specify JSON in 1595 the body. 1597 o Added Editor's Note to DELETE operation about its inclusion. 1598 o Added Editor's Note to registration_access_url about alternate 1599 syntax proposals. 1601 -05 1603 o changed redirect_uri and contact to lists instead of space 1604 delimited strings 1605 o removed operation parameter 1606 o added _links structure 1607 o made client update management more RESTful 1608 o split endpoint into three parts 1609 o changed input to JSON from form-encoded 1610 o added READ and DELETE operations 1611 o removed Requirements section 1612 o changed token_endpoint_auth_type back to 1613 token_endpoint_auth_method to match OIDC who changed to match us 1615 -04 1617 o removed default_acr, too undefined in the general OAuth2 case 1618 o removed default_max_auth_age, since there's no mechanism for 1619 supplying a non-default max_auth_age in OAuth2 1620 o clarified signing and encryption URLs 1621 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1622 match OIDC 1624 -03 1626 o added scope and grant_type claims 1627 o fixed various typos and changed wording for better clarity 1628 o endpoint now returns the full set of client information 1629 o operations on client_update allow for three actions on metadata: 1630 leave existing value, clear existing value, replace existing value 1631 with new value 1633 -02 1635 o Reorganized contributors and references 1636 o Moved OAuth references to RFC 1637 o Reorganized model/protocol sections for clarity 1638 o Changed terminology to "client register" instead of "client 1639 associate" 1640 o Specified that client_id must match across all subsequent requests 1641 o Fixed RFC2XML formatting, especially on lists 1643 -01 1644 o Merged UMA and OpenID Connect registrations into a single document 1645 o Changed to form-parameter inputs to endpoint 1646 o Removed pull-based registration 1648 -00 1650 o Imported original UMA draft specification 1652 Authors' Addresses 1654 Justin Richer 1655 The MITRE Corporation 1657 Email: jricher@mitre.org 1659 Michael B. Jones 1660 Microsoft 1662 Email: mbj@microsoft.com 1663 URI: http://self-issued.info/ 1665 John Bradley 1666 Ping Identity 1668 Email: ve7jtb@ve7jtb.com 1670 Maciej Machulak 1671 Newcastle University 1673 Email: m.p.machulak@ncl.ac.uk 1674 URI: http://ncl.ac.uk/ 1676 Phil Hunt 1677 Oracle Corporation 1679 Email: phil.hunt@yahoo.com