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