idnits 2.17.1 draft-ietf-oauth-dyn-reg-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (January 28, 2014) is 3740 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** 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) Summary: 5 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track M. Jones 5 Expires: August 1, 2014 Microsoft 6 J. Bradley 7 Ping Identity 8 M. Machulak 9 Newcastle University 10 January 28, 2014 12 OAuth 2.0 Dynamic Client Registration Core Protocol 13 draft-ietf-oauth-dyn-reg-15 15 Abstract 17 This specification defines mechanisms used to dynamically register 18 OAuth 2.0 clients at authorization servers. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 1, 2014. 37 Copyright Notice 39 Copyright (c) 2014 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 4 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 57 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 58 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 7 59 2.1. Relationship between Grant Types and Response Types . . . 9 60 3. Software Statement . . . . . . . . . . . . . . . . . . . . . . 9 61 4. Client Registration Endpoint . . . . . . . . . . . . . . . . . 10 62 4.1. Client Registration Request . . . . . . . . . . . . . . . 11 63 4.2. Client Registration Response . . . . . . . . . . . . . . . 13 64 5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 13 65 5.1. Client Information Response . . . . . . . . . . . . . . . 13 66 5.2. Client Registration Error Response . . . . . . . . . . . . 15 67 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 68 6.1. OAuth Registration Client Metadata Registry . . . . . . . 16 69 6.1.1. Registration Template . . . . . . . . . . . . . . . . 17 70 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 17 71 6.2. OAuth Token Endpoint Authentication Methods Registry . . . 18 72 6.2.1. Registration Template . . . . . . . . . . . . . . . . 18 73 6.2.2. Initial Registry Contents . . . . . . . . . . . . . . 19 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 75 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 8.1. Normative References . . . . . . . . . . . . . . . . . . . 20 77 8.2. Informative References . . . . . . . . . . . . . . . . . . 21 78 Appendix A. Use Cases . . . . . . . . . . . . . . . . . . . . . . 22 79 A.1. Open versus Protected Dynamic Client Registration . . . . 22 80 A.1.1. Open Dynamic Client Registration . . . . . . . . . . . 22 81 A.1.2. Protected Dynamic Client Registration . . . . . . . . 22 82 A.2. Registration without or with Software Statements . . . . . 22 83 A.2.1. Registration without a Software Statement . . . . . . 22 84 A.2.2. Registration with a Software Statement . . . . . . . . 22 85 A.3. Registration by the Client or the Developer . . . . . . . 23 86 A.3.1. Registration by the Client . . . . . . . . . . . . . . 23 87 A.3.2. Registration by the Developer . . . . . . . . . . . . 23 88 A.4. Client ID per Client Instance or per Client Software . . . 23 89 A.4.1. Client ID per Client Software Instance . . . . . . . . 23 90 A.4.2. Client ID Shared between all Instances of Client 91 Software . . . . . . . . . . . . . . . . . . . . . . . 23 92 A.5. Stateful or Stateless Registration . . . . . . . . . . . . 23 93 A.5.1. Stateful Client Registration . . . . . . . . . . . . . 24 94 A.5.2. Stateless Client Registration . . . . . . . . . . . . 24 95 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . . 24 96 Appendix C. Document History . . . . . . . . . . . . . . . . . . 24 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 99 1. Introduction 101 In order for an OAuth 2.0 client to utilize an OAuth 2.0 102 authorization server, the client needs specific information to 103 interact with the server, including an OAuth 2.0 Client ID to use at 104 that server. This specification describes how an OAuth 2.0 client 105 can be dynamically registered with an authorization server to obtain 106 this information. 108 As part of the registration process, this specification also defines 109 a mechanism for the client to present the authorization server with a 110 set of metadata, such as a set of valid redirection URIs. This 111 metadata can either be communicated in a self-asserted fashion or as 112 a set of signed metadata called a software statement; in the case of 113 a software statement, the signer is vouching for the validity of the 114 data about the client. 116 The mechanisms defined in this specification can be used either for a 117 client to dynamically register itself with authorization servers or 118 for a client developer to programmatically register the client with 119 authorization servers. 121 1.1. Notational Conventions 123 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 124 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 125 document are to be interpreted as described in [RFC2119]. 127 Unless otherwise noted, all the protocol parameter names and values 128 are case sensitive. 130 1.2. Terminology 132 This specification uses the terms "Access Token", "Refresh Token", 133 "Authorization Code", "Authorization Grant", "Authorization Server", 134 "Authorization Endpoint", "Client", "Client Identifier", "Client 135 Secret", "Protected Resource", "Resource Owner", "Resource Server", 136 "Response Type", and "Token Endpoint" defined by OAuth 2.0 [RFC6749] 137 and uses the term "Claim" defined by JSON Web Token (JWT) [JWT]. 139 This specification defines the following terms: 141 Client Developer The person or organization that builds a client 142 software package and prepares it for distribution. A client 143 developer obtains a software assertion from a software publisher, 144 or self-generates one for the purposes of facilitating client 145 registration. 147 Client Instance A deployed instance of a piece of client software. 148 Multiple instances of the same piece of client software MAY use 149 the same Client ID value at an authorization server, provided that 150 the Redirection URI values and potentially other values dictated 151 by authorization server policy are the same for all instances. 153 Client Software Software implementing an OAuth 2.0 client. 155 Client Registration Endpoint OAuth 2.0 endpoint through which a 156 client can be registered at an authorization server. The means by 157 which the URL for this endpoint is obtained are out of scope for 158 this specification. 160 Initial Access Token OAuth 2.0 access token optionally issued by an 161 Authorization Server and used to authorize calls to the client 162 registration endpoint. The type and format of this token are 163 likely service-specific and are out of scope for this 164 specification. The means by which the authorization server issues 165 this token as well as the means by which the registration endpoint 166 validates this token are out of scope for this specification. 168 Deployment Organization An administrative security domain under 169 which, a software API is deployed and protected by an OAuth 2.0 170 framework. In simple cloud deployments, the software API 171 publisher and the deployment organization may be the same. In 172 other scenarios, a software publisher may be working with many 173 different deployment organizations. 175 Software API Deployment A deployment instance of a software API that 176 is protected by OAuth 2.0 in a particular deployment organization 177 domain. For any particular software API, there may be one or more 178 deployments. A software API deployment typically has an 179 associated OAuth 2.0 authorization server endpoint as well as a 180 client registration endpoint. The means by which endpoints are 181 obtained (discovery) are out of scope for this specification. 183 Software API Publisher The organization that defines a particular 184 web accessible API that may deployed in one or more deployment 185 environments. A publisher may be any commercial, public, private, 186 or open source organization that is responsible for publishing and 187 distributing software that may be protected via OAuth 2.0. A 188 software API publisher may issue software assertions which client 189 developers use to distribute with their software to facilitate 190 registration. In some cases a software API publisher and a client 191 developer may be the same organization. 193 Software Statement A signed JSON Web Token (JWT) [JWT] that asserts 194 metadata values about the client software. This may be used by 195 the registration system to qualify clients for eligibility to 196 register. To obtain a software statement, a client developer may 197 generate a client specific assertion, or a client developer may 198 register with a software API publisher to obtain a software 199 assertion. The statement is distributed with all copies of a 200 client application and may be used during the registration 201 process. 203 1.3. Protocol Flow 205 +--------(A)- Initial Access Token (OPTIONAL) 206 | 207 | +----(B)- Software Statement (OPTIONAL) 208 | | 209 v v 210 +-----------+ +---------------+ 211 | |--(C)- Client Registration Request -->| Client | 212 | Client or | | Registration | 213 | Developer |<-(D)- Client Information Response ---| Endpoint | 214 | | +---------------+ 215 +-----------+ 217 Figure 1: Abstract Dynamic Client Registration Flow 219 The abstract OAuth 2.0 client dynamic registration flow illustrated 220 in Figure 1 describes the interaction between the client or developer 221 and the endpoint defined in this specification. This figure does not 222 demonstrate error conditions. This flow includes the following 223 steps: 225 (A) Optionally, the client or developer is issued an initial access 226 token giving access to the client registration endpoint. The 227 method by which the initial access token is issued to the client 228 or developer is out of scope for this specification. 230 (B) Optionally, the client or developer is issued a software 231 statement for use with the client registration endpoint. The 232 method by which the software statement is issued to the client or 233 developer is out of scope for this specification. 235 (C) The client or developer calls the client registration endpoint 236 with its desired registration metadata, optionally including the 237 initial access token from (A) if one is required by the 238 authorization server. 240 (D) The authorization server registers the client and returns the 241 client's registered metadata, a client identifier that is unique 242 at the server, a set of client credentials such as a client secret 243 if applicable for this client, and possibly other values. 245 2. Client Metadata 247 Clients have a set of metadata values associated with their unique 248 client identifier at an authorization server, such as the list of 249 valid redirect URIs. 251 The Client Metadata values are used in two ways: 253 o as input values to registration requests, and 255 o as output values in registration responses. 257 Client Metadata values can either be communicated directly in the 258 body of a registration request, as described in Section 4.1, or 259 included as claims in a software statement, as described in 260 Section 3. 262 These Client Metadata values are defined by this specification: 264 redirect_uris Array of redirect URIs for use in redirect-based flows 265 such as the authorization code and implicit grant types. It is 266 RECOMMENDED that clients using these flows register this 267 parameter, and an authorization server SHOULD require registration 268 of valid redirect URIs for all clients that use these grant types 269 to protect against token and credential theft attacks. 271 token_endpoint_auth_method The requested authentication method for 272 the token endpoint. Values defined by this specification are: 274 * "none": The client is a public client as defined in OAuth 2.0 275 and does not have a client secret. 277 * "client_secret_post": The client uses the HTTP POST parameters 278 defined in OAuth 2.0 section 2.3.1. 280 * "client_secret_basic": the client uses HTTP Basic defined in 281 OAuth 2.0 section 2.3.1 283 Additional values can be defined via the IANA OAuth Token Endpoint 284 Authentication Methods Registry Section 6.2. Absolute URIs can 285 also be used as values for this parameter without being 286 registered. If unspecified or omitted, the default is 287 "client_secret_basic", denoting HTTP Basic Authentication Scheme 288 as specified in Section 2.3.1 of OAuth 2.0. 290 grant_types Array of OAuth 2.0 grant types that the Client may use. 291 These grant types are defined as follows: 293 * "authorization_code": The Authorization Code Grant described in 294 OAuth 2.0 Section 4.1 296 * "implicit": The Implicit Grant described in OAuth 2.0 Section 297 4.2 299 * "password": The Resource Owner Password Credentials Grant 300 described in OAuth 2.0 Section 4.3 302 * "client_credentials": The Client Credentials Grant described in 303 OAuth 2.0 Section 4.4 305 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 306 Section 6. 308 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 309 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 311 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 312 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 313 [OAuth.SAML2]. 315 Authorization Servers MAY allow for other values as defined in 316 grant type extensions to OAuth 2.0. The extension process is 317 described in OAuth 2.0 Section 2.5. If the token endpoint is used 318 in the grant type, the value of this parameter MUST be the same as 319 the value of the "grant_type" parameter passed to the token 320 endpoint defined in the extension. 322 response_types Array of the OAuth 2.0 response types that the Client 323 may use. These response types are defined as follows: 325 * "code": The Authorization Code response described in OAuth 2.0 326 Section 4.1. 328 * "token": The Implicit response described in OAuth 2.0 Section 329 4.2. 331 Authorization servers MAY allow for other values as defined in 332 response type extensions to OAuth 2.0. The extension process is 333 described in OAuth 2.0 Section 2.5. If the authorization endpoint 334 is used by the grant type, the value of this parameter MUST be the 335 same as the value of the "response_type" parameter passed to the 336 authorization endpoint defined in the extension. 338 Authorization servers MUST accept all fields in this list. 339 Extensions and profiles of this specification MAY expand this list. 340 For instance, the [OAuth.Registration.Metadata] specification defines 341 additional client metadata values. The authorization server MUST 342 ignore any client metadata values sent by the Client that it does not 343 understand. 345 2.1. Relationship between Grant Types and Response Types 347 The "grant_types" and "response_types" values described above are 348 partially orthogonal, as they refer to arguments passed to different 349 endpoints in the OAuth protocol. However, they are related in that 350 the "grant_types" available to a client influence the 351 "response_types" that the client is allowed to use, and vice versa. 352 For instance, a "grant_types" value that includes 353 "authorization_code" implies a "response_types" value that includes 354 "code", as both values are defined as part of the OAuth 2.0 355 authorization code grant. As such, a server supporting these fields 356 SHOULD take steps to ensure that a client cannot register itself into 357 an inconsistent state. 359 The correlation between the two fields is listed in the table below. 361 +-----------------------------------------------+-------------------+ 362 | grant_types value includes: | response_types | 363 | | value includes: | 364 +-----------------------------------------------+-------------------+ 365 | authorization_code | code | 366 | implicit | token | 367 | password | (none) | 368 | client_credentials | (none) | 369 | refresh_token | (none) | 370 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 371 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 372 +-----------------------------------------------+-------------------+ 374 Extensions and profiles of this document that introduce new values to 375 either the "grant_types" or "response_types" parameter MUST document 376 all correspondences between these two parameter types. 378 3. Software Statement 380 A Software Statement is a signed JSON Web Token (JWT) [JWT] that 381 asserts metadata values about the client software. This may be used 382 by the registration system to qualify clients for eligibility to 383 register. To obtain a software statement, a client developer may 384 generate a client specific assertion, or a client developer may 385 register with a software API publisher to obtain a software 386 assertion. The statement is distributed with all copies of a client 387 application and may be used during the registration process. 389 The criteria by which authorization servers determine whether to 390 trust and utilize the information in a software statement is beyond 391 the scope of this specification. 393 If the authorization server determines that the claims in a software 394 statement uniquely identify a piece of software, the same Client ID 395 value MAY be returned for all dynamic registrations using that 396 software statement. 398 In some cases, authorization servers MAY choose to accept a software 399 statement value directly as a Client ID in an authorization request, 400 without a prior dynamic client registration having been performed. 401 The circumstances under which an authorization server would do so, 402 and the specific software statement characteristics required in this 403 case, are beyond the scope of this specification. 405 4. Client Registration Endpoint 407 The client registration endpoint is an OAuth 2.0 endpoint defined in 408 this document that is designed to allow a client to be registered 409 with the authorization server. The client registration endpoint MUST 410 accept HTTP POST messages with request parameters encoded in the 411 entity body using the "application/json" format. The client 412 registration endpoint MUST be protected by a transport-layer security 413 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] 414 and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer 415 mechanisms meeting its security requirements. When using TLS, the 416 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 417 [RFC6125]. 419 The client registration endpoint MAY be an OAuth 2.0 protected 420 resource and accept an initial access token in the form of an OAuth 421 2.0 [RFC6749] access token to limit registration to only previously 422 authorized parties. The method by which the initial access token is 423 obtained by the registrant is generally out-of-band and is out of 424 scope for this specification. The method by which the initial access 425 token is verified and validated by the client registration endpoint 426 is out of scope for this specification. 428 To support open registration and facilitate wider interoperability, 429 the client registration endpoint SHOULD allow initial registration 430 requests with no authorization (which is to say, with no OAuth 2.0 431 access token in the request). These requests MAY be rate-limited or 432 otherwise limited to prevent a denial-of-service attack on the client 433 registration endpoint. 435 The client registration endpoint MUST ignore all parameters it does 436 not understand. 438 4.1. Client Registration Request 440 This operation registers a new client to the authorization server. 441 The authorization server assigns this client a unique client 442 identifier, optionally assigns a client secret, and associates the 443 metadata given in the request with the issued client identifier. The 444 request includes any client metadata parameters being specified for 445 the client during the registration. The authorization server MAY 446 provision default values for any items omitted in the client 447 metadata. 449 Client metadata values may also be provided in a software statement, 450 as described in Section 3. Software statements are included in 451 registration requests using this registration parameter: 453 software_statement A software statement containing client metadata 454 values about the client software as claims. 456 To register, the client or developer sends an HTTP POST to the client 457 registration endpoint with a content type of "application/json". The 458 HTTP Entity Payload is a JSON [RFC4627] document consisting of a JSON 459 object and all parameters as top-level members of that JSON object. 461 For example, if the server supports open registration (with no 462 initial access token), the client could send the following 463 registration request to the client registration endpoint: 465 The following is a non-normative example request not using an initial 466 access token (with line wraps within values for display purposes 467 only): 469 POST /register HTTP/1.1 470 Content-Type: application/json 471 Accept: application/json 472 Host: server.example.com 474 { 475 "redirect_uris":[ 476 "https://client.example.org/callback", 477 "https://client.example.org/callback2"], 478 "token_endpoint_auth_method":"client_secret_basic", 479 "example_extension_parameter": "example_value" 480 } 482 Alternatively, if the server supports authorized registration, the 483 developer or the client will be provisioned with an initial access 484 token (the method by which the initial access token is obtained is 485 out of scope for this specification). The developer or client sends 486 the following authorized registration request to the client 487 registration endpoint. Note that the initial access token sent in 488 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 489 2.0 token type could be used by an authorization server. 491 The following is a non-normative example request using an initial 492 access token (with line wraps within values for display purposes 493 only): 495 POST /register HTTP/1.1 496 Content-Type: application/json 497 Accept: application/json 498 Authorization: Bearer ey23f2.adfj230.af32-developer321 499 Host: server.example.com 501 { 502 "redirect_uris":["https://client.example.org/callback", 503 "https://client.example.org/callback2"], 504 "token_endpoint_auth_method":"client_secret_basic", 505 "example_extension_parameter": "example_value" 506 } 508 In the following example, some registration parameters are conveyed 509 as claims in a software statement (with line wraps within values for 510 display purposes only): 512 POST /register HTTP/1.1 513 Content-Type: application/json 514 Accept: application/json 515 Host: server.example.com 517 { 518 "redirect_uris":[ 519 "https://client.example.org/callback", 520 "https://client.example.org/callback2" 521 ], 522 "software_statement":"eyJhbGciOiJFUzI1NiJ9. 523 eyJpc3Mi[...omitted for brevity...]. 524 J9l-ZhwP[...omitted for brevity...]", 525 "extension_parameter":"foo" 526 } 528 4.2. Client Registration Response 530 Upon successful registration, the authorization server generates a 531 new client identifier for the client. This client identifier MUST be 532 unique at the server and MUST NOT be in use by any other client. The 533 server responds with an HTTP 201 Created code and a body of type 534 "application/json" with content as described in Section 5.1. 536 Upon an unsuccessful registration, the authorization server responds 537 with an error, as described in Section 5.2. 539 5. Responses 541 In response to certain requests from the client to either the client 542 registration endpoint as described in this specification, the 543 authorization server sends the following response bodies. 545 5.1. Client Information Response 547 The response contains the client identifier as well as the client 548 secret, if the client is a confidential client. The response MAY 549 contain additional fields as specified by extensions to this 550 specification. 552 client_id REQUIRED. Unique client identifier. It MUST NOT be 553 currently valid for any other distinct registered client. It MAY 554 be the same as the Client ID value used by other instances of this 555 client, provided that the Redirection URI values and potentially 556 other values dictated by authorization server policy are the same 557 for all instances. 559 client_secret OPTIONAL. The client secret. If issued, this MUST be 560 unique for each "client_id". This value is used by confidential 561 clients to authenticate to the token endpoint as described in 562 OAuth 2.0 [RFC6749] Section 2.3.1. 564 client_id_issued_at OPTIONAL. Time at which the Client Identifier 565 was issued. The time is represented as the number of seconds from 566 1970-01-01T0:0:0Z as measured in UTC until the date/time. 568 client_secret_expires_at REQUIRED if "client_secret" is issued. 569 Time at which the "client_secret" will expire or 0 if it will not 570 expire. The time is represented as the number of seconds from 571 1970-01-01T0:0:0Z as measured in UTC until the date/time. 573 Additionally, the Authorization Server MUST return all registered 574 metadata about this client, including any fields provisioned by the 575 authorization server itself. The authorization server MAY reject or 576 replace any of the client's requested metadata values submitted 577 during the registration or update requests and substitute them with 578 suitable values. 580 The response is an "application/json" document with all parameters as 581 top-level members of a JSON object [RFC4627]. 583 If a software statement was used as part of the registration, its 584 value SHOULD be returned in the response. Client metadata elements 585 used from the software statement SHOULD also be returned directly as 586 top-level client metadata values in the registration response. 588 Following is a non-normative example response: 590 HTTP/1.1 200 OK 591 Content-Type: application/json 592 Cache-Control: no-store 593 Pragma: no-cache 595 { 596 "client_id":"s6BhdRkqt3", 597 "client_secret": "cf136dc3c1fc93f31185e5885805d", 598 "client_id_issued_at":2893256800, 599 "client_secret_expires_at":2893276800, 600 "redirect_uris":[ 601 "https://client.example.org/callback", 602 "https://client.example.org/callback2"], 603 "grant_types": ["authorization_code", "refresh_token"], 604 "token_endpoint_auth_method": "client_secret_basic", 605 "example_extension_parameter": "example_value" 606 } 608 5.2. Client Registration Error Response 610 When an OAuth 2.0 error condition occurs, such as the client 611 presenting an invalid initial access token, the authorization server 612 returns an error response appropriate to the OAuth 2.0 token type. 614 When a registration error condition occurs, the authorization server 615 returns an HTTP 400 status code (unless otherwise specified) with 616 content type "application/json" consisting of a JSON object [RFC4627] 617 describing the error in the response body. 619 The JSON object contains two members: 621 error Single ASCII error code string. 623 error_description Human-readable ASCII text description of the error 624 used for debugging. 626 This specification defines the following error codes: 628 invalid_redirect_uri The value of one or more "redirect_uris" is 629 invalid. 631 invalid_client_metadata The value of one of the client metadata 632 fields is invalid and the server has rejected this request. Note 633 that an Authorization server MAY choose to substitute a valid 634 value for any requested parameter of a client's metadata. 636 invalid_software_statement The software statement presented is 637 invalid. 639 unapproved_software_statement The software statement presented is 640 not approved for use with this authorization server. 642 Following is a non-normative example of an error response (with line 643 wraps for display purposes only): 645 HTTP/1.1 400 Bad Request 646 Content-Type: application/json 647 Cache-Control: no-store 648 Pragma: no-cache 650 { 651 "error":"invalid_redirect_uri", 652 "error_description":"The redirect URI http://sketchy.example.com 653 is not allowed for this server." 654 } 656 6. IANA Considerations 658 6.1. OAuth Registration Client Metadata Registry 660 This specification establishes the OAuth Registration Client Metadata 661 registry. 663 OAuth registration client metadata values are registered with a 664 Specification Required ([RFC5226]) after a two-week review period on 665 the oauth-ext-review@ietf.org mailing list, on the advice of one or 666 more Designated Experts. However, to allow for the allocation of 667 values prior to publication, the Designated Expert(s) may approve 668 registration once they are satisfied that such a specification will 669 be published. 671 Registration requests must be sent to the oauth-ext-review@ietf.org 672 mailing list for review and comment, with an appropriate subject 673 (e.g., "Request to register OAuth Registration Client Metadata name: 674 example"). 676 Within the review period, the Designated Expert(s) will either 677 approve or deny the registration request, communicating this decision 678 to the review list and IANA. Denials should include an explanation 679 and, if applicable, suggestions as to how to make the request 680 successful. 682 IANA must only accept registry updates from the Designated Expert(s) 683 and should direct all requests for registration to the review mailing 684 list. 686 6.1.1. Registration Template 688 Client Metadata Name: The name requested (e.g., "example"). This 689 name is case sensitive. Names that match other registered names 690 in a case insensitive manner SHOULD NOT be accepted. 692 Client Metadata Description: 693 Brief description of the metadata value (e.g., "Example 694 description"). 696 Change controller: For Standards Track RFCs, state "IETF". For 697 others, give the name of the responsible party. Other details 698 (e.g., postal address, email address, home page URI) may also be 699 included. 701 Specification document(s): Reference to the document(s) that specify 702 the token endpoint authorization method, preferably including a 703 URI that can be used to retrieve a copy of the document(s). An 704 indication of the relevant sections may also be included but is 705 not required. 707 6.1.2. Initial Registry Contents 709 The initial contents of the OAuth Registration Client Metadata 710 registry are: 712 o Client Metadata Name: "redirect_uris" 713 o Client Metadata Description: Array of redirect URIs for use in 714 redirect-based flows 715 o Change controller: IESG 716 o Specification document(s): [[ this document ]] 718 o Client Metadata Name: "token_endpoint_auth_method" 719 o Client Metadata Description: Requested authentication method for 720 the token endpoint 721 o Change controller: IESG 722 o Specification document(s): [[ this document ]] 724 o Client Metadata Name: "grant_types" 725 o Client Metadata Description: Array of OAuth 2.0 grant types that 726 the Client may use 727 o Change controller: IESG 728 o Specification document(s): [[ this document ]] 729 o Client Metadata Name: "response_types" 730 o Client Metadata Description: Array of the OAuth 2.0 response types 731 that the Client may use 732 o Change controller: IESG 733 o Specification document(s): [[ this document ]] 735 6.2. OAuth Token Endpoint Authentication Methods Registry 737 This specification establishes the OAuth Token Endpoint 738 Authentication Methods registry. 740 Additional values for use as "token_endpoint_auth_method" metadata 741 values are registered with a Specification Required ([RFC5226]) after 742 a two-week review period on the oauth-ext-review@ietf.org mailing 743 list, on the advice of one or more Designated Experts. However, to 744 allow for the allocation of values prior to publication, the 745 Designated Expert(s) may approve registration once they are satisfied 746 that such a specification will be published. 748 Registration requests must be sent to the oauth-ext-review@ietf.org 749 mailing list for review and comment, with an appropriate subject 750 (e.g., "Request to register token_endpoint_auth_method value: 751 example"). 753 Within the review period, the Designated Expert(s) will either 754 approve or deny the registration request, communicating this decision 755 to the review list and IANA. Denials should include an explanation 756 and, if applicable, suggestions as to how to make the request 757 successful. 759 IANA must only accept registry updates from the Designated Expert(s) 760 and should direct all requests for registration to the review mailing 761 list. 763 6.2.1. Registration Template 765 Token Endpoint Authorization Method Name: The name requested (e.g., 766 "example"). This name is case sensitive. Names that match other 767 registered names in a case insensitive manner SHOULD NOT be 768 accepted. 770 Change controller: For Standards Track RFCs, state "IETF". For 771 others, give the name of the responsible party. Other details 772 (e.g., postal address, email address, home page URI) may also be 773 included. 775 Specification document(s): Reference to the document(s) that specify 776 the token endpoint authorization method, preferably including a 777 URI that can be used to retrieve a copy of the document(s). An 778 indication of the relevant sections may also be included but is 779 not required. 781 6.2.2. Initial Registry Contents 783 The initial contents of the OAuth Token Endpoint Authentication 784 Methods registry are: 786 o Token Endpoint Authorization Method Name: "none" 787 o Change controller: IESG 788 o Specification document(s): [[ this document ]] 790 o Token Endpoint Authorization Method Name: "client_secret_post" 791 o Change controller: IESG 792 o Specification document(s): [[ this document ]] 794 o Token Endpoint Authorization Method Name: "client_secret_basic" 795 o Change controller: IESG 796 o Specification document(s): [[ this document ]] 798 7. Security Considerations 800 Since requests to the client registration endpoint result in the 801 transmission of clear-text credentials (in the HTTP request and 802 response), the Authorization Server MUST require the use of a 803 transport-layer security mechanism when sending requests to the 804 registration endpoint. The server MUST support TLS 1.2 RFC 5246 805 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 806 transport-layer mechanisms meeting its security requirements. When 807 using TLS, the Client MUST perform a TLS/SSL server certificate 808 check, per RFC 6125 [RFC6125]. 810 For clients that use redirect-based grant types such as 811 "authorization_code" and "implicit", authorization servers SHOULD 812 require clients to register their "redirect_uris". Requiring clients 813 to do so can help mitigate attacks where rogue actors inject and 814 impersonate a validly registered client and intercept its 815 authorization code or tokens through an invalid redirect URI. 817 Public clients MAY register with an authorization server using this 818 protocol, if the authorization server's policy allows them. Public 819 clients use a "none" value for the "token_endpoint_auth_method" 820 metadata field and are generally used with the "implicit" grant type. 821 Often these clients will be short-lived in-browser applications 822 requesting access to a user's resources and access is tied to a 823 user's active session at the authorization server. Since such 824 clients often do not have long-term storage, it's possible that such 825 clients would need to re-register every time the browser application 826 is loaded. Additionally, such clients may not have ample opportunity 827 to unregister themselves using the delete action before the browser 828 closes. To avoid the resulting proliferation of dead client 829 identifiers, an authorization server MAY decide to expire 830 registrations for existing clients meeting certain criteria after a 831 period of time has elapsed. 833 Since different OAuth 2.0 grant types have different security and 834 usage parameters, an authorization server MAY require separate 835 registrations for a piece of software to support multiple grant 836 types. For instance, an authorization server might require that all 837 clients using the "authorization_code" grant type make use of a 838 client secret for the "token_endpoint_auth_method", but any clients 839 using the "implicit" grant type do not use any authentication at the 840 token endpoint. In such a situation, a server MAY disallow clients 841 from registering for both the "authorization_code" and "implicit" 842 grant types simultaneously. Similarly, the "authorization_code" 843 grant type is used to represent access on behalf of an end user, but 844 the "client_credentials" grant type represents access on behalf of 845 the client itself. For security reasons, an authorization server 846 could require that different scopes be used for these different use 847 cases, and as a consequence it MAY disallow these two grant types 848 from being registered together by the same client. In all of these 849 cases, the authorization server would respond with an 850 "invalid_client_metadata" error response. 852 8. References 854 8.1. Normative References 856 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 857 (JWT)", draft-ietf-oauth-json-web-token (work in 858 progress), January 2014. 860 [OAuth.JWT] 861 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 862 (JWT) Profile for OAuth 2.0 Client Authentication and 863 Authorization Grants", draft-ietf-oauth-jwt-bearer (work 864 in progress), December 2013. 866 [OAuth.SAML2] 867 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 868 Profile for OAuth 2.0 Client Authentication and 869 Authorization Grants", draft-ietf-oauth-saml2-bearer (work 870 in progress), December 2013. 872 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 873 Requirement Levels", BCP 14, RFC 2119, March 1997. 875 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 876 RFC 2246, January 1999. 878 [RFC4627] Crockford, D., "The application/json Media Type for 879 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 881 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 882 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 883 May 2008. 885 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 886 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 888 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 889 Verification of Domain-Based Application Service Identity 890 within Internet Public Key Infrastructure Using X.509 891 (PKIX) Certificates in the Context of Transport Layer 892 Security (TLS)", RFC 6125, March 2011. 894 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 895 RFC 6749, October 2012. 897 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 898 Framework: Bearer Token Usage", RFC 6750, October 2012. 900 8.2. Informative References 902 [OAuth.Registration.Management] 903 Richer, J., Jones, M., Bradley, J., and M. Machulak, 904 "OAuth 2.0 Dynamic Client Registration Management 905 Protocol", draft-jones-oauth-dyn-reg-management (work in 906 progress), January 2014. 908 [OAuth.Registration.Metadata] 909 Richer, J., Jones, M., Bradley, J., and M. Machulak, 910 "OAuth 2.0 Dynamic Client Registration Metadata", 911 draft-jones-oauth-dyn-reg-metadata (work in progress), 912 January 2014. 914 Appendix A. Use Cases 916 This appendix describes different ways that this specification can be 917 utilized, including describing some of the choices that may need to 918 be made. Some of the choices are independent and can be used in 919 combination, whereas some of the choices are interrelated. 921 A.1. Open versus Protected Dynamic Client Registration 923 A.1.1. Open Dynamic Client Registration 925 Authorization servers that support open registration allow 926 registrations to be made with no initial access token. This allows 927 all client software to register with the authorization server. 929 A.1.2. Protected Dynamic Client Registration 931 Authorization servers that support protected registration require 932 that an initial access token be used when making registration 933 requests. While the method by which a client or developer receives 934 this initial access token and the method by which the authorization 935 server validates this initial access token are out of scope for this 936 specification, a common approach is for the developer to use a manual 937 pre-registration portal at the authorization server that issues an 938 initial access token to the developer. 940 A.2. Registration without or with Software Statements 942 A.2.1. Registration without a Software Statement 944 When a software statement is not used in the registration request, 945 the authorization server must be willing to use client metadata 946 values without them being signed (and thereby attested to) by any 947 authority. (Note that this choice is independent of the Open versus 948 Protected choice, and that an initial access token is another 949 possible form of attestation.) 951 A.2.2. Registration with a Software Statement 953 A software statement can be used in a registration request to provide 954 attestation for a set of client metadata values for a piece of client 955 software by an authority. This can be useful when the authorization 956 server wants to restrict registration to client software attested to 957 by a set of authorities or when it wants to know that multiple 958 registration requests refer to the same piece of client software. 960 A.3. Registration by the Client or the Developer 962 A.3.1. Registration by the Client 964 In some use cases, client software will dynamically register itself 965 with an authorization server to obtain a Client ID and other 966 information needed to interact with the authorization server. In 967 this case, no Client ID for the authorization server is packaged with 968 the client software. 970 A.3.2. Registration by the Developer 972 In some cases, the developer (or development software being used by 973 the developer) will pre-register the client software with the 974 authorization server or a set of authorization servers. In this 975 case, the Client ID value(s) for the authorization server(s) can be 976 packaged with the client software. 978 A.4. Client ID per Client Instance or per Client Software 980 A.4.1. Client ID per Client Software Instance 982 In some cases, each deployed instance of a piece of client software 983 will dynamically register and obtain distinct Client ID values. This 984 can be advantageous, for instance, if the code flow is being used, as 985 it also enables each client instance to have its own client secret. 986 This can be useful for native clients, which cannot maintain the 987 secrecy of a client secret value packaged with the software, but 988 which may be able to maintain the secrecy of a per-instance client 989 secret. 991 A.4.2. Client ID Shared between all Instances of Client Software 993 In some cases, each deployed instance of a piece of client software 994 will share a common Client ID value. For instance, this is often the 995 case for native client using implicit flow, when no client secret is 996 involved. Particular authorization servers might choose, for 997 instance, to maintain a mapping between software statement values and 998 Client ID values, and return the same Client ID value for all 999 registration requests for a particular piece of software. The 1000 circumstances under which an authorization server would do so, and 1001 the specific software statement characteristics required in this 1002 case, are beyond the scope of this specification. 1004 A.5. Stateful or Stateless Registration 1005 A.5.1. Stateful Client Registration 1007 In some cases, authorization servers will maintain state about 1008 registered clients, typically indexing this state using the Client ID 1009 value. This state would typically include the client metadata values 1010 associated with the client registration, and possibly other state 1011 specific to the authorization server's implementation. When stateful 1012 registration is used, operations to support retrieving and/or 1013 updating this state may be supported, as described in the 1014 [OAuth.Registration.Management] specification. 1016 A.5.2. Stateless Client Registration 1018 In some cases, authorization servers will be implemented in a manner 1019 the enables them to not maintain any local state about registered 1020 clients. One means of doing this is to encode all the registration 1021 state in the returned Client ID value, and possibly encrypting the 1022 state to the authorization server to maintain the confidentiality and 1023 integrity of the state. 1025 Appendix B. Acknowledgments 1027 The authors thank the OAuth Working Group, the User-Managed Access 1028 Working Group, and the OpenID Connect Working Group participants for 1029 their input to this document. In particular, the following 1030 individuals have been instrumental in their review and contribution 1031 to various versions of this document: Amanda Anganes, Derek Atkins, 1032 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 1033 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 1034 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Tony Nadalin, Nat 1035 Sakimura, Christian Scholz, and Hannes Tschofenig. 1037 Appendix C. Document History 1039 [[ to be removed by the RFC editor before publication as an RFC ]] 1041 -15 1043 o Partitioned the Dynamic Client Registration specification into 1044 core, metadata, and management specifications. This built on work 1045 first published as draft-richer-oauth-dyn-reg-core-00 and 1046 draft-richer-oauth-dyn-reg-management-00. 1048 o Added the ability to use Software Statements. This built on work 1049 first published as draft-hunt-oauth-software-statement-00 and 1050 draft-hunt-oauth-client-association-00. 1052 o Created the IANA OAuth Registration Client Metadata registry for 1053 registering Client Metadata values. 1055 o Defined Client Instance term and stated that multiple instances 1056 can use the same Client ID value under certain circumstances. 1058 o Rewrote the introduction. 1060 o Rewrote the Use Cases appendix. 1062 -14 1064 o Added software_id and software_version metadata fields 1066 o Added direct references to RFC6750 errors in read/update/delete 1067 methods 1069 -13 1071 o Fixed broken example text in registration request and in delete 1072 request 1074 o Added security discussion of separating clients of different grant 1075 types 1077 o Fixed error reference to point to RFC6750 instead of RFC6749 1079 o Clarified that servers must respond to all requests to 1080 configuration endpoint, even if it's just an error code 1082 o Lowercased all Terms to conform to style used in RFC6750 1084 -12 1086 o Improved definition of Initial Access Token 1088 o Changed developer registration scenario to have the Initial Access 1089 Token gotten through a normal OAuth 2.0 flow 1091 o Moved non-normative client lifecycle examples to appendix 1093 o Marked differentiating between auth servers as out of scope 1095 o Added protocol flow diagram 1097 o Added credential rotation discussion 1098 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 1099 Resource 1101 o Cleaned up several pieces of text 1103 -11 1105 o Added localized text to registration request and response 1106 examples. 1108 o Removed "client_secret_jwt" and "private_key_jwt". 1110 o Clarified "tos_uri" and "policy_uri" definitions. 1112 o Added the OAuth Token Endpoint Authentication Methods registry for 1113 registering "token_endpoint_auth_method" metadata values. 1115 o Removed uses of non-ASCII characters, per RFC formatting rules. 1117 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1118 to "client_id_issued_at" for greater clarity. 1120 o Added explanatory text for different credentials (Initial Access 1121 Token, Registration Access Token, Client Credentials) and what 1122 they're used for. 1124 o Added Client Lifecycle discussion and examples. 1126 o Defined Initial Access Token in Terminology section. 1128 -10 1130 o Added language to point out that scope values are service-specific 1132 o Clarified normative language around client metadata 1134 o Added extensibility to token_endpoint_auth_method using absolute 1135 URIs 1137 o Added security consideration about registering redirect URIs 1139 o Changed erroneous 403 responses to 401's with notes about token 1140 handling 1142 o Added example for initial registration credential 1144 -09 1145 o Added method of internationalization for Client Metadata values 1147 o Fixed SAML reference 1149 -08 1151 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1152 x509_encryption_uri into a single jwks_uri parameter 1154 o Renamed grant_type to grant_types since it's a plural value 1156 o Formalized name of "OAuth 2.0" throughout document 1158 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1159 grant types 1161 o Added response_types parameter and explanatory text on its use 1162 with and relationship to grant_types 1164 -07 1166 o Changed registration_access_url to registration_client_uri 1168 o Fixed missing text in 5.1 1170 o Added Pragma: no-cache to examples 1172 o Changed "no such client" error to 403 1174 o Renamed Client Registration Access Endpoint to Client 1175 Configuration Endpoint 1177 o Changed all the parameter names containing "_url" to instead use 1178 "_uri" 1180 o Updated example text for forming Client Configuration Endpoint URL 1182 -06 1184 o Removed secret_rotation as a client-initiated action, including 1185 removing client secret rotation endpoint and parameters. 1187 o Changed _links structure to single value registration_access_url. 1189 o Collapsed create/update/read responses into client info response. 1191 o Changed return code of create action to 201. 1193 o Added section to describe suggested generation and composition of 1194 Client Registration Access URL. 1196 o Added clarifying text to PUT and POST requests to specify JSON in 1197 the body. 1199 o Added Editor's Note to DELETE operation about its inclusion. 1201 o Added Editor's Note to registration_access_url about alternate 1202 syntax proposals. 1204 -05 1206 o changed redirect_uri and contact to lists instead of space 1207 delimited strings 1209 o removed operation parameter 1211 o added _links structure 1213 o made client update management more RESTful 1215 o split endpoint into three parts 1217 o changed input to JSON from form-encoded 1219 o added READ and DELETE operations 1221 o removed Requirements section 1223 o changed token_endpoint_auth_type back to 1224 token_endpoint_auth_method to match OIDC who changed to match us 1226 -04 1228 o removed default_acr, too undefined in the general OAuth2 case 1230 o removed default_max_auth_age, since there's no mechanism for 1231 supplying a non-default max_auth_age in OAuth2 1233 o clarified signing and encryption URLs 1235 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1236 match OIDC 1238 -03 1239 o added scope and grant_type claims 1241 o fixed various typos and changed wording for better clarity 1243 o endpoint now returns the full set of client information 1245 o operations on client_update allow for three actions on metadata: 1246 leave existing value, clear existing value, replace existing value 1247 with new value 1249 -02 1251 o Reorganized contributors and references 1253 o Moved OAuth references to RFC 1255 o Reorganized model/protocol sections for clarity 1257 o Changed terminology to "client register" instead of "client 1258 associate" 1260 o Specified that client_id must match across all subsequent requests 1262 o Fixed RFC2XML formatting, especially on lists 1264 -01 1266 o Merged UMA and OpenID Connect registrations into a single document 1268 o Changed to form-parameter inputs to endpoint 1270 o Removed pull-based registration 1272 -00 1274 o Imported original UMA draft specification 1276 Authors' Addresses 1278 Justin Richer 1279 The MITRE Corporation 1281 Email: jricher@mitre.org 1282 Michael B. Jones 1283 Microsoft 1285 Email: mbj@microsoft.com 1286 URI: http://self-issued.info/ 1288 John Bradley 1289 Ping Identity 1291 Email: ve7jtb@ve7jtb.com 1293 Maciej Machulak 1294 Newcastle University 1296 Email: m.p.machulak@ncl.ac.uk 1297 URI: http://ncl.ac.uk/