idnits 2.17.1 draft-ietf-oauth-dyn-reg-22.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 (January 15, 2015) is 3387 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: July 19, 2015 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 January 15, 2015 14 OAuth 2.0 Dynamic Client Registration Protocol 15 draft-ietf-oauth-dyn-reg-22 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 July 19, 2015. 47 Copyright Notice 49 Copyright (c) 2015 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 . . . . . . . . . . . . . 11 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. Responses . . . . . . . . . . . . . . . . . . . . . . . . 16 77 3.2.1. Client Information Response . . . . . . . . . . . . . 16 78 3.2.2. Client Registration Error Response . . . . . . . . . 18 79 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 80 4.1. OAuth Dynamic Registration Client Metadata Registry . . . 20 81 4.1.1. Registration Template . . . . . . . . . . . . . . . . 20 82 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 21 83 4.2. OAuth Token Endpoint Authentication Methods Registry . . 23 84 4.2.1. Registration Template . . . . . . . . . . . . . . . . 24 85 4.2.2. Initial Registry Contents . . . . . . . . . . . . . . 24 86 5. Security Considerations . . . . . . . . . . . . . . . . . . . 24 87 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 27 88 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 89 7.1. Normative References . . . . . . . . . . . . . . . . . . 28 90 7.2. Informative References . . . . . . . . . . . . . . . . . 29 91 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 29 92 A.1. Open versus Protected Dynamic Client Registration . . . . 29 93 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 30 94 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 client 213 developer. In other cases, a software statement will be issued by 214 a third party organization for use by the client developer. In 215 both cases, the trust relationship the authorization server has 216 with the issuer of the software statement is intended to be used 217 as an input to the evaluation of whether the registration request 218 is accepted. A software statement can be presented to an 219 authorization server as part of a client registration request. 221 1.3. Protocol Flow 223 +--------(A)- Initial Access Token (OPTIONAL) 224 | 225 | +----(B)- Software Statement (OPTIONAL) 226 | | 227 v v 228 +-----------+ +---------------+ 229 | |--(C)- Client Registration Request -->| Client | 230 | Client or | | Registration | 231 | Developer |<-(D)- Client Information Response ---| Endpoint | 232 | | or Client Error Response +---------------+ 233 +-----------+ 235 Figure 1: Abstract Dynamic Client Registration Flow 236 The abstract OAuth 2.0 client dynamic registration flow illustrated 237 in Figure 1 describes the interaction between the client or developer 238 and the endpoint defined in this specification. This figure does not 239 demonstrate error conditions. This flow includes the following 240 steps: 242 (A) Optionally, the client or developer is issued an initial access 243 token giving access to the client registration endpoint. The 244 method by which the initial access token is issued to the client 245 or developer is out of scope for this specification. 246 (B) Optionally, the client or developer is issued a software 247 statement for use with the client registration endpoint. The 248 method by which the software statement is issued to the client or 249 developer is out of scope for this specification. 250 (C) The client or developer calls the client registration endpoint 251 with the client's desired registration metadata, optionally 252 including the initial access token from (A) if one is required by 253 the authorization server. 254 (D) The authorization server registers the client and returns the 255 client's registered metadata, a client identifier that is unique 256 at the server, a set of client credentials such as a client secret 257 if applicable for this client, and possibly other values. 259 Examples of different configurations and usages are included in 260 Appendix A. 262 2. Client Metadata 264 Registered clients have a set of metadata values associated with 265 their client identifier at an authorization server, such as the list 266 of valid redirection URIs or a display name. 268 These client metadata values are used in two ways: 270 o as input values to registration requests, and 271 o as output values in registration responses. 273 The following client metadata fields are defined by this 274 specification. The implementation and use of all client metadata 275 fields is OPTIONAL, unless stated otherwise. 277 redirect_uris 278 Array of redirection URI values for use in redirect-based flows 279 such as the authorization code and implicit flows. As required by 280 Section 2 of OAuth 2.0 [RFC6749], clients using flows with 281 redirection MUST register their redirection URI values. 282 Authorization servers that support dynamic registration for 283 redirect-based flows MUST implement support for this metadata 284 value. 285 token_endpoint_auth_method 286 The requested authentication method for the token endpoint. 287 Values defined by this specification are: 289 * "none": The client is a public client as defined in OAuth 2.0 290 and does not have a client secret. 291 * "client_secret_post": The client uses the HTTP POST parameters 292 defined in OAuth 2.0 section 2.3.1. 293 * "client_secret_basic": the client uses HTTP Basic defined in 294 OAuth 2.0 section 2.3.1 296 Additional values can be defined via the IANA OAuth Token Endpoint 297 Authentication Methods Registry established in Section 4.2. 298 Absolute URIs can also be used as values for this parameter 299 without being registered. If unspecified or omitted, the default 300 is "client_secret_basic", denoting HTTP Basic Authentication 301 Scheme as specified in Section 2.3.1 of OAuth 2.0. 302 grant_types 303 Array of OAuth 2.0 grant types that the client may use. These 304 grant types are defined as follows: 306 * "authorization_code": The Authorization Code Grant described in 307 OAuth 2.0 Section 4.1 308 * "implicit": The Implicit Grant described in OAuth 2.0 309 Section 4.2 310 * "password": The Resource Owner Password Credentials Grant 311 described in OAuth 2.0 Section 4.3 312 * "client_credentials": The Client Credentials Grant described in 313 OAuth 2.0 Section 4.4 314 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 315 Section 6. 316 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 317 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 318 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 319 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 320 [OAuth.SAML2]. 322 If the token endpoint is used in the grant type, the value of this 323 parameter MUST be the same as the value of the "grant_type" 324 parameter passed to the token endpoint defined in the grant type 325 definition. Authorization servers MAY allow for other values as 326 defined in the grant type extension process described in OAuth 2.0 327 Section 2.5. If omitted, the default behavior is that the client 328 will use only the "authorization_code" Grant Type. 329 response_types 330 Array of the OAuth 2.0 response types that the client can use. 331 These response types are defined as follows: 333 * "code": The authorization code response described in OAuth 2.0 334 Section 4.1. 335 * "token": The implicit response described in OAuth 2.0 336 Section 4.2. 338 If the authorization endpoint is used by the grant type, the value 339 of this parameter MUST be the same as the value of the 340 "response_type" parameter passed to the authorization endpoint 341 defined in the grant type definition. Authorization servers MAY 342 allow for other values as defined in the grant type extension 343 process is described in OAuth 2.0 Section 2.5. If omitted, the 344 default is that the client will use only the "code" response type. 345 client_name 346 Human-readable name of the client to be presented to the user 347 during authorization. If omitted, the authorization server MAY 348 display the raw "client_id" value to the user instead. It is 349 RECOMMENDED that clients always send this field. The value of 350 this field MAY be internationalized, as described in Section 2.2. 351 client_uri 352 URL of a web page providing information about the client. If 353 present, the server SHOULD display this URL to the end user in a 354 clickable fashion. It is RECOMMENDED that clients always send 355 this field. The value of this field MUST point to a valid web 356 page. The value of this field MAY be internationalized, as 357 described in Section 2.2. 358 logo_uri 359 URL that references a logo for the client. If present, the server 360 SHOULD display this image to the end user during approval. The 361 value of this field MUST point to a valid image file. The value 362 of this field MAY be internationalized, as described in 363 Section 2.2. 364 scope 365 Space separated list of scope values (as described in Section 3.3 366 of OAuth 2.0 [RFC6749]) that the client can use when requesting 367 access tokens. The semantics of values in this list is service 368 specific. If omitted, an authorization server MAY register a 369 client with a default set of scopes. 370 contacts 371 Array of strings representing ways to contact people responsible 372 for this client, typically email addresses. The authorization 373 server MAY make these addresses available to end users for support 374 requests for the client. 375 tos_uri 376 URL that points to a human-readable terms of service document for 377 the client that describes a contractual relationship between the 378 end-user and the client that the end-user accepts when authorizing 379 the client. The authorization server SHOULD display this URL to 380 the end-user if it is provided. The value of this field MUST 381 point to a valid web page. The value of this field MAY be 382 internationalized, as described in Section 2.2. 383 policy_uri 384 URL that points to a human-readable privacy policy document that 385 describes how the deployment organization collects, uses, retains, 386 and discloses personal data. The authorization server SHOULD 387 display this URL to the end-user if it is provided. The value of 388 this field MUST point to a valid web page. The value of this 389 field MAY be internationalized, as described in Section 2.2. 390 jwks_uri 391 URL referencing the client's JSON Web Key Set [JWK] document, 392 which contains the client's public keys. The value of this field 393 MUST point to a valid JWK Set document. These keys can be used by 394 higher level protocols that use signing or encryption. For 395 instance, these keys might be used by some applications for 396 validating signed requests made to the token endpoint when using 397 JWTs for client authentication [OAuth.JWT]. Use of this parameter 398 is preferred over the "jwks" parameter, as it allows for easier 399 key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both 400 be present in the same request or response. 401 jwks 402 Client's JSON Web Key Set [JWK] document value, which contains the 403 client's public keys. The value of this field MUST be a JSON 404 object containing a valid JWK Set. These keys can be used by 405 higher level protocols that use signing or encryption. This 406 parameter is intended to be used by clients that cannot use the 407 "jwks_uri" parameter, such as native clients that cannot host 408 public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both 409 be present in the same request or response. 410 software_id 411 Identifier for the software that comprises a client. Unlike 412 "client_id", which is issued by the authorization server and may 413 vary between instances, the "software_id" is asserted by the 414 client software on behalf of the software developer and is 415 intended to be shared among all instances of the client software. 416 The identifier SHOULD NOT change when software version changes or 417 when a new installation occurs. 418 software_version 419 Version identifier for the software that comprises a client. The 420 value of this field is a string that is intended to be compared 421 using string equality matching. The value of the 422 "software_version" SHOULD change on any update to the client 423 software. 425 Extensions and profiles of this specification MAY expand this list. 426 The authorization server MUST ignore any client metadata values sent 427 by the client that it does not understand. 429 Client metadata values can either be communicated directly in the 430 body of a registration request, as described in Section 3.1, or 431 included as claims in a software statement, as described in 432 Section 2.3, or a mixture of both. If the same client metadata name 433 is present in both locations and the software statement is trusted by 434 the authorization server, the value of a claim in the software 435 statement MUST take precedence. 437 2.1. Relationship between Grant Types and Response Types 439 The "grant_types" and "response_types" values described above are 440 partially orthogonal, as they refer to arguments passed to different 441 endpoints in the OAuth protocol. However, they are related in that 442 the "grant_types" available to a client influence the 443 "response_types" that the client is allowed to use, and vice versa. 444 For instance, a "grant_types" value that includes 445 "authorization_code" implies a "response_types" value that includes 446 "code", as both values are defined as part of the OAuth 2.0 447 authorization code grant. As such, a server supporting these fields 448 SHOULD take steps to ensure that a client cannot register itself into 449 an inconsistent state, for example by returning an 450 "invalid_client_metadata" error response to an inconsistent 451 registration request. 453 The correlation between the two fields is listed in the table below. 455 +-----------------------------------------------+-------------------+ 456 | grant_types value includes: | response_types | 457 | | value includes: | 458 +-----------------------------------------------+-------------------+ 459 | authorization_code | code | 460 | implicit | token | 461 | password | (none) | 462 | client_credentials | (none) | 463 | refresh_token | (none) | 464 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 465 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 466 +-----------------------------------------------+-------------------+ 468 Extensions and profiles of this document that introduce new values to 469 either the "grant_types" or "response_types" parameter MUST document 470 all correspondences between these two parameter types. 472 2.2. Human Readable Client Metadata 474 Human-readable client metadata values and client metadata values that 475 reference human-readable values MAY be represented in multiple 476 languages and scripts. For example, the values of fields such as 477 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 478 might have multiple locale-specific values in some client 479 registrations to facilitate use in different locations. 481 To specify the languages and scripts, BCP47 [RFC5646] language tags 482 are added to client metadata member names, delimited by a # 483 character. Since JSON [RFC7159] member names are case sensitive, it 484 is RECOMMENDED that language tag values used in Claim Names be 485 spelled using the character case with which they are registered in 486 the IANA Language Subtag Registry [IANA.Language]. In particular, 487 normally language names are spelled with lowercase characters, region 488 names are spelled with uppercase characters, and languages are 489 spelled with mixed case characters. However, since BCP47 language 490 tag values are case insensitive, implementations SHOULD interpret the 491 language tag values supplied in a case insensitive manner. Per the 492 recommendations in BCP47, language tag values used in metadata member 493 names should only be as specific as necessary. For instance, using 494 "fr" might be sufficient in many contexts, rather than "fr-CA" or 495 "fr-FR". 497 For example, a client could represent its name in English as 498 ""client_name#en": "My Client"" and its name in Japanese as 499 ""client_name#ja-Jpan-JP": 500 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 501 registration request. The authorization server MAY display any or 502 all of these names to the resource owner during the authorization 503 step, choosing which name to display based on system configuration, 504 user preferences or other factors. 506 If any human-readable field is sent without a language tag, parties 507 using it MUST NOT make any assumptions about the language, character 508 set, or script of the string value, and the string value MUST be used 509 as-is wherever it is presented in a user interface. To facilitate 510 interoperability, it is RECOMMENDED that clients and servers use a 511 human-readable field without any language tags in addition to any 512 language-specific fields, and it is RECOMMENDED that any human- 513 readable fields sent without language tags contain values suitable 514 for display on a wide variety of systems. 516 Implementer's Note: Many JSON libraries make it possible to reference 517 members of a JSON object as members of an object construct in the 518 native programming environment of the library. However, while the 519 "#" character is a valid character inside of a JSON object's member 520 names, it is not a valid character for use in an object member name 521 in many programming environments. Therefore, implementations will 522 need to use alternative access forms for these claims. For instance, 523 in JavaScript, if one parses the JSON as follows, "var j = 524 JSON.parse(json);", then as a workaround the member "client_name#en- 525 us" can be accessed using the JavaScript syntax "j["client_name#en- 526 us"]". 528 2.3. Software Statement 530 A software statement is a JSON Web Token (JWT) [JWT] that asserts 531 metadata values about the client software as a bundle. A set of 532 claims that can be used in a software statement are defined in 533 Section 2. When presented to the authorization server as part of a 534 client registration request, the software statement MUST be digitally 535 signed or MACed using JWS [JWS] and MUST contain an "iss" (issuer) 536 claim denoting the party attesting to the claims in the software 537 statement. It is RECOMMENDED that software statements be digitally 538 signed using the "RS256" signature algorithm, although particular 539 applications MAY specify the use of different algorithms. It is 540 RECOMMENDED that software statements contain the "software_id" claim 541 to allow authorization servers to correlate different instances of 542 software using the same software statement. 544 For example, a software statement could contain the following claims: 546 { 547 "software_id": "4NRB1-0XZABZI9E6-5SM3R", 548 "client_name": "Example Statement-based Client", 549 "client_uri": "https://client.example.net/" 550 } 552 The following non-normative example JWT includes these claims and has 553 been asymmetrically signed using RS256: 555 Line breaks are for display purposes only 557 eyJhbGciOiJSUzI1NiJ9. 558 eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll 559 bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs 560 aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ. 561 GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa 562 zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0 563 5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY 564 fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk 565 U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf 566 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 and registering a JWK set by value (with line wraps 670 within values for display purposes only): 672 POST /register HTTP/1.1 673 Content-Type: application/json 674 Accept: application/json 675 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":[{ 687 "e": "AQAB", 688 "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG 689 HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk 690 lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p 691 RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe 692 2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve 693 qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ", 694 "kty": "RSA" 695 }]}, 696 "example_extension_parameter": "example_value" 697 } 699 3.1.1. Client Registration Request Using a Software Statement 701 In addition to JSON elements, client metadata values MAY also be 702 provided in a software statement, as described in Section 2.3. The 703 authorization server MAY ignore the software statement if it does not 704 support this feature. If the server supports software statements, 705 client metadata values conveyed in the software statement MUST take 706 precedence over those conveyed using plain JSON elements. 708 Software statements are included in the requesting JSON object using 709 this OPTIONAL member: 711 software_statement 712 A software statement containing client metadata values about the 713 client software as claims. 715 In the following example, some registration parameters are conveyed 716 as claims in a software statement from the example in the Section 2.3 717 section, while some values specific to the client instance are 718 conveyed as regular parameters (with line wraps within values for 719 display purposes only): 721 POST /register HTTP/1.1 722 Content-Type: application/json 723 Accept: application/json 724 Host: server.example.com 726 { 727 "redirect_uris":[ 728 "https://client.example.org/callback", 729 "https://client.example.org/callback2" 730 ], 731 "software_statement":"eyJhbGciOiJSUzI1NiJ9. 732 eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll 733 bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs 734 aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ. 735 GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa 736 zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0 737 5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY 738 fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk 739 U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf 740 IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA", 741 "scope":"read write", 742 "example_extension_parameter":"example_value" 743 } 745 3.2. Responses 747 Upon a successful registration request, the authorization server 748 returns a client identifier for the client. The server responds with 749 an HTTP 201 Created code and a body of type "application/json" with 750 content as described in Section 3.2.1. 752 Upon an unsuccessful registration request, the authorization server 753 responds with an error, as described in Section 3.2.2. 755 3.2.1. Client Information Response 757 The response contains the client identifier as well as the client 758 secret, if the client is a confidential client. The response MAY 759 contain additional fields as specified by extensions to this 760 specification. 762 client_id 763 REQUIRED. OAuth 2.0 client identifier. It SHOULD NOT be 764 currently valid for any other registered client, though an 765 authorization server MAY issue the same client identifier to 766 multiple instances of a registered client at its discretion. 767 client_secret 768 OPTIONAL. OAuth 2.0 client secret. If issued, this MUST be 769 unique for each "client_id" and SHOULD be unique for multiple 770 instances of a client using the same "client_id". This value is 771 used by confidential clients to authenticate to the token endpoint 772 as described in OAuth 2.0 [RFC6749] Section 2.3.1. 773 client_id_issued_at 774 OPTIONAL. Time at which the client identifier was issued. The 775 time is represented as the number of seconds from 776 1970-01-01T0:0:0Z as measured in UTC until the date/time of 777 issuance. 778 client_secret_expires_at 779 REQUIRED if "client_secret" is issued. Time at which the client 780 secret will expire or 0 if it will not expire. The time is 781 represented as the number of seconds from 1970-01-01T0:0:0Z as 782 measured in UTC until the date/time of expiration. 784 Additionally, the authorization server MUST return all registered 785 metadata about this client, including any fields provisioned by the 786 authorization server itself. The authorization server MAY reject or 787 replace any of the client's requested metadata values submitted 788 during the registration and substitute them with suitable values. 790 The response is an "application/json" document with all parameters as 791 top-level members of a JSON object [RFC7159]. 793 If a software statement was used as part of the registration, its 794 value MUST be returned unmodified in the response along with other 795 metadata using the "software_statement" member name. Client metadata 796 elements used from the software statement MUST also be returned 797 directly as top-level client metadata values in the registration 798 response (possibly with different values, since the values requested 799 and the values used may differ). 801 Following is a non-normative example response: 803 HTTP/1.1 201 Created 804 Content-Type: application/json 805 Cache-Control: no-store 806 Pragma: no-cache 808 { 809 "client_id":"s6BhdRkqt3", 810 "client_secret": "cf136dc3c1fc93f31185e5885805d", 811 "client_id_issued_at":2893256800, 812 "client_secret_expires_at":2893276800, 813 "redirect_uris":[ 814 "https://client.example.org/callback", 815 "https://client.example.org/callback2"], 816 "grant_types": ["authorization_code", "refresh_token"], 817 "client_name":"My Example Client", 818 "client_name#ja-Jpan-JP": 819 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 820 "token_endpoint_auth_method":"client_secret_basic", 821 "logo_uri":"https://client.example.org/logo.png", 822 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 823 "example_extension_parameter": "example_value" 824 } 826 3.2.2. Client Registration Error Response 828 When an OAuth 2.0 error condition occurs, such as the client 829 presenting an invalid initial access token, the authorization server 830 returns an error response appropriate to the OAuth 2.0 token type. 832 When a registration error condition occurs, the authorization server 833 returns an HTTP 400 status code (unless otherwise specified) with 834 content type "application/json" consisting of a JSON object [RFC7159] 835 describing the error in the response body. 837 Two members are defined for inclusion in the JSON object: 839 error 840 REQUIRED. Single ASCII error code string. 841 error_description 842 OPTIONAL. Human-readable ASCII text description of the error used 843 for debugging. 845 Other members MAY also be included, and if not understood, MUST be 846 ignored. 848 This specification defines the following error codes: 850 invalid_redirect_uri 851 The value of one or more redirection URIs is invalid. 852 invalid_client_metadata 853 The value of one of the client metadata fields is invalid and the 854 server has rejected this request. Note that an authorization 855 server MAY choose to substitute a valid value for any requested 856 parameter of a client's metadata. 857 invalid_software_statement 858 The software statement presented is invalid. 859 unapproved_software_statement 860 The software statement presented is not approved for use by this 861 authorization server. 863 Following is a non-normative example of an error response resulting 864 from a redirection URI that has been blacklisted by the authorization 865 server (with line wraps within values for display purposes only): 867 HTTP/1.1 400 Bad Request 868 Content-Type: application/json 869 Cache-Control: no-store 870 Pragma: no-cache 872 { 873 "error": "invalid_redirect_uri", 874 "error_description": "The redirection URI 875 http://sketchy.example.com is not allowed by this server." 876 } 878 Following is a non-normative example of an error response resulting 879 from an inconsistent combination of "response_types" and 880 "grant_types" values (with line wraps within values for display 881 purposes only): 883 HTTP/1.1 400 Bad Request 884 Content-Type: application/json 885 Cache-Control: no-store 886 Pragma: no-cache 888 { 889 "error": "invalid_client_metadata", 890 "error_description": "The grant type 'authorization_code' must be 891 registered along with the response type 'code' but found only 892 'implicit' instead." 893 } 895 4. IANA Considerations 897 4.1. OAuth Dynamic Registration Client Metadata Registry 899 This specification establishes the OAuth Dynamic Registration Client 900 Metadata registry. 902 OAuth registration client metadata values are registered with a 903 Specification Required ([RFC5226]) after a two-week review period on 904 the oauth-ext-review@ietf.org mailing list, on the advice of one or 905 more Designated Experts. However, to allow for the allocation of 906 values prior to publication, the Designated Expert(s) may approve 907 registration once they are satisfied that such a specification will 908 be published. 910 Registration requests must be sent to the oauth-ext-review@ietf.org 911 mailing list for review and comment, with an appropriate subject 912 (e.g., "Request to register OAuth Dynamic Registration Client 913 Metadata name: example"). 915 Within the review period, the Designated Expert(s) will either 916 approve or deny the registration request, communicating this decision 917 to the review list and IANA. Denials should include an explanation 918 and, if applicable, suggestions as to how to make the request 919 successful. 921 IANA must only accept registry updates from the Designated Expert(s) 922 and should direct all requests for registration to the review mailing 923 list. 925 4.1.1. Registration Template 927 Client Metadata Name: 928 The name requested (e.g., "example"). This name is case 929 sensitive. Names that match other registered names in a case 930 insensitive manner SHOULD NOT be accepted. 932 Client Metadata Description: 933 Brief description of the metadata value (e.g., "Example 934 description"). 936 Change controller: 937 For Standards Track RFCs, state "IESG". For others, give the name 938 of the responsible party. Other details (e.g., postal address, 939 email address, home page URI) may also be included. 941 Specification document(s): 943 Reference to the document(s) that specify the token endpoint 944 authorization method, preferably including a URI that can be used 945 to retrieve a copy of the document(s). An indication of the 946 relevant sections may also be included but is not required. 948 4.1.2. Initial Registry Contents 950 The initial contents of the OAuth Dynamic Registration Client 951 Metadata registry are: 953 o Client Metadata Name: "redirect_uris" 954 o Client Metadata Description: Array of redirection URIs for use in 955 redirect-based flows 956 o Change controller: IESG 957 o Specification document(s): [[ this document ]] 959 o Client Metadata Name: "token_endpoint_auth_method" 960 o Client Metadata Description: Requested authentication method for 961 the token endpoint 962 o Change controller: IESG 963 o Specification document(s): [[ this document ]] 965 o Client Metadata Name: "grant_types" 966 o Client Metadata Description: Array of OAuth 2.0 grant types that 967 the client may use 968 o Change controller: IESG 969 o Specification document(s): [[ this document ]] 971 o Client Metadata Name: "response_types" 972 o Client Metadata Description: Array of the OAuth 2.0 response types 973 that the client may use 974 o Change controller: IESG 975 o Specification document(s): [[ this document ]] 977 o Client Metadata Name: "client_name" 978 o Client Metadata Description: Human-readable name of the client to 979 be presented to the user 980 o Change Controller: IESG 981 o Specification Document(s): [[ this document ]] 983 o Client Metadata Name: "client_uri" 984 o Client Metadata Description: URL of a Web page providing 985 information about the client 986 o Change Controller: IESG 987 o Specification Document(s): [[ this document ]] 989 o Client Metadata Name: "logo_uri" 990 o Client Metadata Description: URL that references a logo for the 991 client 992 o Change Controller: IESG 993 o Specification Document(s): [[ this document ]] 995 o Client Metadata Name: "scope" 996 o Client Metadata Description: Space separated list of scope values 997 o Change Controller: IESG 998 o Specification Document(s): [[ this document ]] 1000 o Client Metadata Name: "contacts" 1001 o Client Metadata Description: Array of strings representing ways to 1002 contact people responsible for this client, typically email 1003 addresses 1004 o Change Controller: IESG 1005 o Specification document(s): [[ this document ]] 1007 o Client Metadata Name: "tos_uri" 1008 o Client Metadata Description: URL that points to a human-readable 1009 Terms of Service document for the client 1010 o Change Controller: IESG 1011 o Specification Document(s): [[ this document ]] 1013 o Client Metadata Name: "policy_uri" 1014 o Client Metadata Description: URL that points to a human-readable 1015 Policy document for the client 1016 o Change Controller: IESG 1017 o Specification Document(s): [[ this document ]] 1019 o Client Metadata Name: "jwks_uri" 1020 o Client Metadata Description: URL referencing the client's JSON Web 1021 Key Set [JWK] document representing the client's public keys 1022 o Change Controller: IESG 1023 o Specification Document(s): [[ this document ]] 1025 o Client Metadata Name: "jwks" 1026 o Client Metadata Description: Client's JSON Web Key Set [JWK] 1027 document representing the client's public keys 1028 o Change Controller: IESG 1029 o Specification Document(s): [[ this document ]] 1031 o Client Metadata Name: "software_id" 1032 o Client Metadata Description: Identifier for the software that 1033 comprises a client 1034 o Change Controller: IESG 1035 o Specification Document(s): [[ this document ]] 1037 o Client Metadata Name: "software_version" 1038 o Client Metadata Description: Version identifier for the software 1039 that comprises a client 1040 o Change Controller: IESG 1041 o Specification Document(s): [[ this document ]] 1043 o Client Metadata Name: "client_id" 1044 o Client Metadata Description: Client identifier 1045 o Change Controller: IESG 1046 o Specification Document(s): [[ this document ]] 1048 o Client Metadata Name: "client_secret" 1049 o Client Metadata Description: Client secret 1050 o Change Controller: IESG 1051 o Specification Document(s): [[ this document ]] 1053 o Client Metadata Name: "client_id_issued_at" 1054 o Client Metadata Description: Time at which the client identifier 1055 was issued 1056 o Change Controller: IESG 1057 o Specification Document(s): [[ this document ]] 1059 o Client Metadata Name: "client_secret_expires_at" 1060 o Client Metadata Description: Time at which the client secret will 1061 expire 1062 o Change Controller: IESG 1063 o Specification Document(s): [[ this document ]] 1065 4.2. OAuth Token Endpoint Authentication Methods Registry 1067 This specification establishes the OAuth Token Endpoint 1068 Authentication Methods registry. 1070 Additional values for use as "token_endpoint_auth_method" metadata 1071 values are registered with a Specification Required ([RFC5226]) after 1072 a two-week review period on the oauth-ext-review@ietf.org mailing 1073 list, on the advice of one or more Designated Experts. However, to 1074 allow for the allocation of values prior to publication, the 1075 Designated Expert(s) may approve registration once they are satisfied 1076 that such a specification will be published. 1078 Registration requests must be sent to the oauth-ext-review@ietf.org 1079 mailing list for review and comment, with an appropriate subject 1080 (e.g., "Request to register token_endpoint_auth_method value: 1081 example"). 1083 Within the review period, the Designated Expert(s) will either 1084 approve or deny the registration request, communicating this decision 1085 to the review list and IANA. Denials should include an explanation 1086 and, if applicable, suggestions as to how to make the request 1087 successful. 1089 IANA must only accept registry updates from the Designated Expert(s) 1090 and should direct all requests for registration to the review mailing 1091 list. 1093 4.2.1. Registration Template 1095 Token Endpoint Authorization Method Name: 1096 The name requested (e.g., "example"). This name is case 1097 sensitive. Names that match other registered names in a case 1098 insensitive manner SHOULD NOT be accepted. 1100 Change controller: 1101 For Standards Track RFCs, state "IESG". For others, give the name 1102 of the responsible party. Other details (e.g., postal address, 1103 email address, home page URI) may also be included. 1105 Specification document(s): 1106 Reference to the document(s) that specify the token endpoint 1107 authorization method, preferably including a URI that can be used 1108 to retrieve a copy of the document(s). An indication of the 1109 relevant sections may also be included but is not required. 1111 4.2.2. Initial Registry Contents 1113 The initial contents of the OAuth Token Endpoint Authentication 1114 Methods registry are: 1116 o Token Endpoint Authorization Method Name: "none" 1117 o Change controller: IESG 1118 o Specification document(s): [[ this document ]] 1120 o Token Endpoint Authorization Method Name: "client_secret_post" 1121 o Change controller: IESG 1122 o Specification document(s): [[ this document ]] 1124 o Token Endpoint Authorization Method Name: "client_secret_basic" 1125 o Change controller: IESG 1126 o Specification document(s): [[ this document ]] 1128 5. Security Considerations 1130 Since requests to the client registration endpoint result in the 1131 transmission of clear-text credentials (in the HTTP request and 1132 response), the authorization server MUST require the use of a 1133 transport-layer security mechanism when sending requests to the 1134 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1135 [RFC5246] and MAY support additional transport-layer mechanisms 1136 meeting its security requirements. When using TLS, the client MUST 1137 perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. 1138 Implementation security considerations can be found in 1139 Recommendations for Secure Use of TLS and DTLS [TLS.BCP]. 1141 For clients that use redirect-based grant types such as 1142 "authorization_code" and "implicit", authorization servers MUST 1143 require clients to register their redirection URI values. This can 1144 help mitigate attacks where rogue actors inject and impersonate a 1145 validly registered client and intercept its authorization code or 1146 tokens through an invalid redirection URI or open redirector. 1147 Additionally, in order to prevent hijacking of the return values of 1148 the redirection, registered redirection URI values MUST be one of: 1150 o A remote web site protected by TLS (e.g., 1151 https://client.example.com/oauth_redirect) 1152 o A web site hosted on the local machine using an HTTP URI (e.g., 1153 http://localhost:8080/oauth_redirect) 1154 o A non-HTTP application-specific URL that is available only to the 1155 client application (e.g., exampleapp://oauth_redirect) 1157 Public clients MAY register with an authorization server using this 1158 protocol, if the authorization server's policy allows them. Public 1159 clients use a "none" value for the "token_endpoint_auth_method" 1160 metadata field and are generally used with the "implicit" grant type. 1161 Often these clients will be short-lived in-browser applications 1162 requesting access to a user's resources and access is tied to a 1163 user's active session at the authorization server. Since such 1164 clients often do not have long-term storage, it's possible that such 1165 clients would need to re-register every time the browser application 1166 is loaded. Additionally, such clients may not have ample opportunity 1167 to unregister themselves using the delete action before the browser 1168 closes. To avoid the resulting proliferation of dead client 1169 identifiers, an authorization server MAY decide to expire 1170 registrations for existing clients meeting certain criteria after a 1171 period of time has elapsed. 1173 Since different OAuth 2.0 grant types have different security and 1174 usage parameters, an authorization server MAY require separate 1175 registrations for a piece of software to support multiple grant 1176 types. For instance, an authorization server might require that all 1177 clients using the "authorization_code" grant type make use of a 1178 client secret for the "token_endpoint_auth_method", but any clients 1179 using the "implicit" grant type do not use any authentication at the 1180 token endpoint. In such a situation, a server MAY disallow clients 1181 from registering for both the "authorization_code" and "implicit" 1182 grant types simultaneously. Similarly, the "authorization_code" 1183 grant type is used to represent access on behalf of an end user, but 1184 the "client_credentials" grant type represents access on behalf of 1185 the client itself. For security reasons, an authorization server 1186 could require that different scopes be used for these different use 1187 cases, and as a consequence it MAY disallow these two grant types 1188 from being registered together by the same client. In all of these 1189 cases, the authorization server would respond with an 1190 "invalid_client_metadata" error response. 1192 Unless used as a claim in a software statement, the authorization 1193 server MUST treat all client metadata as self-asserted. For 1194 instance, a rogue client might use the name and logo of a legitimate 1195 client that it is trying to impersonate. Additionally, a rogue 1196 client might try to use the software identifier or software version 1197 of a legitimate client to attempt to associate itself on the 1198 authorization server with instances of the legitimate client. To 1199 counteract this, an authorization server needs to take steps to 1200 mitigate this risk by looking at the entire registration request and 1201 client configuration. For instance, an authorization server could 1202 issue a warning if the domain/site of the logo doesn't match the 1203 domain/site of redirection URIs. An authorization server could also 1204 refuse registration requests from a known software identifier that is 1205 requesting different redirection URIs or a different client homepage 1206 URI. An authorization server can also present warning messages to 1207 end users about dynamically registered clients in all cases, 1208 especially if such clients have been recently registered or have not 1209 been trusted by any users at the authorization server before. 1211 In a situation where the authorization server is supporting open 1212 client registration, it must be extremely careful with any URL 1213 provided by the client that will be displayed to the user (e.g. 1214 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1215 instance, a rogue client could specify a registration request with a 1216 reference to a drive-by download in the "policy_uri". The 1217 authorization server SHOULD check to see if the "logo_uri", 1218 "tos_uri", "client_uri", and "policy_uri" have the same host and 1219 scheme as the those defined in the array of "redirect_uris" and that 1220 all of these URIs resolve to valid web pages. 1222 Clients MAY use both the direct JSON object and the JWT-encoded 1223 software statement to present client metadata to the authorization 1224 server as part of the registration request. A software statement is 1225 cryptographically protected and represents claims made by the issuer 1226 of the statement, while the JSON object represents the self-asserted 1227 claims made by the client or developer directly. If the software 1228 statement is valid and signed by an acceptable authority (such as the 1229 software API publisher), the values of client metadata within the 1230 software statement MUST take precedence over those metadata values 1231 presented in the plain JSON object, which could have been modified en 1232 route. 1234 The software statement is an item that is self-asserted by the 1235 client, even though its contents have been digitally signed or MACed 1236 by the issuer of the software statement. As such, presentation of 1237 the software statement is not sufficient in most cases to fully 1238 identity a piece of client software. An initial access token, in 1239 contrast, does not necessarily contain information about a particular 1240 piece of client software but instead represents authorization to use 1241 the registration endpoint. An authorization server MUST consider the 1242 full registration request, including the software statement, initial 1243 access token, and JSON client metadata values, when deciding whether 1244 to honor a given registration request. 1246 If an authorization server receives a registration request for a 1247 client that uses the same "software_id" and "software_version" values 1248 as another client, the server should treat the new registration as 1249 being suspect. It is possible that the new client is trying to 1250 impersonate the existing client. 1252 Since a client identifier is a public value that can be used to 1253 impersonate a client at the authorization endpoint, an authorization 1254 server that decides to issue the same client identifier to multiple 1255 instances of a registered client needs to be very particular about 1256 the circumstances under which this occurs. For instance, the 1257 authorization server can limit a given client identifier to clients 1258 using the same redirect-based flow and the same redirection URIs. An 1259 authorization server SHOULD NOT issue the same client secret to 1260 multiple instances of a registered client, even if they are issued 1261 the same client identifier, or else the client secret could be 1262 leaked, allowing malicious impostors to impersonate a confidential 1263 client. 1265 6. Privacy Considerations 1267 As the protocol described in this specification deals almost 1268 exclusively with information about software and not about people, 1269 there are very few privacy concerns for its use. The notable 1270 exception is the "contacts" field as defined in Client Metadata 1271 (Section 2), which contains contact information for the developers or 1272 other parties responsible for the client software. These values are 1273 intended to be displayed to end users and will be available to the 1274 administrators of the authorization server. As such, the developer 1275 may wish to provide an email address or other contact information 1276 expressly dedicated to the purpose of supporting the client instead 1277 of using their personal or professional addresses. Alternatively, 1278 the developer may wish to provide a collective email address for the 1279 client to allow for continuing contact and support of the client 1280 software after the developer moves on and someone else takes over 1281 that responsibility. 1283 7. References 1285 7.1. Normative References 1287 [IANA.Language] 1288 Internet Assigned Numbers Authority (IANA), "Language 1289 Subtag Registry", 2005. 1291 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 1292 key (work in progress), July 2014. 1294 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1295 Signature (JWS)", draft-ietf-jose-json-web-signature (work 1296 in progress), July 2014. 1298 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1299 (JWT)", draft-ietf-oauth-json-web-token (work in 1300 progress), July 2014. 1302 [OAuth.JWT] 1303 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1304 (JWT) Profile for OAuth 2.0 Client Authentication and 1305 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 1306 in progress), July 2014. 1308 [OAuth.SAML2] 1309 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1310 Profile for OAuth 2.0 Client Authentication and 1311 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 1312 in progress), July 2014. 1314 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1315 Requirement Levels", BCP 14, RFC 2119, March 1997. 1317 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1318 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1319 May 2008. 1321 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1322 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1324 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1325 Languages", BCP 47, RFC 5646, September 2009. 1327 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1328 Verification of Domain-Based Application Service Identity 1329 within Internet Public Key Infrastructure Using X.509 1330 (PKIX) Certificates in the Context of Transport Layer 1331 Security (TLS)", RFC 6125, March 2011. 1333 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1334 6749, October 2012. 1336 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1337 Framework: Bearer Token Usage", RFC 6750, October 2012. 1339 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1340 Interchange Format", RFC 7159, March 2014. 1342 7.2. Informative References 1344 [I-D.hardjono-oauth-umacore] 1345 Hardjono, T., "User-Managed Access (UMA) Profile of OAuth 1346 2.0", draft-hardjono-oauth-umacore-10 (work in progress), 1347 July 2014. 1349 [OAuth.Registration.Management] 1350 Richer, J., Jones, M., Bradley, J., and M. Machulak, 1351 "OAuth 2.0 Dynamic Client Registration Management 1352 Protocol", draft-ietf-oauth-dyn-reg-management (work in 1353 progress), August 2014. 1355 [OpenID.Registration] 1356 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 1357 Dynamic Client Registration 1.0", February 2014. 1359 [TLS.BCP] Sheffer, Y., Holz, R., and P. Saint-Andre, 1360 "Recommendations for Secure Use of TLS and DTLS", November 1361 2014. 1363 Appendix A. Use Cases 1365 This appendix describes different ways that this specification can be 1366 utilized, including describing some of the choices that may need to 1367 be made. Some of the choices are independent and can be used in 1368 combination, whereas some of the choices are interrelated. 1370 A.1. Open versus Protected Dynamic Client Registration 1371 A.1.1. Open Dynamic Client Registration 1373 Authorization servers that support open registration allow 1374 registrations to be made with no initial access token. This allows 1375 all client software to register with the authorization server. 1377 A.1.2. Protected Dynamic Client Registration 1379 Authorization servers that support protected registration require 1380 that an initial access token be used when making registration 1381 requests. While the method by which a client or developer receives 1382 this initial access token and the method by which the authorization 1383 server validates this initial access token are out of scope for this 1384 specification, a common approach is for the developer to use a manual 1385 pre-registration portal at the authorization server that issues an 1386 initial access token to the developer. 1388 A.2. Registration Without or With Software Statements 1390 A.2.1. Registration Without a Software Statement 1392 When a software statement is not used in the registration request, 1393 the authorization server must be willing to use client metadata 1394 values without them being digitally signed or MACed (and thereby 1395 attested to) by any authority. (Note that this choice is independent 1396 of the Open versus Protected choice, and that an initial access token 1397 is another possible form of attestation.) 1399 A.2.2. Registration With a Software Statement 1401 A software statement can be used in a registration request to provide 1402 attestation by an authority for a set of client metadata values. 1403 This can be useful when the authorization server wants to restrict 1404 registration to client software attested to by a set of authorities 1405 or when it wants to know that multiple registration requests refer to 1406 the same piece of client software. 1408 A.3. Registration by the Client or Developer 1410 A.3.1. Registration by the Client 1412 In some use cases, client software will dynamically register itself 1413 with an authorization server to obtain a client identifier and other 1414 information needed to interact with the authorization server. In 1415 this case, no client identifier for the authorization server is 1416 packaged with the client software. 1418 A.3.2. Registration by the Developer 1420 In some cases, the developer (or development software being used by 1421 the developer) will pre-register the client software with the 1422 authorization server or a set of authorization servers. In this 1423 case, the client identifier value(s) for the authorization server(s) 1424 can be packaged with the client software. 1426 A.4. Client ID per Client Instance or per Client Software 1428 A.4.1. Client ID per Client Software Instance 1430 In some cases, each deployed instance of a piece of client software 1431 will dynamically register and obtain distinct client identifier 1432 values. This can be advantageous, for instance, if the code flow is 1433 being used, as it also enables each client instance to have its own 1434 client secret. This can be useful for native clients, which cannot 1435 maintain the secrecy of a client secret value packaged with the 1436 software, but which may be able to maintain the secrecy of a per- 1437 instance client secret. 1439 A.4.2. Client ID Shared Among All Instances of Client Software 1441 In some cases, each deployed instance of a piece of client software 1442 will share a common client identifier value. For instance, this is 1443 often the case for in-browser clients using the implicit flow, when 1444 no client secret is involved. Particular authorization servers might 1445 choose, for instance, to maintain a mapping between software 1446 statement values and client identifier values, and return the same 1447 client identifier value for all registration requests for a 1448 particular piece of software. The circumstances under which an 1449 authorization server would do so, and the specific software statement 1450 characteristics required in this case, are beyond the scope of this 1451 specification. 1453 A.5. Stateful or Stateless Registration 1455 A.5.1. Stateful Client Registration 1457 In some cases, authorization servers will maintain state about 1458 registered clients, typically indexing this state using the client 1459 identifier value. This state would typically include the client 1460 metadata values associated with the client registration, and possibly 1461 other state specific to the authorization server's implementation. 1462 When stateful registration is used, operations to support retrieving 1463 and/or updating this state may be supported. One possible set of 1464 operations upon stateful registrations is described in the 1465 [OAuth.Registration.Management] specification. 1467 A.5.2. Stateless Client Registration 1469 In some cases, authorization servers will be implemented in a manner 1470 the enables them to not maintain any local state about registered 1471 clients. One means of doing this is to encode all the registration 1472 state in the returned client identifier value, and possibly 1473 encrypting the state to the authorization server to maintain the 1474 confidentiality and integrity of the state. 1476 Appendix B. Acknowledgments 1478 The authors thank the OAuth Working Group, the User-Managed Access 1479 Working Group, and the OpenID Connect Working Group participants for 1480 their input to this document. In particular, the following 1481 individuals have been instrumental in their review and contribution 1482 to various versions of this document: Amanda Anganes, Derek Atkins, 1483 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1484 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1485 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1486 Sakimura, Christian Scholz, and Hannes Tschofenig. 1488 Appendix C. Document History 1490 [[ to be removed by the RFC editor before publication as an RFC ]] 1492 -22 1494 o Reorganized registration response sections. 1495 o Addressed shepherd comments. 1496 o Added concrete JWK set to example. 1498 -21 1500 o Applied minor editorial fixes. 1501 o Added software statement examples. 1502 o Moved software statement request details to sub-section. 1503 o Clarified that a server MAY ignore the software statement (just as 1504 it MAY ignore other metadata values). 1505 o Removed TLS 1.0. 1506 o Added privacy considerations around "contacts" field. 1507 o Marked software_id as RECOMMENDED inside of a software statement. 1509 -20 1511 o Applied minor editorial fixes from working group comments. 1513 -19 1514 o Added informative references to the OpenID Connect Dynamic Client 1515 Registration and UMA specifications in the introduction. 1516 o Clarified the "jwks" and "jwks_uri" descriptions and included an 1517 example situation in which they might be used. 1518 o Removed "application_type". 1519 o Added redirection URI usage restrictions to the Security 1520 Considerations section, based on the client type. 1521 o Expanded the "tos_uri" and "policy_uri" descriptions. 1523 -18 1525 o Corrected an example HTTP response status code to be 201 Created. 1526 o Said more about who issues and uses initial access tokens and 1527 software statements. 1528 o Stated that the use of an initial access token is required when 1529 the authorization server limits the parties that can register a 1530 client. 1531 o Stated that the implementation and use of all client metadata 1532 fields is OPTIONAL, other than "redirect_uris", which MUST be used 1533 for redirect-based flows and implemented to fulfill the 1534 requirement in Section 2 of OAuth 2.0. 1535 o Added the "application_type" metadata value, which had somehow 1536 been omitted. 1537 o Added missing default metadata values, which had somehow been 1538 omitted. 1539 o Clarified that the "software_id" is ultimately asserted by the 1540 client developer. 1541 o Clarified that the "error" member is required in error responses, 1542 "error_description" member is optional, and other members may be 1543 present. 1544 o Added security consideration about registrations with duplicate 1545 "software_id" and "software_version" values. 1547 -17 1549 o Merged draft-ietf-oauth-dyn-reg-metadata back into this document. 1550 o Removed "Core" from the document title. 1551 o Explicitly state that all metadata members are optional. 1552 o Clarified language around software statements for use in 1553 registration context. 1554 o Clarified that software statements need to be digitally signed or 1555 MACed. 1556 o Added a "jwks" metadata parameter to parallel the "jwks_uri" 1557 parameter. 1558 o Removed normative language from terminology. 1559 o Expanded abstract and introduction. 1560 o Addressed review comments from several working group members. 1562 -16 1564 o Replaced references to draft-jones-oauth-dyn-reg-metadata and 1565 draft-jones-oauth-dyn-reg-management with draft-ietf-oauth-dyn- 1566 reg-metadata and draft-ietf-oauth-dyn-reg-management. 1567 o Addressed review comments by Phil Hunt and Tony Nadalin. 1569 -15 1571 o Partitioned the Dynamic Client Registration specification into 1572 core, metadata, and management specifications. This built on work 1573 first published as draft-richer-oauth-dyn-reg-core-00 and draft- 1574 richer-oauth-dyn-reg-management-00. 1575 o Added the ability to use Software Statements. This built on work 1576 first published as draft-hunt-oauth-software-statement-00 and 1577 draft-hunt-oauth-client-association-00. 1578 o Created the IANA OAuth Registration Client Metadata registry for 1579 registering Client Metadata values. 1580 o Defined Client Instance term and stated that multiple instances 1581 can use the same client identifier value under certain 1582 circumstances. 1583 o Rewrote the introduction. 1584 o Rewrote the Use Cases appendix. 1586 -14 1588 o Added software_id and software_version metadata fields 1589 o Added direct references to RFC6750 errors in read/update/delete 1590 methods 1592 -13 1594 o Fixed broken example text in registration request and in delete 1595 request 1596 o Added security discussion of separating clients of different grant 1597 types 1598 o Fixed error reference to point to RFC6750 instead of RFC6749 1599 o Clarified that servers must respond to all requests to 1600 configuration endpoint, even if it's just an error code 1601 o Lowercased all Terms to conform to style used in RFC6750 1603 -12 1605 o Improved definition of Initial Access Token 1606 o Changed developer registration scenario to have the Initial Access 1607 Token gotten through a normal OAuth 2.0 flow 1608 o Moved non-normative client lifecycle examples to appendix 1609 o Marked differentiating between auth servers as out of scope 1610 o Added protocol flow diagram 1611 o Added credential rotation discussion 1612 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1613 Resource 1614 o Cleaned up several pieces of text 1616 -11 1618 o Added localized text to registration request and response 1619 examples. 1620 o Removed "client_secret_jwt" and "private_key_jwt". 1621 o Clarified "tos_uri" and "policy_uri" definitions. 1622 o Added the OAuth Token Endpoint Authentication Methods registry for 1623 registering "token_endpoint_auth_method" metadata values. 1624 o Removed uses of non-ASCII characters, per RFC formatting rules. 1625 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1626 to "client_id_issued_at" for greater clarity. 1627 o Added explanatory text for different credentials (Initial Access 1628 Token, Registration Access Token, Client Credentials) and what 1629 they're used for. 1630 o Added Client Lifecycle discussion and examples. 1631 o Defined Initial Access Token in Terminology section. 1633 -10 1635 o Added language to point out that scope values are service-specific 1636 o Clarified normative language around client metadata 1637 o Added extensibility to token_endpoint_auth_method using absolute 1638 URIs 1639 o Added security consideration about registering redirect URIs 1640 o Changed erroneous 403 responses to 401's with notes about token 1641 handling 1642 o Added example for initial registration credential 1644 -09 1646 o Added method of internationalization for Client Metadata values 1647 o Fixed SAML reference 1649 -08 1651 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1652 x509_encryption_uri into a single jwks_uri parameter 1653 o Renamed grant_type to grant_types since it's a plural value 1654 o Formalized name of "OAuth 2.0" throughout document 1655 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1656 grant types 1658 o Added response_types parameter and explanatory text on its use 1659 with and relationship to grant_types 1661 -07 1663 o Changed registration_access_url to registration_client_uri 1664 o Fixed missing text in 5.1 1665 o Added Pragma: no-cache to examples 1666 o Changed "no such client" error to 403 1667 o Renamed Client Registration Access Endpoint to Client 1668 Configuration Endpoint 1669 o Changed all the parameter names containing "_url" to instead use 1670 "_uri" 1671 o Updated example text for forming Client Configuration Endpoint URL 1673 -06 1675 o Removed secret_rotation as a client-initiated action, including 1676 removing client secret rotation endpoint and parameters. 1677 o Changed _links structure to single value registration_access_url. 1678 o Collapsed create/update/read responses into client info response. 1679 o Changed return code of create action to 201. 1680 o Added section to describe suggested generation and composition of 1681 Client Registration Access URL. 1682 o Added clarifying text to PUT and POST requests to specify JSON in 1683 the body. 1684 o Added Editor's Note to DELETE operation about its inclusion. 1685 o Added Editor's Note to registration_access_url about alternate 1686 syntax proposals. 1688 -05 1690 o changed redirect_uri and contact to lists instead of space 1691 delimited strings 1692 o removed operation parameter 1693 o added _links structure 1694 o made client update management more RESTful 1695 o split endpoint into three parts 1696 o changed input to JSON from form-encoded 1697 o added READ and DELETE operations 1698 o removed Requirements section 1699 o changed token_endpoint_auth_type back to 1700 token_endpoint_auth_method to match OIDC who changed to match us 1702 -04 1704 o removed default_acr, too undefined in the general OAuth2 case 1705 o removed default_max_auth_age, since there's no mechanism for 1706 supplying a non-default max_auth_age in OAuth2 1707 o clarified signing and encryption URLs 1708 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1709 match OIDC 1711 -03 1713 o added scope and grant_type claims 1714 o fixed various typos and changed wording for better clarity 1715 o endpoint now returns the full set of client information 1716 o operations on client_update allow for three actions on metadata: 1717 leave existing value, clear existing value, replace existing value 1718 with new value 1720 -02 1722 o Reorganized contributors and references 1723 o Moved OAuth references to RFC 1724 o Reorganized model/protocol sections for clarity 1725 o Changed terminology to "client register" instead of "client 1726 associate" 1727 o Specified that client_id must match across all subsequent requests 1728 o Fixed RFC2XML formatting, especially on lists 1730 -01 1732 o Merged UMA and OpenID Connect registrations into a single document 1733 o Changed to form-parameter inputs to endpoint 1734 o Removed pull-based registration 1736 -00 1738 o Imported original UMA draft specification 1740 Authors' Addresses 1742 Justin Richer 1743 The MITRE Corporation 1745 Email: jricher@mitre.org 1747 Michael B. Jones 1748 Microsoft 1750 Email: mbj@microsoft.com 1751 URI: http://self-issued.info/ 1752 John Bradley 1753 Ping Identity 1755 Email: ve7jtb@ve7jtb.com 1757 Maciej Machulak 1758 Newcastle University 1760 Email: m.p.machulak@ncl.ac.uk 1761 URI: http://ncl.ac.uk/ 1763 Phil Hunt 1764 Oracle Corporation 1766 Email: phil.hunt@yahoo.com