idnits 2.17.1 draft-ietf-oauth-dyn-reg-19.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 5, 2014) is 3544 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 6, 2015 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 August 5, 2014 14 OAuth 2.0 Dynamic Client Registration Protocol 15 draft-ietf-oauth-dyn-reg-19 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 February 6, 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 Authorization Servers MAY allow for other values as defined in 319 grant type extensions to OAuth 2.0. The extension process is 320 described in OAuth 2.0 Section 2.5. If the token endpoint is used 321 in the grant type, the value of this parameter MUST be the same as 322 the value of the "grant_type" parameter passed to the token 323 endpoint defined in the extension. If omitted, the default is 324 that the client 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 Authorization servers MAY allow for other values as defined in 335 response type extensions to OAuth 2.0. The extension process is 336 described in OAuth 2.0 Section 2.5. If the authorization endpoint 337 is used by the grant type, the value of this parameter MUST be the 338 same as the value of the "response_type" parameter passed to the 339 authorization endpoint defined in the extension. 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 be 396 used together. 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 be 405 used together. 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 the member "client_name#en-us" can be 521 accessed using the JavaScript syntax "j["client_name#en-us"]". 523 2.3. Software Statement 525 A software statement is a JSON Web Token (JWT) [JWT] that asserts 526 metadata values about the client software as a bundle. A set of 527 claims that can be used in a software statement are defined in 528 Section 2. When presented to the authorization server as part of a 529 client registration request, the software statement MUST be digitally 530 signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer) 531 claim denoting the party attesting to the claims in the software 532 statement. It is RECOMMENDED that software statements be digitally 533 signed using the "RS256" signature algorithm, although particular 534 applications MAY specify the use of different algorithms. 536 The means by which a client or developer obtains a software statement 537 are outside the scope of this specification. Some common methods 538 could include a client developer generating a client-specific JWT 539 registering with a software API publisher to obtain a software 540 statement for a class of clients. The software statement is 541 typically distributed with all instances of a client application. 543 The criteria by which authorization servers determine whether to 544 trust and utilize the information in a software statement are beyond 545 the scope of this specification. 547 In some cases, authorization servers MAY choose to accept a software 548 statement value directly as a client identifier in an authorization 549 request, without a prior dynamic client registration having been 550 performed. The circumstances under which an authorization server 551 would do so, and the specific software statement characteristics 552 required in this case, are beyond the scope of this specification. 554 3. Client Registration Endpoint 556 The client registration endpoint is an OAuth 2.0 endpoint defined in 557 this document that is designed to allow a client to be registered 558 with the authorization server. The client registration endpoint MUST 559 accept HTTP POST messages with request parameters encoded in the 560 entity body using the "application/json" format. The client 561 registration endpoint MUST be protected by a transport-layer security 562 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] 563 and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer 564 mechanisms meeting its security requirements. When using TLS, the 565 client MUST perform a TLS/SSL server certificate check, per RFC 6125 566 [RFC6125]. 568 The client registration endpoint MAY be an OAuth 2.0 protected 569 resource and accept an initial access token in the form of an OAuth 570 2.0 [RFC6749] access token to limit registration to only previously 571 authorized parties. The method by which the initial access token is 572 obtained by the client or developer is generally out-of-band and is 573 out of scope for this specification. The method by which the initial 574 access token is verified and validated by the client registration 575 endpoint is out of scope for this specification. 577 To support open registration and facilitate wider interoperability, 578 the client registration endpoint SHOULD allow registration requests 579 with no authorization (which is to say, with no initial access token 580 in the request). These requests MAY be rate-limited or otherwise 581 limited to prevent a denial-of-service attack on the client 582 registration endpoint. 584 3.1. Client Registration Request 586 This operation registers a client with the authorization server. The 587 authorization server assigns this client a unique client identifier, 588 optionally assigns a client secret, and associates the metadata 589 provided in the request with the issued client identifier. The 590 request includes any client metadata parameters being specified for 591 the client during the registration. The authorization server MAY 592 provision default values for any items omitted in the client 593 metadata. 595 To register, the client or developer sends an HTTP POST to the client 596 registration endpoint with a content type of "application/json". The 597 HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON 598 object and all requested client metadata values as top-level members 599 of that JSON object. 601 Client metadata values may also be provided in a software statement, 602 as described in Section 2.3. Software statements are included in the 603 requesting JSON object using this member: 605 software_statement 606 A software statement containing client metadata values about the 607 client software as claims. 609 For example, if the server supports open registration (with no 610 initial access token), the client could send the following 611 registration request to the client registration endpoint: 613 The following is a non-normative example request not using an initial 614 access token (with line wraps within values for display purposes 615 only): 617 POST /register HTTP/1.1 618 Content-Type: application/json 619 Accept: application/json 620 Host: server.example.com 622 { 623 "redirect_uris":[ 624 "https://client.example.org/callback", 625 "https://client.example.org/callback2"], 626 "client_name":"My Example Client", 627 "client_name#ja-Jpan-JP": 628 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 629 "token_endpoint_auth_method":"client_secret_basic", 630 "logo_uri":"https://client.example.org/logo.png", 631 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 632 "example_extension_parameter": "example_value" 633 } 635 Alternatively, if the server supports authorized registration, the 636 developer or the client will be provisioned with an initial access 637 token. (The method by which the initial access token is obtained is 638 out of scope for this specification.) The developer or client sends 639 the following authorized registration request to the client 640 registration endpoint. Note that the initial access token sent in 641 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 642 2.0 token type could be used by an authorization server. 644 The following is a non-normative example request using an initial 645 access token (with line wraps within values for display purposes 646 only): 648 POST /register HTTP/1.1 649 Content-Type: application/json 650 Accept: application/json 651 Authorization: Bearer ey23f2.adfj230.af32-developer321 652 Host: server.example.com 654 { 655 "redirect_uris":["https://client.example.org/callback", 656 "https://client.example.org/callback2"], 657 "client_name":"My Example Client", 658 "client_name#ja-Jpan-JP": 659 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 660 "token_endpoint_auth_method":"client_secret_basic", 661 "policy_uri":"https://client.example.org/policy.html", 662 "jwks":{"keys":[{...omitted for brevity...}]}, 663 "example_extension_parameter": "example_value" 664 } 666 In the following example, some registration parameters are conveyed 667 as claims in a software statement, while some values specific to the 668 client instance are conveyed as regular parameters (with line wraps 669 within values for display purposes only): 671 POST /register HTTP/1.1 672 Content-Type: application/json 673 Accept: application/json 674 Host: server.example.com 676 { 677 "redirect_uris":[ 678 "https://client.example.org/callback", 679 "https://client.example.org/callback2" 680 ], 681 "software_statement":"eyJhbGciOiJFUzI1NiJ9. 682 eyJpc3Mi[...omitted for brevity...]. 683 J9l-ZhwP[...omitted for brevity...]", 684 "scope":"read write", 685 "example_extension_parameter":"example_value" 686 } 688 3.2. Client Registration Response 690 Upon successful registration, the authorization server returns a 691 client identifier for the client. The server responds with an HTTP 692 201 Created code and a body of type "application/json" with content 693 as described in Section 4.1. 695 Upon an unsuccessful registration, the authorization server responds 696 with an error, as described in Section 4.2. 698 4. Responses 700 The following responses are sent in response to registration 701 requests. 703 4.1. Client Information Response 705 The response contains the client identifier as well as the client 706 secret, if the client is a confidential client. The response MAY 707 contain additional fields as specified by extensions to this 708 specification. 710 client_id 711 REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be 712 currently valid for any other registered client, though an 713 authorization server MAY issue the same client identifier to 714 multiple instances of a registered client, at its discretion. 715 client_secret 716 OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be 717 unique for each "client_id". This value is used by confidential 718 clients to authenticate to the token endpoint as described in 719 OAuth 2.0 [RFC6749] Section 2.3.1. 720 client_id_issued_at 721 OPTIONAL. Time at which the client identifier was issued. The 722 time is represented as the number of seconds from 723 1970-01-01T0:0:0Z as measured in UTC until the date/time. 724 client_secret_expires_at 725 REQUIRED if "client_secret" is issued. Time at which the client 726 secret will expire or 0 if it will not expire. The time is 727 represented as the number of seconds from 1970-01-01T0:0:0Z as 728 measured in UTC until the date/time. 730 Additionally, the authorization server MUST return all registered 731 metadata about this client, including any fields provisioned by the 732 authorization server itself. The authorization server MAY reject or 733 replace any of the client's requested metadata values submitted 734 during the registration or update requests and substitute them with 735 suitable values. 737 The response is an "application/json" document with all parameters as 738 top-level members of a JSON object [RFC7159]. 740 If a software statement was used as part of the registration, its 741 value MUST be returned in the response along with other metadata. 742 Client metadata elements used from the software statement MUST also 743 be returned directly as top-level client metadata values in the 744 registration response (possibly with different values, since the 745 values requested and the values used may differ). 747 Following is a non-normative example response: 749 HTTP/1.1 201 Created 750 Content-Type: application/json 751 Cache-Control: no-store 752 Pragma: no-cache 754 { 755 "client_id":"s6BhdRkqt3", 756 "client_secret": "cf136dc3c1fc93f31185e5885805d", 757 "client_id_issued_at":2893256800, 758 "client_secret_expires_at":2893276800, 759 "redirect_uris":[ 760 "https://client.example.org/callback", 761 "https://client.example.org/callback2"], 762 "grant_types": ["authorization_code", "refresh_token"], 763 "client_name":"My Example Client", 764 "client_name#ja-Jpan-JP": 765 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 766 "token_endpoint_auth_method":"client_secret_basic", 767 "logo_uri":"https://client.example.org/logo.png", 768 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 769 "example_extension_parameter": "example_value" 770 } 772 4.2. Client Registration Error Response 774 When an OAuth 2.0 error condition occurs, such as the client 775 presenting an invalid initial access token, the authorization server 776 returns an error response appropriate to the OAuth 2.0 token type. 778 When a registration error condition occurs, the authorization server 779 returns an HTTP 400 status code (unless otherwise specified) with 780 content type "application/json" consisting of a JSON object [RFC7159] 781 describing the error in the response body. 783 Two members are defined for inclusion in the JSON object: 785 error 786 REQUIRED. Single ASCII error code string. 787 error_description 788 OPTIONAL. Human-readable ASCII text description of the error used 789 for debugging. 791 Other members MAY also be included, and if not understood, MUST be 792 ignored. 794 This specification defines the following error codes: 796 invalid_redirect_uri 797 The value of one or more redirection URIs is invalid. 798 invalid_client_metadata 799 The value of one of the client metadata fields is invalid and the 800 server has rejected this request. Note that an authorization 801 server MAY choose to substitute a valid value for any requested 802 parameter of a client's metadata. 803 invalid_software_statement 804 The software statement presented is invalid. 805 unapproved_software_statement 806 The software statement presented is not approved for use by this 807 authorization server. 809 Following is a non-normative example of an error response resulting 810 from a redirection URI that has been blacklisted by the authorization 811 server (with line wraps within values for display purposes only): 813 HTTP/1.1 400 Bad Request 814 Content-Type: application/json 815 Cache-Control: no-store 816 Pragma: no-cache 818 { 819 "error": "invalid_redirect_uri", 820 "error_description": "The redirection URI 821 http://sketchy.example.com is not allowed by this server." 822 } 824 Following is a non-normative example of an error response resulting 825 from an inconsistent combination of "response_types" and 826 "grant_types" values (with line wraps within values for display 827 purposes only): 829 HTTP/1.1 400 Bad Request 830 Content-Type: application/json 831 Cache-Control: no-store 832 Pragma: no-cache 834 { 835 "error": "invalid_client_metadata", 836 "error_description": "The grant type 'authorization_code' must be 837 registered along with the response type 'code' but found only 838 'implicit' instead." 839 } 841 5. IANA Considerations 843 5.1. OAuth Dynamic Registration Client Metadata Registry 845 This specification establishes the OAuth Dynamic Registration Client 846 Metadata registry. 848 OAuth registration client metadata values are registered with a 849 Specification Required ([RFC5226]) after a two-week review period on 850 the oauth-ext-review@ietf.org mailing list, on the advice of one or 851 more Designated Experts. However, to allow for the allocation of 852 values prior to publication, the Designated Expert(s) may approve 853 registration once they are satisfied that such a specification will 854 be published. 856 Registration requests must be sent to the oauth-ext-review@ietf.org 857 mailing list for review and comment, with an appropriate subject 858 (e.g., "Request to register OAuth Dynamic Registration Client 859 Metadata name: example"). 861 Within the review period, the Designated Expert(s) will either 862 approve or deny the registration request, communicating this decision 863 to the review list and IANA. Denials should include an explanation 864 and, if applicable, suggestions as to how to make the request 865 successful. 867 IANA must only accept registry updates from the Designated Expert(s) 868 and should direct all requests for registration to the review mailing 869 list. 871 5.1.1. Registration Template 873 Client Metadata Name: 874 The name requested (e.g., "example"). This name is case 875 sensitive. Names that match other registered names in a case 876 insensitive manner SHOULD NOT be accepted. 878 Client Metadata Description: 879 Brief description of the metadata value (e.g., "Example 880 description"). 882 Change controller: 883 For Standards Track RFCs, state "IESG". For others, give the name 884 of the responsible party. Other details (e.g., postal address, 885 email address, home page URI) may also be included. 887 Specification document(s): 888 Reference to the document(s) that specify the token endpoint 889 authorization method, preferably including a URI that can be used 890 to retrieve a copy of the document(s). An indication of the 891 relevant sections may also be included but is not required. 893 5.1.2. Initial Registry Contents 895 The initial contents of the OAuth Dynamic Registration Client 896 Metadata registry are: 898 o Client Metadata Name: "redirect_uris" 899 o Client Metadata Description: Array of redirection URIs for use in 900 redirect-based flows 901 o Change controller: IESG 902 o Specification document(s): [[ this document ]] 904 o Client Metadata Name: "token_endpoint_auth_method" 905 o Client Metadata Description: Requested authentication method for 906 the token endpoint 907 o Change controller: IESG 908 o Specification document(s): [[ this document ]] 910 o Client Metadata Name: "grant_types" 911 o Client Metadata Description: Array of OAuth 2.0 grant types that 912 the client may use 913 o Change controller: IESG 914 o Specification document(s): [[ this document ]] 916 o Client Metadata Name: "response_types" 917 o Client Metadata Description: Array of the OAuth 2.0 response types 918 that the client may use 920 o Change controller: IESG 921 o Specification document(s): [[ this document ]] 923 o Client Metadata Name: "client_name" 924 o Client Metadata Description: Human-readable name of the client to 925 be presented to the user 926 o Change Controller: IESG 927 o Specification Document(s): [[ this document ]] 929 o Client Metadata Name: "client_uri" 930 o Client Metadata Description: URL of a Web page providing 931 information about the client 932 o Change Controller: IESG 933 o Specification Document(s): [[ this document ]] 935 o Client Metadata Name: "logo_uri" 936 o Client Metadata Description: URL that references a logo for the 937 client 938 o Change Controller: IESG 939 o Specification Document(s): [[ this document ]] 941 o Client Metadata Name: "scope" 942 o Client Metadata Description: Space separated list of scope values 943 o Change Controller: IESG 944 o Specification Document(s): [[ this document ]] 946 o Client Metadata Name: "contacts" 947 o Client Metadata Description: Array of strings representing ways to 948 contact people responsible for this client, typically email 949 addresses 950 o Change Controller: IESG 951 o Specification document(s): [[ this document ]] 953 o Client Metadata Name: "tos_uri" 954 o Client Metadata Description: URL that points to a human-readable 955 Terms of Service document for the client 956 o Change Controller: IESG 957 o Specification Document(s): [[ this document ]] 959 o Client Metadata Name: "policy_uri" 960 o Client Metadata Description: URL that points to a human-readable 961 Policy document for the client 962 o Change Controller: IESG 963 o Specification Document(s): [[ this document ]] 965 o Client Metadata Name: "jwks_uri" 966 o Client Metadata Description: URL referencing the client's JSON Web 967 Key Set [JWK] document representing the client's public keys 969 o Change Controller: IESG 970 o Specification Document(s): [[ this document ]] 972 o Client Metadata Name: "jwks" 973 o Client Metadata Description: Client's JSON Web Key Set [JWK] 974 document representing the client's public keys 975 o Change Controller: IESG 976 o Specification Document(s): [[ this document ]] 978 o Client Metadata Name: "software_id" 979 o Client Metadata Description: Identifier for the software that 980 comprises a client 981 o Change Controller: IESG 982 o Specification Document(s): [[ this document ]] 984 o Client Metadata Name: "software_version" 985 o Client Metadata Description: Version identifier for the software 986 that comprises a client 987 o Change Controller: IESG 988 o Specification Document(s): [[ this document ]] 990 o Client Metadata Name: "client_id" 991 o Client Metadata Description: Client identifier 992 o Change Controller: IESG 993 o Specification Document(s): [[ this document ]] 995 o Client Metadata Name: "client_secret" 996 o Client Metadata Description: Client secret 997 o Change Controller: IESG 998 o Specification Document(s): [[ this document ]] 1000 o Client Metadata Name: "client_id_issued_at" 1001 o Client Metadata Description: Time at which the client identifier 1002 was issued 1003 o Change Controller: IESG 1004 o Specification Document(s): [[ this document ]] 1006 o Client Metadata Name: "client_secret_expires_at" 1007 o Client Metadata Description: Time at which the client secret will 1008 expire 1009 o Change Controller: IESG 1010 o Specification Document(s): [[ this document ]] 1012 5.2. OAuth Token Endpoint Authentication Methods Registry 1014 This specification establishes the OAuth Token Endpoint 1015 Authentication Methods registry. 1017 Additional values for use as "token_endpoint_auth_method" metadata 1018 values are registered with a Specification Required ([RFC5226]) after 1019 a two-week review period on the oauth-ext-review@ietf.org mailing 1020 list, on the advice of one or more Designated Experts. However, to 1021 allow for the allocation of values prior to publication, the 1022 Designated Expert(s) may approve registration once they are satisfied 1023 that such a specification will be published. 1025 Registration requests must be sent to the oauth-ext-review@ietf.org 1026 mailing list for review and comment, with an appropriate subject 1027 (e.g., "Request to register token_endpoint_auth_method value: 1028 example"). 1030 Within the review period, the Designated Expert(s) will either 1031 approve or deny the registration request, communicating this decision 1032 to the review list and IANA. Denials should include an explanation 1033 and, if applicable, suggestions as to how to make the request 1034 successful. 1036 IANA must only accept registry updates from the Designated Expert(s) 1037 and should direct all requests for registration to the review mailing 1038 list. 1040 5.2.1. Registration Template 1042 Token Endpoint Authorization Method Name: 1043 The name requested (e.g., "example"). This name is case 1044 sensitive. Names that match other registered names in a case 1045 insensitive manner SHOULD NOT be accepted. 1047 Change controller: 1048 For Standards Track RFCs, state "IESG". For others, give the name 1049 of the responsible party. Other details (e.g., postal address, 1050 email address, home page URI) may also be included. 1052 Specification document(s): 1053 Reference to the document(s) that specify the token endpoint 1054 authorization method, preferably including a URI that can be used 1055 to retrieve a copy of the document(s). An indication of the 1056 relevant sections may also be included but is not required. 1058 5.2.2. Initial Registry Contents 1060 The initial contents of the OAuth Token Endpoint Authentication 1061 Methods registry are: 1063 o Token Endpoint Authorization Method Name: "none" 1064 o Change controller: IESG 1065 o Specification document(s): [[ this document ]] 1067 o Token Endpoint Authorization Method Name: "client_secret_post" 1068 o Change controller: IESG 1069 o Specification document(s): [[ this document ]] 1071 o Token Endpoint Authorization Method Name: "client_secret_basic" 1072 o Change controller: IESG 1073 o Specification document(s): [[ this document ]] 1075 6. Security Considerations 1077 Since requests to the client registration endpoint result in the 1078 transmission of clear-text credentials (in the HTTP request and 1079 response), the authorization server MUST require the use of a 1080 transport-layer security mechanism when sending requests to the 1081 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1082 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 1083 transport-layer mechanisms meeting its security requirements. When 1084 using TLS, the client MUST perform a TLS/SSL server certificate 1085 check, per RFC 6125 [RFC6125]. 1087 For clients that use redirect-based grant types such as 1088 "authorization_code" and "implicit", authorization servers MUST 1089 require clients to register their redirection URI values. This can 1090 help mitigate attacks where rogue actors inject and impersonate a 1091 validly registered client and intercept its authorization code or 1092 tokens through an invalid redirection URI or open redirector. 1093 Additionally, in order to prevent hijacking of the return values of 1094 the redirection, registered redirection URI values MUST be one of: 1096 o A remote web site protected by TLS (e.g., 1097 https://client.example.com/oauth_redirect) 1098 o A web site hosted on the local machine using an HTTP URI (e.g., 1099 http://localhost:8080/oauth_redirect) 1100 o A non-HTTP application-specific URL that is available only to the 1101 client application (e.g., exampleapp://oauth_redirect) 1103 Public clients MAY register with an authorization server using this 1104 protocol, if the authorization server's policy allows them. Public 1105 clients use a "none" value for the "token_endpoint_auth_method" 1106 metadata field and are generally used with the "implicit" grant type. 1107 Often these clients will be short-lived in-browser applications 1108 requesting access to a user's resources and access is tied to a 1109 user's active session at the authorization server. Since such 1110 clients often do not have long-term storage, it's possible that such 1111 clients would need to re-register every time the browser application 1112 is loaded. Additionally, such clients may not have ample opportunity 1113 to unregister themselves using the delete action before the browser 1114 closes. To avoid the resulting proliferation of dead client 1115 identifiers, an authorization server MAY decide to expire 1116 registrations for existing clients meeting certain criteria after a 1117 period of time has elapsed. 1119 Since different OAuth 2.0 grant types have different security and 1120 usage parameters, an authorization server MAY require separate 1121 registrations for a piece of software to support multiple grant 1122 types. For instance, an authorization server might require that all 1123 clients using the "authorization_code" grant type make use of a 1124 client secret for the "token_endpoint_auth_method", but any clients 1125 using the "implicit" grant type do not use any authentication at the 1126 token endpoint. In such a situation, a server MAY disallow clients 1127 from registering for both the "authorization_code" and "implicit" 1128 grant types simultaneously. Similarly, the "authorization_code" 1129 grant type is used to represent access on behalf of an end user, but 1130 the "client_credentials" grant type represents access on behalf of 1131 the client itself. For security reasons, an authorization server 1132 could require that different scopes be used for these different use 1133 cases, and as a consequence it MAY disallow these two grant types 1134 from being registered together by the same client. In all of these 1135 cases, the authorization server would respond with an 1136 "invalid_client_metadata" error response. 1138 Unless used as a claim in a software statement, the authorization 1139 server MUST treat all client metadata as self-asserted. For 1140 instance, a rogue client might use the name and logo of a legitimate 1141 client that it is trying to impersonate. Additionally, a rogue 1142 client might try to use the software identifier or software version 1143 of a legitimate client to attempt to associate itself on the 1144 authorization server with instances of the legitimate client. To 1145 counteract this, an authorization server needs to take steps to 1146 mitigate this risk by looking at the entire registration request and 1147 client configuration. For instance, an authorization server could 1148 issue a warning if the domain/site of the logo doesn't match the 1149 domain/site of redirection URIs. An authorization server could also 1150 refuse registration requests from a known software identifier that is 1151 requesting different redirection URIs or a different client homepage 1152 URI. An authorization server can also present warning messages to 1153 end users about dynamically registered clients in all cases, 1154 especially if such clients have been recently registered or have not 1155 been trusted by any users at the authorization server before. 1157 In a situation where the authorization server is supporting open 1158 client registration, it must be extremely careful with any URL 1159 provided by the client that will be displayed to the user (e.g. 1160 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1161 instance, a rogue client could specify a registration request with a 1162 reference to a drive-by download in the "policy_uri". The 1163 authorization server SHOULD check to see if the "logo_uri", 1164 "tos_uri", "client_uri", and "policy_uri" have the same host and 1165 scheme as the those defined in the array of "redirect_uris" and that 1166 all of these URIs resolve to valid web pages. 1168 Clients MAY use both the direct JSON object and the JWT-encoded 1169 software statement to present client metadata to the authorization 1170 server as part of the registration request. A software statement is 1171 cryptographically protected and represents claims made by the issuer 1172 of the statement, while the JSON object represents the self-asserted 1173 claims made by the client or developer directly. If the software 1174 statement is valid and trusted, the values of client metadata within 1175 the software statement MUST take precedence over those metadata 1176 values presented in the plain JSON object, which could have been 1177 modified en route. 1179 The software statement is an item that is self-asserted by the 1180 client, even though its contents have been digitally signed or MACed 1181 by the issuer of the software statement. As such, presentation of 1182 the software statement is not sufficient in most cases to fully 1183 identity a piece of client software. An initial access token, in 1184 contrast, does not necessarily contain information about a particular 1185 piece of client software but instead represents authorization to use 1186 the registration endpoint. An authorization server MUST consider the 1187 full registration request, including the software statement, initial 1188 access token, and JSON client metadata values, when deciding whether 1189 to honor a given registration request. 1191 If an authorization server receives a registration request for a 1192 client that uses the same "software_id" and "software_version" values 1193 as another client, the server should treat the new registration as 1194 being suspect. It is possible that the new client is trying to 1195 impersonate the existing client. 1197 Since a client identifier is a public value that can be used to 1198 impersonate a client at the authorization endpoint, an authorization 1199 server that decides to issue the same client identifier to multiple 1200 instances of a registered client MUST be very particular about the 1201 circumstances under which this occurs. For instance, the 1202 authorization server can limit a given client identifier to clients 1203 using the same redirect-based flow and the same redirection URIs. An 1204 authorization server SHOULD NOT issue the same client secret to 1205 multiple instances of a registered client, even if they are issued 1206 the same client identifier, or else the client secret could be 1207 leaked, allowing malicious imposters to impersonate a confidential 1208 client. 1210 7. References 1212 7.1. Normative References 1214 [IANA.Language] 1215 Internet Assigned Numbers Authority (IANA), "Language 1216 Subtag Registry", 2005. 1218 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1219 key (work in progress), July 2014. 1221 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1222 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1223 in progress), July 2014. 1225 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1226 (JWT)", draft-ietf-oauth-json-web-token (work in 1227 progress), July 2014. 1229 [OAuth.JWT] 1230 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1231 (JWT) Profile for OAuth 2.0 Client Authentication and 1232 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 1233 in progress), July 2014. 1235 [OAuth.SAML2] 1236 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1237 Profile for OAuth 2.0 Client Authentication and 1238 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 1239 in progress), July 2014. 1241 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1242 Requirement Levels", BCP 14, RFC 2119, March 1997. 1244 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1245 RFC 2246, January 1999. 1247 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1248 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1249 May 2008. 1251 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1252 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1254 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1255 Languages", BCP 47, RFC 5646, September 2009. 1257 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1258 Verification of Domain-Based Application Service Identity 1259 within Internet Public Key Infrastructure Using X.509 1260 (PKIX) Certificates in the Context of Transport Layer 1261 Security (TLS)", RFC 6125, March 2011. 1263 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1264 6749, October 2012. 1266 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1267 Framework: Bearer Token Usage", RFC 6750, October 2012. 1269 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1270 Interchange Format", RFC 7159, March 2014. 1272 7.2. Informative References 1274 [I-D.hardjono-oauth-umacore] 1275 Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 1276 2.0", draft-hardjono-oauth-umacore-10 (work in progress), 1277 July 2014. 1279 [OAuth.Registration.Management] 1280 Richer, J., Jones, M., Bradley, J., Machulak, M., and P. 1281 Hunt, "OAuth 2.0 Dynamic Client Registration Management 1282 Protocol", draft-ietf-oauth-dyn-reg-management (work in 1283 progress), August 2014. 1285 [OpenID.Registration] 1286 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 1287 Dynamic Client Registration 1.0", February 2014. 1289 Appendix A. Use Cases 1291 This appendix describes different ways that this specification can be 1292 utilized, including describing some of the choices that may need to 1293 be made. Some of the choices are independent and can be used in 1294 combination, whereas some of the choices are interrelated. 1296 A.1. Open versus Protected Dynamic Client Registration 1298 A.1.1. Open Dynamic Client Registration 1300 Authorization servers that support open registration allow 1301 registrations to be made with no initial access token. This allows 1302 all client software to register with the authorization server. 1304 A.1.2. Protected Dynamic Client Registration 1306 Authorization servers that support protected registration require 1307 that an initial access token be used when making registration 1308 requests. While the method by which a client or developer receives 1309 this initial access token and the method by which the authorization 1310 server validates this initial access token are out of scope for this 1311 specification, a common approach is for the developer to use a manual 1312 pre-registration portal at the authorization server that issues an 1313 initial access token to the developer. 1315 A.2. Registration Without or With Software Statements 1317 A.2.1. Registration Without a Software Statement 1319 When a software statement is not used in the registration request, 1320 the authorization server must be willing to use client metadata 1321 values without them being digitally signed or MACed (and thereby 1322 attested to) by any authority. (Note that this choice is independent 1323 of the Open versus Protected choice, and that an initial access token 1324 is another possible form of attestation.) 1326 A.2.2. Registration With a Software Statement 1328 A software statement can be used in a registration request to provide 1329 attestation by an authority for a set of client metadata values. 1330 This can be useful when the authorization server wants to restrict 1331 registration to client software attested to by a set of authorities 1332 or when it wants to know that multiple registration requests refer to 1333 the same piece of client software. 1335 A.3. Registration by the Client or Developer 1337 A.3.1. Registration by the Client 1339 In some use cases, client software will dynamically register itself 1340 with an authorization server to obtain a client identifier and other 1341 information needed to interact with the authorization server. In 1342 this case, no client identifier for the authorization server is 1343 packaged with the client software. 1345 A.3.2. Registration by the Developer 1347 In some cases, the developer (or development software being used by 1348 the developer) will pre-register the client software with the 1349 authorization server or a set of authorization servers. In this 1350 case, the client identifier value(s) for the authorization server(s) 1351 can be packaged with the client software. 1353 A.4. Client ID per Client Instance or per Client Software 1355 A.4.1. Client ID per Client Software Instance 1357 In some cases, each deployed instance of a piece of client software 1358 will dynamically register and obtain distinct client identifier 1359 values. This can be advantageous, for instance, if the code flow is 1360 being used, as it also enables each client instance to have its own 1361 client secret. This can be useful for native clients, which cannot 1362 maintain the secrecy of a client secret value packaged with the 1363 software, but which may be able to maintain the secrecy of a per- 1364 instance client secret. 1366 A.4.2. Client ID Shared Among All Instances of Client Software 1368 In some cases, each deployed instance of a piece of client software 1369 will share a common client identifier value. For instance, this is 1370 often the case for in-browser clients using the implicit flow, when 1371 no client secret is involved. Particular authorization servers might 1372 choose, for instance, to maintain a mapping between software 1373 statement values and client identifier values, and return the same 1374 client identifier value for all registration requests for a 1375 particular piece of software. The circumstances under which an 1376 authorization server would do so, and the specific software statement 1377 characteristics required in this case, are beyond the scope of this 1378 specification. 1380 A.5. Stateful or Stateless Registration 1382 A.5.1. Stateful Client Registration 1384 In some cases, authorization servers will maintain state about 1385 registered clients, typically indexing this state using the client 1386 identifier value. This state would typically include the client 1387 metadata values associated with the client registration, and possibly 1388 other state specific to the authorization server's implementation. 1389 When stateful registration is used, operations to support retrieving 1390 and/or updating this state may be supported. One possible set of 1391 operations upon stateful registrations is described in the 1392 [OAuth.Registration.Management] specification. 1394 A.5.2. Stateless Client Registration 1396 In some cases, authorization servers will be implemented in a manner 1397 the enables them to not maintain any local state about registered 1398 clients. One means of doing this is to encode all the registration 1399 state in the returned client identifier value, and possibly 1400 encrypting the state to the authorization server to maintain the 1401 confidentiality and integrity of the state. 1403 Appendix B. Acknowledgments 1405 The authors thank the OAuth Working Group, the User-Managed Access 1406 Working Group, and the OpenID Connect Working Group participants for 1407 their input to this document. In particular, the following 1408 individuals have been instrumental in their review and contribution 1409 to various versions of this document: Amanda Anganes, Derek Atkins, 1410 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1411 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1412 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1413 Sakimura, Christian Scholz, and Hannes Tschofenig. 1415 Appendix C. Document History 1417 [[ to be removed by the RFC editor before publication as an RFC ]] 1419 -19 1421 o Added informative references to the OpenID Connect Dynamic Client 1422 Registration and UMA specifications in the introduction. 1423 o Clarified the "jwks" and "jwks_uri" descriptions and included an 1424 example situation in which they might be used. 1425 o Removed "application_type". 1426 o Added redirection URI usage restrictions to the Security 1427 Considerations section, based on the client type. 1428 o Expanded the "tos_uri" and "policy_uri" descriptions. 1430 -18 1432 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. 1435 o Stated that the use of an initial access token is required when 1436 the authorization server limits the parties that can register a 1437 client. 1438 o Stated that the implementation and use of all client metadata 1439 fields is OPTIONAL, other than "redirect_uris", which MUST be used 1440 for redirect-based flows and implemented to fulfill the 1441 requirement in Section 2 of OAuth 2.0. 1442 o Added the "application_type" metadata value, which had somehow 1443 been omitted. 1444 o Added missing default metadata values, which had somehow been 1445 omitted. 1446 o Clarified that the "software_id" is ultimately asserted by the 1447 client developer. 1449 o Clarified that the "error" member is required in error responses, 1450 "error_description" member is optional, and other members may be 1451 present. 1452 o Added security consideration about registrations with duplicate 1453 "software_id" and "software_version" values. 1455 -17 1457 o Merged draft-ietf-oauth-dyn-reg-metadata back into this document. 1458 o Removed "Core" from the document title. 1459 o Explicitly state that all metadata members are optional. 1460 o Clarified language around software statements for use in 1461 registration context. 1462 o Clarified that software statements need to be digitally signed or 1463 MACed. 1464 o Added a "jwks" metadata parameter to parallel the "jwks_uri" 1465 parameter. 1466 o Removed normative language from terminology. 1467 o Expanded abstract and introduction. 1468 o Addressed review comments from several working group members. 1470 -16 1472 o Replaced references to draft-jones-oauth-dyn-reg-metadata and 1473 draft-jones-oauth-dyn-reg-management with draft-ietf-oauth-dyn- 1474 reg-metadata and draft-ietf-oauth-dyn-reg-management. 1475 o Addressed review comments by Phil Hunt and Tony Nadalin. 1477 -15 1479 o Partitioned the Dynamic Client Registration specification into 1480 core, metadata, and management specifications. This built on work 1481 first published as draft-richer-oauth-dyn-reg-core-00 and draft- 1482 richer-oauth-dyn-reg-management-00. 1483 o Added the ability to use Software Statements. This built on work 1484 first published as draft-hunt-oauth-software-statement-00 and 1485 draft-hunt-oauth-client-association-00. 1486 o Created the IANA OAuth Registration Client Metadata registry for 1487 registering Client Metadata values. 1488 o Defined Client Instance term and stated that multiple instances 1489 can use the same client identifier value under certain 1490 circumstances. 1491 o Rewrote the introduction. 1492 o Rewrote the Use Cases appendix. 1494 -14 1496 o Added software_id and software_version metadata fields 1497 o Added direct references to RFC6750 errors in read/update/delete 1498 methods 1500 -13 1502 o Fixed broken example text in registration request and in delete 1503 request 1504 o Added security discussion of separating clients of different grant 1505 types 1506 o Fixed error reference to point to RFC6750 instead of RFC6749 1507 o Clarified that servers must respond to all requests to 1508 configuration endpoint, even if it's just an error code 1509 o Lowercased all Terms to conform to style used in RFC6750 1511 -12 1513 o Improved definition of Initial Access Token 1514 o Changed developer registration scenario to have the Initial Access 1515 Token gotten through a normal OAuth 2.0 flow 1516 o Moved non-normative client lifecycle examples to appendix 1517 o Marked differentiating between auth servers as out of scope 1518 o Added protocol flow diagram 1519 o Added credential rotation discussion 1520 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1521 Resource 1522 o Cleaned up several pieces of text 1524 -11 1526 o Added localized text to registration request and response 1527 examples. 1528 o Removed "client_secret_jwt" and "private_key_jwt". 1529 o Clarified "tos_uri" and "policy_uri" definitions. 1530 o Added the OAuth Token Endpoint Authentication Methods registry for 1531 registering "token_endpoint_auth_method" metadata values. 1532 o Removed uses of non-ASCII characters, per RFC formatting rules. 1533 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1534 to "client_id_issued_at" for greater clarity. 1535 o Added explanatory text for different credentials (Initial Access 1536 Token, Registration Access Token, Client Credentials) and what 1537 they're used for. 1538 o Added Client Lifecycle discussion and examples. 1539 o Defined Initial Access Token in Terminology section. 1541 -10 1543 o Added language to point out that scope values are service-specific 1544 o Clarified normative language around client metadata 1545 o Added extensibility to token_endpoint_auth_method using absolute 1546 URIs 1547 o Added security consideration about registering redirect URIs 1548 o Changed erroneous 403 responses to 401's with notes about token 1549 handling 1550 o Added example for initial registration credential 1552 -09 1554 o Added method of internationalization for Client Metadata values 1555 o Fixed SAML reference 1557 -08 1559 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1560 x509_encryption_uri into a single jwks_uri parameter 1561 o Renamed grant_type to grant_types since it's a plural value 1562 o Formalized name of "OAuth 2.0" throughout document 1563 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1564 grant types 1565 o Added response_types parameter and explanatory text on its use 1566 with and relationship to grant_types 1568 -07 1570 o Changed registration_access_url to registration_client_uri 1571 o Fixed missing text in 5.1 1572 o Added Pragma: no-cache to examples 1573 o Changed "no such client" error to 403 1574 o Renamed Client Registration Access Endpoint to Client 1575 Configuration Endpoint 1576 o Changed all the parameter names containing "_url" to instead use 1577 "_uri" 1578 o Updated example text for forming Client Configuration Endpoint URL 1580 -06 1582 o Removed secret_rotation as a client-initiated action, including 1583 removing client secret rotation endpoint and parameters. 1584 o Changed _links structure to single value registration_access_url. 1585 o Collapsed create/update/read responses into client info response. 1586 o Changed return code of create action to 201. 1587 o Added section to describe suggested generation and composition of 1588 Client Registration Access URL. 1589 o Added clarifying text to PUT and POST requests to specify JSON in 1590 the body. 1591 o Added Editor's Note to DELETE operation about its inclusion. 1593 o Added Editor's Note to registration_access_url about alternate 1594 syntax proposals. 1596 -05 1598 o changed redirect_uri and contact to lists instead of space 1599 delimited strings 1600 o removed operation parameter 1601 o added _links structure 1602 o made client update management more RESTful 1603 o split endpoint into three parts 1604 o changed input to JSON from form-encoded 1605 o added READ and DELETE operations 1606 o removed Requirements section 1607 o changed token_endpoint_auth_type back to 1608 token_endpoint_auth_method to match OIDC who changed to match us 1610 -04 1612 o removed default_acr, too undefined in the general OAuth2 case 1613 o removed default_max_auth_age, since there's no mechanism for 1614 supplying a non-default max_auth_age in OAuth2 1615 o clarified signing and encryption URLs 1616 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1617 match OIDC 1619 -03 1621 o added scope and grant_type claims 1622 o fixed various typos and changed wording for better clarity 1623 o endpoint now returns the full set of client information 1624 o operations on client_update allow for three actions on metadata: 1625 leave existing value, clear existing value, replace existing value 1626 with new value 1628 -02 1630 o Reorganized contributors and references 1631 o Moved OAuth references to RFC 1632 o Reorganized model/protocol sections for clarity 1633 o Changed terminology to "client register" instead of "client 1634 associate" 1635 o Specified that client_id must match across all subsequent requests 1636 o Fixed RFC2XML formatting, especially on lists 1638 -01 1640 o Merged UMA and OpenID Connect registrations into a single document 1641 o Changed to form-parameter inputs to endpoint 1642 o Removed pull-based registration 1644 -00 1646 o Imported original UMA draft specification 1648 Authors' Addresses 1650 Justin Richer 1651 The MITRE Corporation 1653 Email: jricher@mitre.org 1655 Michael B. Jones 1656 Microsoft 1658 Email: mbj@microsoft.com 1659 URI: http://self-issued.info/ 1661 John Bradley 1662 Ping Identity 1664 Email: ve7jtb@ve7jtb.com 1666 Maciej Machulak 1667 Newcastle University 1669 Email: m.p.machulak@ncl.ac.uk 1670 URI: http://ncl.ac.uk/ 1672 Phil Hunt 1673 Oracle Corporation 1675 Email: phil.hunt@yahoo.com