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