idnits 2.17.1 draft-ietf-oauth-dyn-reg-30.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 (May 28, 2015) is 3257 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) ** Obsolete normative reference: RFC 7525 (Obsoleted by RFC 9325) == Outdated reference: A later version (-14) exists of draft-hardjono-oauth-umacore-13 Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft 4 Intended status: Standards Track M. Jones 5 Expires: November 29, 2015 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 P. Hunt 11 Oracle Corporation 12 May 28, 2015 14 OAuth 2.0 Dynamic Client Registration Protocol 15 draft-ietf-oauth-dyn-reg-30 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 November 29, 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 . . . . . . . . . . . . . . . . . . . . . . 6 68 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 69 2.1. Relationship between Grant Types and Response Types . . . 11 70 2.2. Human-Readable Client Metadata . . . . . . . . . . . . . 12 71 2.3. Software Statement . . . . . . . . . . . . . . . . . . . 13 72 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 14 73 3.1. Client Registration Request . . . . . . . . . . . . . . . 15 74 3.1.1. Client Registration Request Using a Software 75 Statement . . . . . . . . . . . . . . . . . . . . . . 17 76 3.2. Responses . . . . . . . . . . . . . . . . . . . . . . . . 18 77 3.2.1. Client Information Response . . . . . . . . . . . . . 18 78 3.2.2. Client Registration Error Response . . . . . . . . . 20 79 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 80 4.1. OAuth Dynamic Client Registration Metadata Registry . . . 22 81 4.1.1. Registration Template . . . . . . . . . . . . . . . . 23 82 4.1.2. Initial Registry Contents . . . . . . . . . . . . . . 23 83 4.2. OAuth Token Endpoint Authentication Methods Registry . . 26 84 4.2.1. Registration Template . . . . . . . . . . . . . . . . 26 85 4.2.2. Initial Registry Contents . . . . . . . . . . . . . . 27 86 5. Security Considerations . . . . . . . . . . . . . . . . . . . 27 87 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 30 88 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 89 7.1. Normative References . . . . . . . . . . . . . . . . . . 31 90 7.2. Informative References . . . . . . . . . . . . . . . . . 33 91 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . 33 92 A.1. Open versus Protected Dynamic Client Registration . . . . 33 93 A.1.1. Open Dynamic Client Registration . . . . . . . . . . 33 94 A.1.2. Protected Dynamic Client Registration . . . . . . . . 33 96 A.2. Registration Without or With Software Statements . . . . 34 97 A.2.1. Registration Without a Software Statement . . . . . . 34 98 A.2.2. Registration With a Software Statement . . . . . . . 34 99 A.3. Registration by the Client or Developer . . . . . . . . . 34 100 A.3.1. Registration by the Client . . . . . . . . . . . . . 34 101 A.3.2. Registration by the Developer . . . . . . . . . . . . 34 102 A.4. Client ID per Client Instance or per Client Software . . 34 103 A.4.1. Client ID per Client Software Instance . . . . . . . 34 104 A.4.2. Client ID Shared Among All Instances of Client 105 Software . . . . . . . . . . . . . . . . . . . . . . 35 106 A.5. Stateful or Stateless Registration . . . . . . . . . . . 35 107 A.5.1. Stateful Client Registration . . . . . . . . . . . . 35 108 A.5.2. Stateless Client Registration . . . . . . . . . . . . 35 109 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 35 110 Appendix C. Document History . . . . . . . . . . . . . . . . . . 36 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42 113 1. Introduction 115 In order for an OAuth 2.0 [RFC6749] 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) [RFC7519]. 163 This specification defines the following terms: 165 Client Software 166 Software implementing an OAuth 2.0 client. 168 Client Instance 169 A deployed instance of a piece of client software. 171 Client Developer 172 The person or organization that builds a client software package 173 and prepares it for distribution. At the time of building the 174 client, the developer is often not aware of who the deploying 175 service provider organizations will be. Client developers will 176 need to use dynamic registration when they are unable to predict 177 aspects of the software, such as the deployment URLs, at compile 178 time. For instance, this can occur when the software API 179 publisher and the deploying organization are not the same. 181 Client Registration Endpoint 182 OAuth 2.0 endpoint through which a client can be registered at an 183 authorization server. The means by which the URL for this 184 endpoint is obtained are out of scope for this specification. 186 Initial Access Token 187 OAuth 2.0 access token optionally issued by an authorization 188 server to a developer or client and used to authorize calls to the 189 client registration endpoint. The type and format of this token 190 are likely service-specific and are out of scope for this 191 specification. The means by which the authorization server issues 192 this token as well as the means by which the registration endpoint 193 validates this token are out of scope for this specification. Use 194 of an initial access token is required when the authorization 195 server limits the parties that can register a client. 197 Deployment Organization 198 An administrative security domain under which a software API 199 (service) is deployed and protected by an OAuth 2.0 framework. In 200 some OAuth scenarios, the deployment organization and the software 201 API publisher are the same. In these cases, the deploying 202 organization will often have a close relationship with client 203 software developers. In many other cases, the definer of the 204 service may be an independent third-party publisher or a standards 205 organization. When working to a published specification for an 206 API, the client software developer is unable to have a prior 207 relationship with the potentially many deployment organizations 208 deploying the software API (service). 210 Software API Deployment 211 A deployed instance of a software API that is protected by OAuth 212 2.0 (a protected resource) in a particular deployment organization 213 domain. For any particular software API, there may be one or more 214 deployments. A software API deployment typically has an 215 associated OAuth 2.0 authorization server as well as a client 216 registration endpoint. The means by which endpoints are obtained 217 are out of scope for this specification. 219 Software API Publisher 220 The organization that defines a particular web accessible API that 221 may be deployed in one or more deployment environments. A 222 publisher may be any standards body, commercial, public, private, 223 or open source organization that is responsible for publishing and 224 distributing software and API specifications that may be protected 225 via OAuth 2.0. In some cases, a software API publisher and a 226 client developer may be the same organization. At the time of 227 publication of a web accessible API, the software publisher often 228 does not have a prior relationship with the deploying 229 organizations. 231 Software Statement 232 Digitally signed or MACed JSON Web Token (JWT) [RFC7519] that 233 asserts metadata values about the client software. In some cases, 234 a software statement will be issued directly by the client 235 developer. In other cases, a software statement will be issued by 236 a third party organization for use by the client developer. In 237 both cases, the trust relationship the authorization server has 238 with the issuer of the software statement is intended to be used 239 as an input to the evaluation of whether the registration request 240 is accepted. A software statement can be presented to an 241 authorization server as part of a client registration request. 243 1.3. Protocol Flow 245 +--------(A)- Initial Access Token (OPTIONAL) 246 | 247 | +----(B)- Software Statement (OPTIONAL) 248 | | 249 v v 250 +-----------+ +---------------+ 251 | |--(C)- Client Registration Request -->| Client | 252 | Client or | | Registration | 253 | Developer |<-(D)- Client Information Response ---| Endpoint | 254 | | or Client Error Response +---------------+ 255 +-----------+ 257 Figure 1: Abstract Dynamic Client Registration Flow 259 The abstract OAuth 2.0 client dynamic registration flow illustrated 260 in Figure 1 describes the interaction between the client or developer 261 and the endpoint defined in this specification. This figure does not 262 demonstrate error conditions. This flow includes the following 263 steps: 265 (A) Optionally, the client or developer is issued an initial access 266 token giving access to the client registration endpoint. The 267 method by which the initial access token is issued to the client 268 or developer is out of scope for this specification. 270 (B) Optionally, the client or developer is issued a software 271 statement for use with the client registration endpoint. The 272 method by which the software statement is issued to the client or 273 developer is out of scope for this specification. 275 (C) The client or developer calls the client registration endpoint 276 with the client's desired registration metadata, optionally 277 including the initial access token from (A) if one is required by 278 the authorization server. 280 (D) The authorization server registers the client and returns: 282 * the client's registered metadata, 284 * a client identifier that is unique at the server, and 285 * a set of client credentials such as a client secret, if 286 applicable for this client. 288 Examples of different configurations and usages are included in 289 Appendix A. 291 2. Client Metadata 293 Registered clients have a set of metadata values associated with 294 their client identifier at an authorization server, such as the list 295 of valid redirection URIs or a display name. 297 These client metadata values are used in two ways: 299 o as input values to registration requests, and 301 o as output values in registration responses. 303 The following client metadata fields are defined by this 304 specification. The implementation and use of all client metadata 305 fields is OPTIONAL, unless stated otherwise. All data member types 306 (strings, arrays, numbers) are defined in terms of their JSON 307 [RFC7159] representations. 309 redirect_uris 310 Array of redirection URI strings for use in redirect-based flows 311 such as the authorization code and implicit flows. As required by 312 Section 2 of OAuth 2.0 [RFC6749], clients using flows with 313 redirection MUST register their redirection URI values. 314 Authorization servers that support dynamic registration for 315 redirect-based flows MUST implement support for this metadata 316 value. 318 token_endpoint_auth_method 319 String indicator of the requested authentication method for the 320 token endpoint. Values defined by this specification are: 322 * "none": The client is a public client as defined in OAuth 2.0 323 and does not have a client secret. 325 * "client_secret_post": The client uses the HTTP POST parameters 326 defined in OAuth 2.0 section 2.3.1. 328 * "client_secret_basic": the client uses HTTP Basic defined in 329 OAuth 2.0 section 2.3.1 331 Additional values can be defined via the IANA OAuth Token Endpoint 332 Authentication Methods Registry established in Section 4.2. 334 Absolute URIs can also be used as values for this parameter 335 without being registered. If unspecified or omitted, the default 336 is "client_secret_basic", denoting HTTP Basic Authentication 337 Scheme as specified in Section 2.3.1 of OAuth 2.0. 339 grant_types 340 Array of OAuth 2.0 grant type strings that the client can use at 341 the token endpoint. These grant types are defined as follows: 343 * "authorization_code": The Authorization Code Grant described in 344 OAuth 2.0 Section 4.1 346 * "implicit": The Implicit Grant described in OAuth 2.0 347 Section 4.2 349 * "password": The Resource Owner Password Credentials Grant 350 described in OAuth 2.0 Section 4.3 352 * "client_credentials": The Client Credentials Grant described in 353 OAuth 2.0 Section 4.4 355 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 356 Section 6. 358 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 359 Grant defined in OAuth JWT Bearer Token Profiles [RFC7523]. 361 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 362 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 363 [RFC7522]. 365 If the token endpoint is used in the grant type, the value of this 366 parameter MUST be the same as the value of the "grant_type" 367 parameter passed to the token endpoint defined in the grant type 368 definition. Authorization servers MAY allow for other values as 369 defined in the grant type extension process described in OAuth 2.0 370 Section 2.5. If omitted, the default behavior is that the client 371 will use only the "authorization_code" Grant Type. 373 response_types 374 Array of the OAuth 2.0 response type strings that the client can 375 use at the authorization endpoint. These response types are 376 defined as follows: 378 * "code": The authorization code response described in OAuth 2.0 379 Section 4.1. 381 * "token": The implicit response described in OAuth 2.0 382 Section 4.2. 384 If the authorization endpoint is used by the grant type, the value 385 of this parameter MUST be the same as the value of the 386 "response_type" parameter passed to the authorization endpoint 387 defined in the grant type definition. Authorization servers MAY 388 allow for other values as defined in the grant type extension 389 process is described in OAuth 2.0 Section 2.5. If omitted, the 390 default is that the client will use only the "code" response type. 392 client_name 393 Human-readable string name of the client to be presented to the 394 end-user during authorization. If omitted, the authorization 395 server MAY display the raw "client_id" value to the end-user 396 instead. It is RECOMMENDED that clients always send this field. 397 The value of this field MAY be internationalized, as described in 398 Section 2.2. 400 client_uri 401 URL string of a web page providing information about the client. 402 If present, the server SHOULD display this URL to the end-user in 403 a clickable fashion. It is RECOMMENDED that clients always send 404 this field. The value of this field MUST point to a valid web 405 page. The value of this field MAY be internationalized, as 406 described in Section 2.2. 408 logo_uri 409 URL string that references a logo for the client. If present, the 410 server SHOULD display this image to the end-user during approval. 411 The value of this field MUST point to a valid image file. The 412 value of this field MAY be internationalized, as described in 413 Section 2.2. 415 scope 416 String containing a space separated list of scope values (as 417 described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client 418 can use when requesting access tokens. The semantics of values in 419 this list is service specific. If omitted, an authorization 420 server MAY register a client with a default set of scopes. 422 contacts 423 Array of strings representing ways to contact people responsible 424 for this client, typically email addresses. The authorization 425 server MAY make these contact addresses available to end-users for 426 support requests for the client. See Section 6 for information on 427 Privacy Considerations. 429 tos_uri 430 URL string that points to a human-readable terms of service 431 document for the client that describes a contractual relationship 432 between the end-user and the client that the end-user accepts when 433 authorizing the client. The authorization server SHOULD display 434 this URL to the end-user if it is provided. The value of this 435 field MUST point to a valid web page. The value of this field MAY 436 be internationalized, as described in Section 2.2. 438 policy_uri 439 URL string that points to a human-readable privacy policy document 440 that describes how the deployment organization collects, uses, 441 retains, and discloses personal data. The authorization server 442 SHOULD display this URL to the end-user if it is provided. The 443 value of this field MUST point to a valid web page. The value of 444 this field MAY be internationalized, as described in Section 2.2. 446 jwks_uri 447 URL string referencing the client's JSON Web Key Set [RFC7517] 448 document, which contains the client's public keys. The value of 449 this field MUST point to a valid JWK Set document. These keys can 450 be used by higher level protocols that use signing or encryption. 451 For instance, these keys might be used by some applications for 452 validating signed requests made to the token endpoint when using 453 JWTs for client authentication [RFC7523]. Use of this parameter 454 is preferred over the "jwks" parameter, as it allows for easier 455 key rotation. The "jwks_uri" and "jwks" parameters MUST NOT both 456 be present in the same request or response. 458 jwks 459 Client's JSON Web Key Set [RFC7517] document value, which contains 460 the client's public keys. The value of this field MUST be a JSON 461 object containing a valid JWK Set. These keys can be used by 462 higher level protocols that use signing or encryption. This 463 parameter is intended to be used by clients that cannot use the 464 "jwks_uri" parameter, such as native clients that cannot host 465 public URLs. The "jwks_uri" and "jwks" parameters MUST NOT both 466 be present in the same request or response. 468 software_id 469 A unique identifier string (e.g. a UUID) assigned by the client 470 developer or software publisher used by registration endpoints to 471 identify the client software to be dynamically registered. Unlike 472 "client_id", which is issued by the authorization server and 473 SHOULD vary between instances, the "software_id" SHOULD remain the 474 same for all instances of the client software. The "software_id" 475 SHOULD remain the same across multiple updates or versions of the 476 same piece of software. The value of this field is not intended 477 to be human-readable and is usually opaque to the client and 478 authorization server. 480 software_version 481 A version identifier string for the client software identified by 482 "software_id". The value of the "software_version" SHOULD change 483 on any update to the client software identified by the same 484 "software_id". The value of this field is intended to be compared 485 using string equality matching and no other comparison semantics 486 are defined by this specification. The value of this field is 487 outside the scope of this speicification, but it is not intended 488 to be human readable and is usually opaque to the client and 489 authorization server. The definition of what constitutes an 490 update to client software that would trigger a change to this 491 value is specific to the software itself and is outside the scope 492 of this specification. 494 Extensions and profiles of this specification can expand this list 495 with metadata names and descriptions registered in accordance with 496 the IANA Considerations in Section 4 of this document. The 497 authorization server MUST ignore any client metadata sent by the 498 client that it does not understand (for instance, by silently 499 removing unknown metadata from the client's registration record 500 during processing). The authorization server MAY reject any 501 requested client metadata values by replacing requested values with 502 suitable defaults as described in Section 3.2.1 or by returning an 503 error response as described in Section 3.2.2. 505 Client metadata values can either be communicated directly in the 506 body of a registration request, as described in Section 3.1, or 507 included as claims in a software statement, as described in 508 Section 2.3, or a mixture of both. If the same client metadata name 509 is present in both locations and the software statement is trusted by 510 the authorization server, the value of a claim in the software 511 statement MUST take precedence. 513 2.1. Relationship between Grant Types and Response Types 515 The "grant_types" and "response_types" values described above are 516 partially orthogonal, as they refer to arguments passed to different 517 endpoints in the OAuth protocol. However, they are related in that 518 the "grant_types" available to a client influence the 519 "response_types" that the client is allowed to use, and vice versa. 520 For instance, a "grant_types" value that includes 521 "authorization_code" implies a "response_types" value that includes 522 "code", as both values are defined as part of the OAuth 2.0 523 authorization code grant. As such, a server supporting these fields 524 SHOULD take steps to ensure that a client cannot register itself into 525 an inconsistent state, for example by returning an 526 "invalid_client_metadata" error response to an inconsistent 527 registration request. 529 The correlation between the two fields is listed in the table below. 531 +-----------------------------------------------+-------------------+ 532 | grant_types value includes: | response_types | 533 | | value includes: | 534 +-----------------------------------------------+-------------------+ 535 | authorization_code | code | 536 | implicit | token | 537 | password | (none) | 538 | client_credentials | (none) | 539 | refresh_token | (none) | 540 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 541 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 542 +-----------------------------------------------+-------------------+ 544 Extensions and profiles of this document that introduce new values to 545 either the "grant_types" or "response_types" parameter MUST document 546 all correspondences between these two parameter types. 548 2.2. Human-Readable Client Metadata 550 Human-readable client metadata values and client metadata values that 551 reference human-readable values MAY be represented in multiple 552 languages and scripts. For example, the values of fields such as 553 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 554 might have multiple locale-specific values in some client 555 registrations to facilitate use in different locations. 557 To specify the languages and scripts, BCP47 [RFC5646] language tags 558 are added to client metadata member names, delimited by a # 559 character. Since JSON [RFC7159] member names are case sensitive, it 560 is RECOMMENDED that language tag values used in Claim Names be 561 spelled using the character case with which they are registered in 562 the IANA Language Subtag Registry [IANA.Language]. In particular, 563 normally language names are spelled with lowercase characters, region 564 names are spelled with uppercase characters, and languages are 565 spelled with mixed case characters. However, since BCP47 language 566 tag values are case insensitive, implementations SHOULD interpret the 567 language tag values supplied in a case insensitive manner. Per the 568 recommendations in BCP47, language tag values used in metadata member 569 names should only be as specific as necessary. For instance, using 570 "fr" might be sufficient in many contexts, rather than "fr-CA" or 571 "fr-FR". 573 For example, a client could represent its name in English as 574 ""client_name#en": "My Client"" and its name in Japanese as 575 ""client_name#ja-Jpan-JP": 576 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 577 registration request. The authorization server MAY display any or 578 all of these names to the resource owner during the authorization 579 step, choosing which name to display based on system configuration, 580 user preferences or other factors. 582 If any human-readable field is sent without a language tag, parties 583 using it MUST NOT make any assumptions about the language, character 584 set, or script of the string value, and the string value MUST be used 585 as-is wherever it is presented in a user interface. To facilitate 586 interoperability, it is RECOMMENDED that clients and servers use a 587 human-readable field without any language tags in addition to any 588 language-specific fields, and it is RECOMMENDED that any human- 589 readable fields sent without language tags contain values suitable 590 for display on a wide variety of systems. 592 Implementer's Note: Many JSON libraries make it possible to reference 593 members of a JSON object as members of an object construct in the 594 native programming environment of the library. However, while the 595 "#" character is a valid character inside of a JSON object's member 596 names, it is not a valid character for use in an object member name 597 in many programming environments. Therefore, implementations will 598 need to use alternative access forms for these claims. For instance, 599 in JavaScript, if one parses the JSON as follows, "var j = 600 JSON.parse(json);", then as a workaround the member "client_name#en- 601 us" can be accessed using the JavaScript syntax "j["client_name#en- 602 us"]". 604 2.3. Software Statement 606 A software statement is a JSON Web Token (JWT) [RFC7519] that asserts 607 metadata values about the client software as a bundle. A set of 608 claims that can be used in a software statement are defined in 609 Section 2. When presented to the authorization server as part of a 610 client registration request, the software statement MUST be digitally 611 signed or MACed using JWS [RFC7515] and MUST contain an "iss" 612 (issuer) claim denoting the party attesting to the claims in the 613 software statement. It is RECOMMENDED that software statements be 614 digitally signed using the "RS256" signature algorithm, although 615 particular applications MAY specify the use of different algorithms. 616 It is RECOMMENDED that software statements contain the "software_id" 617 claim to allow authorization servers to correlate different instances 618 of software using the same software statement. 620 For example, a software statement could contain the following claims: 622 { 623 "software_id": "4NRB1-0XZABZI9E6-5SM3R", 624 "client_name": "Example Statement-based Client", 625 "client_uri": "https://client.example.net/" 626 } 628 The following non-normative example JWT includes these claims and has 629 been asymmetrically signed using RS256: 631 Line breaks are for display purposes only 633 eyJhbGciOiJSUzI1NiJ9. 634 eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll 635 bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs 636 aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ. 637 GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa 638 zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0 639 5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY 640 fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk 641 U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf 642 IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA 644 The means by which a client or developer obtains a software statement 645 are outside the scope of this specification. Some common methods 646 could include a client developer generating a client-specific JWT by 647 registering with a software API publisher to obtain a software 648 statement for a class of clients. The software statement is 649 typically distributed with all instances of a client application. 651 The criteria by which authorization servers determine whether to 652 trust and utilize the information in a software statement are beyond 653 the scope of this specification. 655 In some cases, authorization servers MAY choose to accept a software 656 statement value directly as a client identifier in an authorization 657 request, without a prior dynamic client registration having been 658 performed. The circumstances under which an authorization server 659 would do so, and the specific software statement characteristics 660 required in this case, are beyond the scope of this specification. 662 3. Client Registration Endpoint 664 The client registration endpoint is an OAuth 2.0 endpoint defined in 665 this document that is designed to allow a client to be registered 666 with the authorization server. The client registration endpoint MUST 667 accept HTTP POST messages with request parameters encoded in the 668 entity body using the "application/json" format. The client 669 registration endpoint MUST be protected by a transport-layer security 670 mechanism, as described in Section 5. 672 The client registration endpoint MAY be an OAuth 2.0 protected 673 resource and accept an initial access token in the form of an OAuth 674 2.0 [RFC6749] access token to limit registration to only previously 675 authorized parties. The method by which the initial access token is 676 obtained by the client or developer is generally out-of-band and is 677 out of scope for this specification. The method by which the initial 678 access token is verified and validated by the client registration 679 endpoint is out of scope for this specification. 681 To support open registration and facilitate wider interoperability, 682 the client registration endpoint SHOULD allow registration requests 683 with no authorization (which is to say, with no initial access token 684 in the request). These requests MAY be rate-limited or otherwise 685 limited to prevent a denial-of-service attack on the client 686 registration endpoint. 688 3.1. Client Registration Request 690 This operation registers a client with the authorization server. The 691 authorization server assigns this client a unique client identifier, 692 optionally assigns a client secret, and associates the metadata 693 provided in the request with the issued client identifier. The 694 request includes any client metadata parameters being specified for 695 the client during the registration. The authorization server MAY 696 provision default values for any items omitted in the client 697 metadata. 699 To register, the client or developer sends an HTTP POST to the client 700 registration endpoint with a content type of "application/json". The 701 HTTP Entity Payload is a JSON [RFC7159] document consisting of a JSON 702 object and all requested client metadata values as top-level members 703 of that JSON object. 705 For example, if the server supports open registration (with no 706 initial access token), the client could send the following 707 registration request to the client registration endpoint: 709 The following is a non-normative example request not using an initial 710 access token (with line wraps within values for display purposes 711 only): 713 POST /register HTTP/1.1 714 Content-Type: application/json 715 Accept: application/json 716 Host: server.example.com 718 { 719 "redirect_uris":[ 720 "https://client.example.org/callback", 721 "https://client.example.org/callback2"], 722 "client_name":"My Example Client", 723 "client_name#ja-Jpan-JP": 724 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 725 "token_endpoint_auth_method":"client_secret_basic", 726 "logo_uri":"https://client.example.org/logo.png", 727 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 728 "example_extension_parameter": "example_value" 729 } 731 Alternatively, if the server supports authorized registration, the 732 developer or the client will be provisioned with an initial access 733 token. (The method by which the initial access token is obtained is 734 out of scope for this specification.) The developer or client sends 735 the following authorized registration request to the client 736 registration endpoint. Note that the initial access token sent in 737 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 738 2.0 token type could be used by an authorization server. 740 The following is a non-normative example request using an initial 741 access token and registering a JWK set by value (with line wraps 742 within values for display purposes only): 744 POST /register HTTP/1.1 745 Content-Type: application/json 746 Accept: application/json 747 Authorization: Bearer ey23f2.adfj230.af32-developer321 748 Host: server.example.com 750 { 751 "redirect_uris":["https://client.example.org/callback", 752 "https://client.example.org/callback2"], 753 "client_name":"My Example Client", 754 "client_name#ja-Jpan-JP": 755 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 756 "token_endpoint_auth_method":"client_secret_basic", 757 "policy_uri":"https://client.example.org/policy.html", 758 "jwks":{"keys":[{ 759 "e": "AQAB", 760 "n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG 761 HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk 762 lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p 763 RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe 764 2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve 765 qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ", 766 "kty": "RSA" 767 }]}, 768 "example_extension_parameter": "example_value" 769 } 771 3.1.1. Client Registration Request Using a Software Statement 773 In addition to JSON elements, client metadata values MAY also be 774 provided in a software statement, as described in Section 2.3. The 775 authorization server MAY ignore the software statement if it does not 776 support this feature. If the server supports software statements, 777 client metadata values conveyed in the software statement MUST take 778 precedence over those conveyed using plain JSON elements. 780 Software statements are included in the requesting JSON object using 781 this OPTIONAL member: 783 software_statement 784 A software statement containing client metadata values about the 785 client software as claims. This is a string value containing the 786 entire signed JWT. 788 In the following example, some registration parameters are conveyed 789 as claims in a software statement from the example in Section 2.3, 790 while some values specific to the client instance are conveyed as 791 regular parameters (with line wraps within values for display 792 purposes only): 794 POST /register HTTP/1.1 795 Content-Type: application/json 796 Accept: application/json 797 Host: server.example.com 799 { 800 "redirect_uris":[ 801 "https://client.example.org/callback", 802 "https://client.example.org/callback2" 803 ], 804 "software_statement":"eyJhbGciOiJSUzI1NiJ9. 805 eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll 806 bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs 807 aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ. 808 GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa 809 zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0 810 5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY 811 fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk 812 U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf 813 IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA", 814 "scope":"read write", 815 "example_extension_parameter":"example_value" 816 } 818 3.2. Responses 820 Upon a successful registration request, the authorization server 821 returns a client identifier for the client. The server responds with 822 an HTTP 201 Created code and a body of type "application/json" with 823 content as described in Section 3.2.1. 825 Upon an unsuccessful registration request, the authorization server 826 responds with an error, as described in Section 3.2.2. 828 3.2.1. Client Information Response 830 The response contains the client identifier as well as the client 831 secret, if the client is a confidential client. The response MAY 832 contain additional fields as specified by extensions to this 833 specification. 835 client_id 836 REQUIRED. OAuth 2.0 client identifier string. It SHOULD NOT be 837 currently valid for any other registered client, though an 838 authorization server MAY issue the same client identifier to 839 multiple instances of a registered client at its discretion. 841 client_secret 842 OPTIONAL. OAuth 2.0 client secret string. If issued, this MUST 843 be unique for each "client_id" and SHOULD be unique for multiple 844 instances of a client using the same "client_id". This value is 845 used by confidential clients to authenticate to the token endpoint 846 as described in OAuth 2.0 [RFC6749] Section 2.3.1. 848 client_id_issued_at 849 OPTIONAL. Time at which the client identifier was issued. The 850 time is represented as the number of seconds from 851 1970-01-01T0:0:0Z as measured in UTC until the date/time of 852 issuance. 854 client_secret_expires_at 855 REQUIRED if "client_secret" is issued. Time at which the client 856 secret will expire or 0 if it will not expire. The time is 857 represented as the number of seconds from 1970-01-01T0:0:0Z as 858 measured in UTC until the date/time of expiration. 860 Additionally, the authorization server MUST return all registered 861 metadata about this client, including any fields provisioned by the 862 authorization server itself. The authorization server MAY reject or 863 replace any of the client's requested metadata values submitted 864 during the registration and substitute them with suitable values. 865 The client or developer can check the values in the response to 866 determine if the registration is sufficient for use (e.g., the 867 registered "token_endpoint_auth_method" is supported by the client 868 software) and determine a course of action appropriate for the client 869 software. The response to such a situation is out of scope for this 870 specification but could include filing a report with the application 871 developer or authorization server provider, attempted re-registration 872 with different metadata values, or various other methods. For 873 instance, if the server also supports a registration management 874 mechanism such as that defined in [OAuth.Registration.Management], 875 the client or developer could attempt to update the registration with 876 different metadata values. This process could also be aided by a 877 service discovery protocol such as [OpenID.Discovery] which can list 878 a server's capabilities, allowing a client to make a more informed 879 registration request. The use of any such management or discovery 880 system is optional and outside the scope of this specification. 882 The successful registration response uses an HTTP 201 Created status 883 code with a body of type "application/json" consisting of a single 884 JSON object [RFC7159] with all parameters as top-level members of the 885 object. 887 If a software statement was used as part of the registration, its 888 value MUST be returned unmodified in the response along with other 889 metadata using the "software_statement" member name. Client metadata 890 elements used from the software statement MUST also be returned 891 directly as top-level client metadata values in the registration 892 response (possibly with different values, since the values requested 893 and the values used may differ). 895 Following is a non-normative example response of a successful 896 registration: 898 HTTP/1.1 201 Created 899 Content-Type: application/json 900 Cache-Control: no-store 901 Pragma: no-cache 903 { 904 "client_id":"s6BhdRkqt3", 905 "client_secret": "cf136dc3c1fc93f31185e5885805d", 906 "client_id_issued_at":2893256800, 907 "client_secret_expires_at":2893276800, 908 "redirect_uris":[ 909 "https://client.example.org/callback", 910 "https://client.example.org/callback2"], 911 "grant_types": ["authorization_code", "refresh_token"], 912 "client_name":"My Example Client", 913 "client_name#ja-Jpan-JP": 914 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 915 "token_endpoint_auth_method":"client_secret_basic", 916 "logo_uri":"https://client.example.org/logo.png", 917 "jwks_uri":"https://client.example.org/my_public_keys.jwks", 918 "example_extension_parameter": "example_value" 919 } 921 3.2.2. Client Registration Error Response 923 When an OAuth 2.0 error condition occurs, such as the client 924 presenting an invalid initial access token, the authorization server 925 returns an error response appropriate to the OAuth 2.0 token type. 927 When a registration error condition occurs, the authorization server 928 returns an HTTP 400 status code (unless otherwise specified) with 929 content type "application/json" consisting of a JSON object [RFC7159] 930 describing the error in the response body. 932 Two members are defined for inclusion in the JSON object: 934 error 935 REQUIRED. Single ASCII error code string. 937 error_description 938 OPTIONAL. Human-readable ASCII text description of the error used 939 for debugging. 941 Other members MAY also be included, and if not understood, MUST be 942 ignored. 944 This specification defines the following error codes: 946 invalid_redirect_uri 947 The value of one or more redirection URIs is invalid. 949 invalid_client_metadata 950 The value of one of the client metadata fields is invalid and the 951 server has rejected this request. Note that an authorization 952 server MAY choose to substitute a valid value for any requested 953 parameter of a client's metadata. 955 invalid_software_statement 956 The software statement presented is invalid. 958 unapproved_software_statement 959 The software statement presented is not approved for use by this 960 authorization server. 962 Following is a non-normative example of an error response resulting 963 from a redirection URI that has been blacklisted by the authorization 964 server (with line wraps within values for display purposes only): 966 HTTP/1.1 400 Bad Request 967 Content-Type: application/json 968 Cache-Control: no-store 969 Pragma: no-cache 971 { 972 "error": "invalid_redirect_uri", 973 "error_description": "The redirection URI 974 http://sketchy.example.com is not allowed by this server." 975 } 977 Following is a non-normative example of an error response resulting 978 from an inconsistent combination of "response_types" and 979 "grant_types" values (with line wraps within values for display 980 purposes only): 982 HTTP/1.1 400 Bad Request 983 Content-Type: application/json 984 Cache-Control: no-store 985 Pragma: no-cache 987 { 988 "error": "invalid_client_metadata", 989 "error_description": "The grant type 'authorization_code' must be 990 registered along with the response type 'code' but found only 991 'implicit' instead." 992 } 994 4. IANA Considerations 996 4.1. OAuth Dynamic Client Registration Metadata Registry 998 This specification establishes the OAuth Dynamic Client Registration 999 Metadata registry. 1001 OAuth registration client metadata names and descriptions are 1002 registered with a Specification Required ([RFC5226]) after a two-week 1003 review period on the oauth-ext-review@ietf.org mailing list, on the 1004 advice of one or more Designated Experts. However, to allow for the 1005 allocation of names prior to publication, the Designated Expert(s) 1006 may approve registration once they are satisfied that such a 1007 specification will be published, per [RFC7120]. 1009 Registration requests sent to the mailing list for review should use 1010 an appropriate subject (e.g., "Request to register OAuth Dynamic 1011 Client Registration Metadata name: example"). 1013 Within the review period, the Designated Expert(s) will either 1014 approve or deny the registration request, communicating this decision 1015 to the review list and IANA. Denials should include an explanation 1016 and, if applicable, suggestions as to how to make the request 1017 successful. 1019 IANA must only accept registry updates from the Designated Expert(s) 1020 and should direct all requests for registration to the review mailing 1021 list. 1023 4.1.1. Registration Template 1025 Client Metadata Name: 1026 The name requested (e.g., "example"). This name is case 1027 sensitive. Names that match other registered names in a case 1028 insensitive manner SHOULD NOT be accepted. 1030 Client Metadata Description: 1031 Brief description of the metadata value (e.g., "Example 1032 description"). 1034 Change controller: 1035 For Standards Track RFCs, state "IESG". For others, give the name 1036 of the responsible party. Other details (e.g., postal address, 1037 email address, home page URI) may also be included. 1039 Specification document(s): 1040 Reference to the document(s) that specify the token endpoint 1041 authorization method, preferably including a URI that can be used 1042 to retrieve a copy of the document(s). An indication of the 1043 relevant sections may also be included but is not required. 1045 4.1.2. Initial Registry Contents 1047 The initial contents of the OAuth Dynamic Client Registration 1048 Metadata registry are: 1050 o Client Metadata Name: "redirect_uris" 1051 o Client Metadata Description: Array of redirection URIs for use in 1052 redirect-based flows 1053 o Change controller: IESG 1054 o Specification document(s): [[ this document ]] 1056 o Client Metadata Name: "token_endpoint_auth_method" 1057 o Client Metadata Description: Requested authentication method for 1058 the token endpoint 1059 o Change controller: IESG 1060 o Specification document(s): [[ this document ]] 1062 o Client Metadata Name: "grant_types" 1063 o Client Metadata Description: Array of OAuth 2.0 grant types that 1064 the client may use 1065 o Change controller: IESG 1066 o Specification document(s): [[ this document ]] 1068 o Client Metadata Name: "response_types" 1069 o Client Metadata Description: Array of the OAuth 2.0 response types 1070 that the client may use 1072 o Change controller: IESG 1073 o Specification document(s): [[ this document ]] 1075 o Client Metadata Name: "client_name" 1076 o Client Metadata Description: Human-readable name of the client to 1077 be presented to the user 1078 o Change Controller: IESG 1079 o Specification Document(s): [[ this document ]] 1081 o Client Metadata Name: "client_uri" 1082 o Client Metadata Description: URL of a Web page providing 1083 information about the client 1084 o Change Controller: IESG 1085 o Specification Document(s): [[ this document ]] 1087 o Client Metadata Name: "logo_uri" 1088 o Client Metadata Description: URL that references a logo for the 1089 client 1090 o Change Controller: IESG 1091 o Specification Document(s): [[ this document ]] 1093 o Client Metadata Name: "scope" 1094 o Client Metadata Description: Space separated list of OAuth 2.0 1095 scope values 1096 o Change Controller: IESG 1097 o Specification Document(s): [[ this document ]] 1099 o Client Metadata Name: "contacts" 1100 o Client Metadata Description: Array of strings representing ways to 1101 contact people responsible for this client, typically email 1102 addresses 1103 o Change Controller: IESG 1104 o Specification document(s): [[ this document ]] 1106 o Client Metadata Name: "tos_uri" 1107 o Client Metadata Description: URL that points to a human-readable 1108 Terms of Service document for the client 1109 o Change Controller: IESG 1110 o Specification Document(s): [[ this document ]] 1112 o Client Metadata Name: "policy_uri" 1113 o Client Metadata Description: URL that points to a human-readable 1114 Policy document for the client 1115 o Change Controller: IESG 1116 o Specification Document(s): [[ this document ]] 1118 o Client Metadata Name: "jwks_uri" 1119 o Client Metadata Description: URL referencing the client's JSON Web 1120 Key Set [RFC7517] document representing the client's public keys 1121 o Change Controller: IESG 1122 o Specification Document(s): [[ this document ]] 1124 o Client Metadata Name: "jwks" 1125 o Client Metadata Description: Client's JSON Web Key Set [RFC7517] 1126 document representing the client's public keys 1127 o Change Controller: IESG 1128 o Specification Document(s): [[ this document ]] 1130 o Client Metadata Name: "software_id" 1131 o Client Metadata Description: Identifier for the software that 1132 comprises a client 1133 o Change Controller: IESG 1134 o Specification Document(s): [[ this document ]] 1136 o Client Metadata Name: "software_version" 1137 o Client Metadata Description: Version identifier for the software 1138 that comprises a client 1139 o Change Controller: IESG 1140 o Specification Document(s): [[ this document ]] 1142 o Client Metadata Name: "client_id" 1143 o Client Metadata Description: Client identifier 1144 o Change Controller: IESG 1145 o Specification Document(s): [[ this document ]] 1147 o Client Metadata Name: "client_secret" 1148 o Client Metadata Description: Client secret 1149 o Change Controller: IESG 1150 o Specification Document(s): [[ this document ]] 1152 o Client Metadata Name: "client_id_issued_at" 1153 o Client Metadata Description: Time at which the client identifier 1154 was issued 1155 o Change Controller: IESG 1156 o Specification Document(s): [[ this document ]] 1158 o Client Metadata Name: "client_secret_expires_at" 1159 o Client Metadata Description: Time at which the client secret will 1160 expire 1161 o Change Controller: IESG 1162 o Specification Document(s): [[ this document ]] 1164 4.2. OAuth Token Endpoint Authentication Methods Registry 1166 This specification establishes the OAuth Token Endpoint 1167 Authentication Methods registry. 1169 Additional values for use as "token_endpoint_auth_method" values are 1170 registered with a Specification Required ([RFC5226]) after a two-week 1171 review period on the oauth-ext-review@ietf.org mailing list, on the 1172 advice of one or more Designated Experts. However, to allow for the 1173 allocation of values prior to publication, the Designated Expert(s) 1174 may approve registration once they are satisfied that such a 1175 specification will be published, per [RFC7120]. 1177 Registration requests must be sent to the oauth-ext-review@ietf.org 1178 mailing list for review and comment, with an appropriate subject 1179 (e.g., "Request to register token_endpoint_auth_method value: 1180 example"). 1182 Within the review period, the Designated Expert(s) will either 1183 approve or deny the registration request, communicating this decision 1184 to the review list and IANA. Denials should include an explanation 1185 and, if applicable, suggestions as to how to make the request 1186 successful. 1188 IANA must only accept registry updates from the Designated Expert(s) 1189 and should direct all requests for registration to the review mailing 1190 list. 1192 4.2.1. Registration Template 1194 Token Endpoint Authorization Method Name: 1195 The name requested (e.g., "example"). This name is case 1196 sensitive. Names that match other registered names in a case 1197 insensitive manner SHOULD NOT be accepted. 1199 Change controller: 1200 For Standards Track RFCs, state "IESG". For others, give the name 1201 of the responsible party. Other details (e.g., postal address, 1202 email address, home page URI) may also be included. 1204 Specification document(s): 1205 Reference to the document(s) that specify the token endpoint 1206 authorization method, preferably including a URI that can be used 1207 to retrieve a copy of the document(s). An indication of the 1208 relevant sections may also be included but is not required. 1210 4.2.2. Initial Registry Contents 1212 The initial contents of the OAuth Token Endpoint Authentication 1213 Methods registry are: 1215 o Token Endpoint Authorization Method Name: "none" 1216 o Change controller: IESG 1217 o Specification document(s): [[ this document ]] 1219 o Token Endpoint Authorization Method Name: "client_secret_post" 1220 o Change controller: IESG 1221 o Specification document(s): [[ this document ]] 1223 o Token Endpoint Authorization Method Name: "client_secret_basic" 1224 o Change controller: IESG 1225 o Specification document(s): [[ this document ]] 1227 5. Security Considerations 1229 Since requests to the client registration endpoint result in the 1230 transmission of clear-text credentials (in the HTTP request and 1231 response), the authorization server MUST require the use of a 1232 transport-layer security mechanism when sending requests to the 1233 registration endpoint. The server MUST support TLS 1.2 RFC 5246 1234 [RFC5246] and MAY support additional transport-layer mechanisms 1235 meeting its security requirements. When using TLS, the client MUST 1236 perform a TLS/SSL server certificate check, per RFC 6125 [RFC6125]. 1237 Implementation security considerations can be found in 1238 Recommendations for Secure Use of TLS and DTLS [RFC7525]. 1240 For clients that use redirect-based grant types such as 1241 "authorization_code" and "implicit", authorization servers MUST 1242 require clients to register their redirection URI values. This can 1243 help mitigate attacks where rogue actors inject and impersonate a 1244 validly registered client and intercept its authorization code or 1245 tokens through an invalid redirection URI or open redirector. 1246 Additionally, in order to prevent hijacking of the return values of 1247 the redirection, registered redirection URI values MUST be one of: 1249 o A remote web site protected by TLS (e.g., 1250 https://client.example.com/oauth_redirect) 1251 o A web site hosted on the local machine using an HTTP URI (e.g., 1252 http://localhost:8080/oauth_redirect) 1253 o A non-HTTP application-specific URL that is available only to the 1254 client application (e.g., exampleapp://oauth_redirect) 1256 Public clients MAY register with an authorization server using this 1257 protocol, if the authorization server's policy allows them. Public 1258 clients use a "none" value for the "token_endpoint_auth_method" 1259 metadata field and are generally used with the "implicit" grant type. 1260 Often these clients will be short-lived in-browser applications 1261 requesting access to a user's resources and access is tied to a 1262 user's active session at the authorization server. Since such 1263 clients often do not have long-term storage, it is possible that such 1264 clients would need to re-register every time the browser application 1265 is loaded. To avoid the resulting proliferation of dead client 1266 identifiers, an authorization server MAY decide to expire 1267 registrations for existing clients meeting certain criteria after a 1268 period of time has elapsed. Alternatively, such clients could be 1269 registered on the server where the in-browser application's code is 1270 served from, and the client's configuration pushed to the browser 1271 along side the code. 1273 Since different OAuth 2.0 grant types have different security and 1274 usage parameters, an authorization server MAY require separate 1275 registrations for a piece of software to support multiple grant 1276 types. For instance, an authorization server might require that all 1277 clients using the "authorization_code" grant type make use of a 1278 client secret for the "token_endpoint_auth_method", but any clients 1279 using the "implicit" grant type do not use any authentication at the 1280 token endpoint. In such a situation, a server MAY disallow clients 1281 from registering for both the "authorization_code" and "implicit" 1282 grant types simultaneously. Similarly, the "authorization_code" 1283 grant type is used to represent access on behalf of an end-user, but 1284 the "client_credentials" grant type represents access on behalf of 1285 the client itself. For security reasons, an authorization server 1286 could require that different scopes be used for these different use 1287 cases, and as a consequence it MAY disallow these two grant types 1288 from being registered together by the same client. In all of these 1289 cases, the authorization server would respond with an 1290 "invalid_client_metadata" error response. 1292 Unless used as a claim in a software statement, the authorization 1293 server MUST treat all client metadata as self-asserted. For 1294 instance, a rogue client might use the name and logo of a legitimate 1295 client that it is trying to impersonate. Additionally, a rogue 1296 client might try to use the software identifier or software version 1297 of a legitimate client to attempt to associate itself on the 1298 authorization server with instances of the legitimate client. To 1299 counteract this, an authorization server MUST take appropriate steps 1300 to mitigate this risk by looking at the entire registration request 1301 and client configuration. For instance, an authorization server 1302 could issue a warning if the domain/site of the logo doesn't match 1303 the domain/site of redirection URIs. An authorization server could 1304 also refuse registration requests from a known software identifier 1305 that is requesting different redirection URIs or a different client 1306 URI. An authorization server can also present warning messages to 1307 end-users about dynamically registered clients in all cases, 1308 especially if such clients have been recently registered or have not 1309 been trusted by any users at the authorization server before. 1311 In a situation where the authorization server is supporting open 1312 client registration, it must be extremely careful with any URL 1313 provided by the client that will be displayed to the user (e.g. 1314 "logo_uri", "tos_uri", "client_uri", and "policy_uri"). For 1315 instance, a rogue client could specify a registration request with a 1316 reference to a drive-by download in the "policy_uri", enticing the 1317 user to click on it during the authorization. The authorization 1318 server SHOULD check to see if the "logo_uri", "tos_uri", 1319 "client_uri", and "policy_uri" have the same host and scheme as the 1320 those defined in the array of "redirect_uris" and that all of these 1321 URIs resolve to valid web pages. Since these URI values that are 1322 intended to be displayed to the user at the authorization page, the 1323 authorization server SHOULD protect the user from malicious content 1324 hosted at the URLs where possible. For instance, before presenting 1325 the URLs to the user at the authorization page, the authorization 1326 server could download the content hosted at the URLs, check the 1327 content against a malware scanner and blacklist filter, determine 1328 whether or not there is mixed secure and non-secure content at the 1329 URL, and other possible server-side mitigations. Note that the 1330 content in these URLs can change at any time and the authorization 1331 server cannot provide complete confidence in the safety of the URLs, 1332 but these practices could help. To further mitigate this kind of 1333 threat, the authorization server can also warn the user that the URL 1334 links have been provided by a third party, should be treated with 1335 caution, and are not hosted by the authorization server itself. For 1336 instance, instead of providing the links directly in an HTML anchor, 1337 the authorization server can direct the user to an interstitial 1338 warning page before allowing the user to continue to the target URL. 1340 Clients MAY use both the direct JSON object and the JWT-encoded 1341 software statement to present client metadata to the authorization 1342 server as part of the registration request. A software statement is 1343 cryptographically protected and represents claims made by the issuer 1344 of the statement, while the JSON object represents the self-asserted 1345 claims made by the client or developer directly. If the software 1346 statement is valid and signed by an acceptable authority (such as the 1347 software API publisher), the values of client metadata within the 1348 software statement MUST take precedence over those metadata values 1349 presented in the plain JSON object, which could have been intercepted 1350 and modified. 1352 Like all metadata values, the software statement is an item that is 1353 self-asserted by the client, even though its contents have been 1354 digitally signed or MACed by the issuer of the software statement. 1355 As such, presentation of the software statement is not sufficient in 1356 most cases to fully identify a piece of client software. An initial 1357 access token, in contrast, does not necessarily contain information 1358 about a particular piece of client software but instead represents 1359 authorization to use the registration endpoint. An authorization 1360 server MUST consider the full registration request, including the 1361 software statement, initial access token, and JSON client metadata 1362 values, when deciding whether to honor a given registration request. 1364 If an authorization server receives a registration request for a 1365 client that is not intended to have multiple instances registered 1366 simultaneously and the authorization server can infer a duplication 1367 of registration (e.g., it uses the same "software_id" and 1368 "software_version" values as another existing client), the server 1369 SHOULD treat the new registration as being suspect and reject the 1370 registration. It is possible that the new client is trying to 1371 impersonate the existing client in order to trick users into 1372 authorizing it, or that the original registration is no longer valid. 1373 The details of managing this situation are specific to the 1374 authorization server deployment and outside the scope of this 1375 specification. 1377 Since a client identifier is a public value that can be used to 1378 impersonate a client at the authorization endpoint, an authorization 1379 server that decides to issue the same client identifier to multiple 1380 instances of a registered client needs to be very particular about 1381 the circumstances under which this occurs. For instance, the 1382 authorization server can limit a given client identifier to clients 1383 using the same redirect-based flow and the same redirection URIs. An 1384 authorization server SHOULD NOT issue the same client secret to 1385 multiple instances of a registered client, even if they are issued 1386 the same client identifier, or else the client secret could be 1387 leaked, allowing malicious impostors to impersonate a confidential 1388 client. 1390 6. Privacy Considerations 1392 As the protocol described in this specification deals almost 1393 exclusively with information about software and not about people, 1394 there are very few privacy concerns for its use. The notable 1395 exception is the "contacts" field as defined in Client Metadata 1396 (Section 2), which contains contact information for the developers or 1397 other parties responsible for the client software. These values are 1398 intended to be displayed to end-users and will be available to the 1399 administrators of the authorization server. As such, the developer 1400 may wish to provide an email address or other contact information 1401 expressly dedicated to the purpose of supporting the client instead 1402 of using their personal or professional addresses. Alternatively, 1403 the developer may wish to provide a collective email address for the 1404 client to allow for continuing contact and support of the client 1405 software after the developer moves on and someone else takes over 1406 that responsibility. 1408 In general, the metadata for a client, such as the client name and 1409 software identifier, are common across all instances of a piece of 1410 client software and therefore pose no privacy issues for end-users. 1411 Client identifiers, on the other hand, are often unique to a specific 1412 instance of a client. For clients such as web sites that are used by 1413 many users, there may not be significant privacy concerns regarding 1414 the client identifier, but for clients such as native applications 1415 that are installed on a single end-user's device, the client 1416 identifier could be uniquely tracked during OAuth 2.0 transactions 1417 and its use tied to that single end-user. However, as the client 1418 software still needs to be authorized by a resource owner through an 1419 OAuth 2.0 authorization grant, this type of tracking can occur 1420 whether or not the client identifier is unique by correlating the 1421 authenticated resource owner with the requesting client identifier. 1423 Note that clients are forbidden by this specification from creating 1424 their own client identifier. If the client were able to do so, an 1425 individual client instance could be tracked across multiple colluding 1426 authorization servers, leading to privacy and security issues. 1427 Additionally, client identifiers are generally issued uniquely per 1428 registration request, even for the same instance of software. In 1429 this way, an application could marginally improve privacy by 1430 registering multiple times and appearing to be completely separate 1431 applications. However, this technique does incur significant 1432 usability cost in the form of requiring multiple authorizations per 1433 resource owner and is therefore unlikely to be used in practice. 1435 7. References 1437 7.1. Normative References 1439 [IANA.Language] 1440 Internet Assigned Numbers Authority (IANA), "Language 1441 Subtag Registry", . 1444 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1445 Requirement Levels", BCP 14, RFC 2119, March 1997. 1447 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1448 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1449 May 2008. 1451 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1452 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1454 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1455 Languages", BCP 47, RFC 5646, September 2009. 1457 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1458 Verification of Domain-Based Application Service Identity 1459 within Internet Public Key Infrastructure Using X.509 1460 (PKIX) Certificates in the Context of Transport Layer 1461 Security (TLS)", RFC 6125, March 2011. 1463 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 1464 6749, October 2012. 1466 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1467 Framework: Bearer Token Usage", RFC 6750, October 2012. 1469 [RFC7120] Cotton, M., "Early IANA Allocation of Standards Track Code 1470 Points", BCP 100, RFC 7120, January 2014. 1472 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 1473 Interchange Format", RFC 7159, March 2014. 1475 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 1476 Signature (JWS)", RFC 7515, May 2015. 1478 [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, May 2015. 1480 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 1481 (JWT)", RFC 7519, May 2015. 1483 [RFC7522] Campbell, B., Mortimore, C., and M. Jones, "Security 1484 Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 1485 Client Authentication and Authorization Grants", RFC 7522, 1486 May 2015. 1488 [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1489 (JWT) Profile for OAuth 2.0 Client Authentication and 1490 Authorization Grants", RFC 7523, May 2015. 1492 [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, 1493 "Recommendations for Secure Use of Transport Layer 1494 Security (TLS) and Datagram Transport Layer Security 1495 (DTLS)", BCP 195, RFC 7525, May 2015. 1497 7.2. Informative References 1499 [I-D.hardjono-oauth-umacore] 1500 Hardjono, T., Maler, E., Machulak, M., and D. Catalano, 1501 "User-Managed Access (UMA) Profile of OAuth 2.0", draft- 1502 hardjono-oauth-umacore-13 (work in progress), April 2015. 1504 [OAuth.Registration.Management] 1505 Richer, J., Jones, M., Bradley, J., and M. Machulak, 1506 "OAuth 2.0 Dynamic Client Registration Management 1507 Protocol", draft-ietf-oauth-dyn-reg-management (work in 1508 progress), May 2015. 1510 [OpenID.Discovery] 1511 Sakimura, N., Bradley, J., Jones, M., and E. Jay, "OpenID 1512 Connect Discovery 1.0", November 2014. 1514 [OpenID.Registration] 1515 Sakimura, N., Bradley, J., and M. Jones, "OpenID Connect 1516 Dynamic Client Registration 1.0", November 2014. 1518 Appendix A. Use Cases 1520 This appendix describes different ways that this specification can be 1521 utilized, including describing some of the choices that may need to 1522 be made. Some of the choices are independent and can be used in 1523 combination, whereas some of the choices are interrelated. 1525 A.1. Open versus Protected Dynamic Client Registration 1527 A.1.1. Open Dynamic Client Registration 1529 Authorization servers that support open registration allow 1530 registrations to be made with no initial access token. This allows 1531 all client software to register with the authorization server. 1533 A.1.2. Protected Dynamic Client Registration 1535 Authorization servers that support protected registration require 1536 that an initial access token be used when making registration 1537 requests. While the method by which a client or developer receives 1538 this initial access token and the method by which the authorization 1539 server validates this initial access token are out of scope for this 1540 specification, a common approach is for the developer to use a manual 1541 pre-registration portal at the authorization server that issues an 1542 initial access token to the developer. 1544 A.2. Registration Without or With Software Statements 1546 A.2.1. Registration Without a Software Statement 1548 When a software statement is not used in the registration request, 1549 the authorization server must be willing to use client metadata 1550 values without them being digitally signed or MACed (and thereby 1551 attested to) by any authority. (Note that this choice is independent 1552 of the Open versus Protected choice, and that an initial access token 1553 is another possible form of attestation.) 1555 A.2.2. Registration With a Software Statement 1557 A software statement can be used in a registration request to provide 1558 attestation by an authority for a set of client metadata values. 1559 This can be useful when the authorization server wants to restrict 1560 registration to client software attested to by a set of authorities 1561 or when it wants to know that multiple registration requests refer to 1562 the same piece of client software. 1564 A.3. Registration by the Client or Developer 1566 A.3.1. Registration by the Client 1568 In some use cases, client software will dynamically register itself 1569 with an authorization server to obtain a client identifier and other 1570 information needed to interact with the authorization server. In 1571 this case, no client identifier for the authorization server is 1572 packaged with the client software. 1574 A.3.2. Registration by the Developer 1576 In some cases, the developer (or development software being used by 1577 the developer) will pre-register the client software with the 1578 authorization server or a set of authorization servers. In this 1579 case, the client identifier value(s) for the authorization server(s) 1580 can be packaged with the client software. 1582 A.4. Client ID per Client Instance or per Client Software 1584 A.4.1. Client ID per Client Software Instance 1586 In some cases, each deployed instance of a piece of client software 1587 will dynamically register and obtain distinct client identifier 1588 values. This can be advantageous, for instance, if the code flow is 1589 being used, as it also enables each client instance to have its own 1590 client secret. This can be useful for native clients, which cannot 1591 maintain the secrecy of a client secret value packaged with the 1592 software, but which may be able to maintain the secrecy of a per- 1593 instance client secret. 1595 A.4.2. Client ID Shared Among All Instances of Client Software 1597 In some cases, each deployed instance of a piece of client software 1598 will share a common client identifier value. For instance, this is 1599 often the case for in-browser clients using the implicit flow, when 1600 no client secret is involved. Particular authorization servers might 1601 choose, for instance, to maintain a mapping between software 1602 statement values and client identifier values, and return the same 1603 client identifier value for all registration requests for a 1604 particular piece of software. The circumstances under which an 1605 authorization server would do so, and the specific software statement 1606 characteristics required in this case, are beyond the scope of this 1607 specification. 1609 A.5. Stateful or Stateless Registration 1611 A.5.1. Stateful Client Registration 1613 In some cases, authorization servers will maintain state about 1614 registered clients, typically indexing this state using the client 1615 identifier value. This state would typically include the client 1616 metadata values associated with the client registration, and possibly 1617 other state specific to the authorization server's implementation. 1618 When stateful registration is used, operations to support retrieving 1619 and/or updating this state may be supported. One possible set of 1620 operations upon stateful registrations is described in the 1621 [OAuth.Registration.Management] specification. 1623 A.5.2. Stateless Client Registration 1625 In some cases, authorization servers will be implemented in a manner 1626 the enables them to not maintain any local state about registered 1627 clients. One means of doing this is to encode all the registration 1628 state in the returned client identifier value, and possibly 1629 encrypting the state to the authorization server to maintain the 1630 confidentiality and integrity of the state. 1632 Appendix B. Acknowledgments 1634 The authors thank the OAuth Working Group, the User-Managed Access 1635 Working Group, and the OpenID Connect Working Group participants for 1636 their input to this document. In particular, the following 1637 individuals have been instrumental in their review and contribution 1638 to various versions of this document: Amanda Anganes, Derek Atkins, 1639 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1640 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1641 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1642 Sakimura, Christian Scholz, and Hannes Tschofenig. 1644 Appendix C. Document History 1646 [[ to be removed by the RFC editor before publication as an RFC ]] 1648 -30 1650 o Updated JOSE, JWT, and OAuth Assertion draft references to final 1651 RFC numbers. 1653 -29 1655 o Descrbed more possible client responses to the metadata fields 1656 returned by the server being different than those requested. 1657 o Added RFC 7120/BCP 100 references. 1658 o Added RFC 7525/BCP 195 reference to replace draft reference. 1660 -28 1662 o Clarified all client metadata as JSON arrays, strings, or numbers. 1663 o Expanded security considerations advice around external URLs. 1664 o Added text to say what happens if the client doesn't get back the 1665 registration it expected in the response. 1666 o Added more explicit references to HTTP 201 response from 1667 registration. 1668 o Clarified client version definition. 1669 o Removed spurious reference to "delete action". 1670 o Fixed intended normative and non-normative language in several 1671 sections. 1672 o Stated what a server should do if a suspected duplicate client 1673 tries to register. 1675 -27 1677 o Changed a registry name missed in -26. 1679 -26 1681 o Used consistent registry name. 1683 -25 1685 o Updated author information. 1686 o Clarified registry contents. 1687 o Added forward pointer to IANA from metadata section. 1689 o Clarified how to silently ignore errors. 1690 o Reformatted diagram text. 1692 -24 1694 o Clarified some party definitions. 1695 o Clarified the opaqueness of software_id and software_statement. 1696 o Created a forward pointer to the Security Considerations section 1697 for TLS requirements on the registration endpoint. 1698 o Added a forward pointer to the Privacy Considerations section for 1699 the contacts field. 1700 o Wrote privacy considerations about client_id tracking. 1702 -23 1704 o Updated author information. 1706 -22 1708 o Reorganized registration response sections. 1709 o Addressed shepherd comments. 1710 o Added concrete JWK set to example. 1712 -21 1714 o Applied minor editorial fixes. 1715 o Added software statement examples. 1716 o Moved software statement request details to sub-section. 1717 o Clarified that a server MAY ignore the software statement (just as 1718 it MAY ignore other metadata values). 1719 o Removed TLS 1.0. 1720 o Added privacy considerations around "contacts" field. 1721 o Marked software_id as RECOMMENDED inside of a software statement. 1723 -20 1725 o Applied minor editorial fixes from working group comments. 1727 -19 1729 o Added informative references to the OpenID Connect Dynamic Client 1730 Registration and UMA specifications in the introduction. 1731 o Clarified the "jwks" and "jwks_uri" descriptions and included an 1732 example situation in which they might be used. 1733 o Removed "application_type". 1734 o Added redirection URI usage restrictions to the Security 1735 Considerations section, based on the client type. 1736 o Expanded the "tos_uri" and "policy_uri" descriptions. 1738 -18 1740 o Corrected an example HTTP response status code to be 201 Created. 1741 o Said more about who issues and uses initial access tokens and 1742 software statements. 1743 o Stated that the use of an initial access token is required when 1744 the authorization server limits the parties that can register a 1745 client. 1746 o Stated that the implementation and use of all client metadata 1747 fields is OPTIONAL, other than "redirect_uris", which MUST be used 1748 for redirect-based flows and implemented to fulfill the 1749 requirement in Section 2 of OAuth 2.0. 1750 o Added the "application_type" metadata value, which had somehow 1751 been omitted. 1752 o Added missing default metadata values, which had somehow been 1753 omitted. 1754 o Clarified that the "software_id" is ultimately asserted by the 1755 client developer. 1756 o Clarified that the "error" member is required in error responses, 1757 "error_description" member is optional, and other members may be 1758 present. 1759 o Added security consideration about registrations with duplicate 1760 "software_id" and "software_version" values. 1762 -17 1764 o Merged draft-ietf-oauth-dyn-reg-metadata back into this document. 1765 o Removed "Core" from the document title. 1766 o Explicitly state that all metadata members are optional. 1767 o Clarified language around software statements for use in 1768 registration context. 1769 o Clarified that software statements need to be digitally signed or 1770 MACed. 1771 o Added a "jwks" metadata parameter to parallel the "jwks_uri" 1772 parameter. 1773 o Removed normative language from terminology. 1774 o Expanded abstract and introduction. 1775 o Addressed review comments from several working group members. 1777 -16 1779 o Replaced references to draft-jones-oauth-dyn-reg-metadata and 1780 draft-jones-oauth-dyn-reg-management with draft-ietf-oauth-dyn- 1781 reg-metadata and draft-ietf-oauth-dyn-reg-management. 1782 o Addressed review comments by Phil Hunt and Tony Nadalin. 1784 -15 1785 o Partitioned the Dynamic Client Registration specification into 1786 core, metadata, and management specifications. This built on work 1787 first published as draft-richer-oauth-dyn-reg-core-00 and draft- 1788 richer-oauth-dyn-reg-management-00. 1789 o Added the ability to use Software Statements. This built on work 1790 first published as draft-hunt-oauth-software-statement-00 and 1791 draft-hunt-oauth-client-association-00. 1792 o Created the IANA OAuth Registration Client Metadata registry for 1793 registering Client Metadata values. 1794 o Defined Client Instance term and stated that multiple instances 1795 can use the same client identifier value under certain 1796 circumstances. 1797 o Rewrote the introduction. 1798 o Rewrote the Use Cases appendix. 1800 -14 1802 o Added software_id and software_version metadata fields 1803 o Added direct references to RFC6750 errors in read/update/delete 1804 methods 1806 -13 1808 o Fixed broken example text in registration request and in delete 1809 request 1810 o Added security discussion of separating clients of different grant 1811 types 1812 o Fixed error reference to point to RFC6750 instead of RFC6749 1813 o Clarified that servers must respond to all requests to 1814 configuration endpoint, even if it's just an error code 1815 o Lowercased all Terms to conform to style used in RFC6750 1817 -12 1819 o Improved definition of Initial Access Token 1820 o Changed developer registration scenario to have the Initial Access 1821 Token gotten through a normal OAuth 2.0 flow 1822 o Moved non-normative client lifecycle examples to appendix 1823 o Marked differentiating between auth servers as out of scope 1824 o Added protocol flow diagram 1825 o Added credential rotation discussion 1826 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1827 Resource 1828 o Cleaned up several pieces of text 1830 -11 1831 o Added localized text to registration request and response 1832 examples. 1833 o Removed "client_secret_jwt" and "private_key_jwt". 1834 o Clarified "tos_uri" and "policy_uri" definitions. 1835 o Added the OAuth Token Endpoint Authentication Methods registry for 1836 registering "token_endpoint_auth_method" metadata values. 1837 o Removed uses of non-ASCII characters, per RFC formatting rules. 1838 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1839 to "client_id_issued_at" for greater clarity. 1840 o Added explanatory text for different credentials (Initial Access 1841 Token, Registration Access Token, Client Credentials) and what 1842 they're used for. 1843 o Added Client Lifecycle discussion and examples. 1844 o Defined Initial Access Token in Terminology section. 1846 -10 1848 o Added language to point out that scope values are service-specific 1849 o Clarified normative language around client metadata 1850 o Added extensibility to token_endpoint_auth_method using absolute 1851 URIs 1852 o Added security consideration about registering redirect URIs 1853 o Changed erroneous 403 responses to 401's with notes about token 1854 handling 1855 o Added example for initial registration credential 1857 -09 1859 o Added method of internationalization for Client Metadata values 1860 o Fixed SAML reference 1862 -08 1864 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1865 x509_encryption_uri into a single jwks_uri parameter 1866 o Renamed grant_type to grant_types since it's a plural value 1867 o Formalized name of "OAuth 2.0" throughout document 1868 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1869 grant types 1870 o Added response_types parameter and explanatory text on its use 1871 with and relationship to grant_types 1873 -07 1875 o Changed registration_access_url to registration_client_uri 1876 o Fixed missing text in 5.1 1877 o Added Pragma: no-cache to examples 1878 o Changed "no such client" error to 403 1879 o Renamed Client Registration Access Endpoint to Client 1880 Configuration Endpoint 1881 o Changed all the parameter names containing "_url" to instead use 1882 "_uri" 1883 o Updated example text for forming Client Configuration Endpoint URL 1885 -06 1887 o Removed secret_rotation as a client-initiated action, including 1888 removing client secret rotation endpoint and parameters. 1889 o Changed _links structure to single value registration_access_url. 1890 o Collapsed create/update/read responses into client info response. 1891 o Changed return code of create action to 201. 1892 o Added section to describe suggested generation and composition of 1893 Client Registration Access URL. 1894 o Added clarifying text to PUT and POST requests to specify JSON in 1895 the body. 1896 o Added Editor's Note to DELETE operation about its inclusion. 1897 o Added Editor's Note to registration_access_url about alternate 1898 syntax proposals. 1900 -05 1902 o changed redirect_uri and contact to lists instead of space 1903 delimited strings 1904 o removed operation parameter 1905 o added _links structure 1906 o made client update management more RESTful 1907 o split endpoint into three parts 1908 o changed input to JSON from form-encoded 1909 o added READ and DELETE operations 1910 o removed Requirements section 1911 o changed token_endpoint_auth_type back to 1912 token_endpoint_auth_method to match OIDC who changed to match us 1914 -04 1916 o removed default_acr, too undefined in the general OAuth2 case 1917 o removed default_max_auth_age, since there's no mechanism for 1918 supplying a non-default max_auth_age in OAuth2 1919 o clarified signing and encryption URLs 1920 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1921 match OIDC 1923 -03 1925 o added scope and grant_type claims 1926 o fixed various typos and changed wording for better clarity 1927 o endpoint now returns the full set of client information 1928 o operations on client_update allow for three actions on metadata: 1929 leave existing value, clear existing value, replace existing value 1930 with new value 1932 -02 1934 o Reorganized contributors and references 1935 o Moved OAuth references to RFC 1936 o Reorganized model/protocol sections for clarity 1937 o Changed terminology to "client register" instead of "client 1938 associate" 1939 o Specified that client_id must match across all subsequent requests 1940 o Fixed RFC2XML formatting, especially on lists 1942 -01 1944 o Merged UMA and OpenID Connect registrations into a single document 1945 o Changed to form-parameter inputs to endpoint 1946 o Removed pull-based registration 1948 -00 1950 o Imported original UMA draft specification 1952 Authors' Addresses 1954 Justin Richer (editor) 1956 Email: ietf@justin.richer.org 1958 Michael B. Jones 1959 Microsoft 1961 Email: mbj@microsoft.com 1962 URI: http://self-issued.info/ 1964 John Bradley 1965 Ping Identity 1967 Email: ve7jtb@ve7jtb.com 1968 Maciej Machulak 1969 Newcastle University 1971 Email: maciej.machulak@gmail.com 1973 Phil Hunt 1974 Oracle Corporation 1976 Email: phil.hunt@yahoo.com