idnits 2.17.1 draft-richer-oauth-dyn-reg-core-00.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 (August 26, 2013) is 3893 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) == Unused Reference: 'JWK' is defined on line 633, but no explicit reference was found in the text == Unused Reference: 'RFC2616' is defined on line 652, but no explicit reference was found in the text == Unused Reference: 'RFC4122' is defined on line 656, but no explicit reference was found in the text == Unused Reference: 'RFC5646' is defined on line 670, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** 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: 6 errors (**), 0 flaws (~~), 7 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 The MITRE Corporation 4 Intended status: Standards Track J. Bradley 5 Expires: February 27, 2014 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 August 26, 2013 12 OAuth 2.0 Core Dynamic Client Registration 13 draft-richer-oauth-dyn-reg-core-00 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth 2.0 clients at an authorization server. 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 February 27, 2014. 37 Copyright Notice 39 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.3. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 3 58 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. Relationship Between Grant Types and Response Types . . . 6 60 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 7 61 3.1. Client Registration Request . . . . . . . . . . . . . . . 8 62 3.2. Client Registration Response . . . . . . . . . . . . . . 9 63 4. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 4.1. Client Information Response . . . . . . . . . . . . . . . 9 65 4.2. Client Registration Error Response . . . . . . . . . . . 10 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 67 5.1. OAuth Token Endpoint Authentication Methods Registry . . 12 68 5.1.1. Registration Template . . . . . . . . . . . . . . . . 12 69 5.1.2. Initial Registry Contents . . . . . . . . . . . . . . 12 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . 13 71 7. Normative References . . . . . . . . . . . . . . . . . . . . 14 72 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 15 73 Appendix B. Use Cases . . . . . . . . . . . . . . . . . . . . . 16 74 B.1. Open Registration . . . . . . . . . . . . . . . . . . . . 17 75 B.2. Stateless Open Registration using JWT . . . . . . . . . . 18 76 B.3. Protected Registration . . . . . . . . . . . . . . . . . 19 77 B.4. Developer Automation . . . . . . . . . . . . . . . . . . 20 78 Appendix C. Document History . . . . . . . . . . . . . . . . . . 21 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 81 1. Introduction 83 In some use-case scenarios, it is desirable or necessary to allow 84 OAuth 2.0 clients to obtain authorization from an OAuth 2.0 85 authorization server without requiring the two parties to interact 86 beforehand. Nevertheless, for the authorization server to accurately 87 and securely represent to end-users which client is seeking 88 authorization to access the end-user's resources, a method for 89 automatic and unique registration of clients is needed. The OAuth 90 2.0 authorization framework does not define how the relationship 91 between the client and the authorization server is initialized, or 92 how a given client is assigned a unique client identifier. 93 Historically, this has happened out-of-band from the OAuth 2.0 94 protocol. This draft provides a mechanism for a client to register 95 itself with the authorization server, which can be used to 96 dynamically provision a client identifier, and optionally a client 97 secret. Additionally, the mechanisms in this draft may can be used 98 by a client developer to register the client with the authorization 99 server in a programmatic fashion. 101 As part of the registration process, this specification also defines 102 a mechanism for the client to present the authorization server with a 103 set of metadata, such as a set of valid redirect URIs. 105 1.1. Notational Conventions 107 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 108 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 109 document are to be interpreted as described in [RFC2119]. 111 Unless otherwise noted, all the protocol parameter names and values 112 are case sensitive. 114 1.2. Terminology 116 This specification uses the terms "Access Token", "Refresh Token", 117 "Authorization Code", "Authorization Grant", "Authorization Server", 118 "Authorization Endpoint", "Client", "Client Identifier", "Client 119 Secret", "Protected Resource", "Resource Owner", "Resource Server", 120 and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. 122 This specification defines the following additional terms: 124 Client Registration Endpoint OAuth 2.0 endpoint through which a 125 client can be registered at an authorization server. The means by 126 which the URL for this endpoint are obtained are out of scope for 127 this specification. 128 Initial Access Token OAuth 2.0 access token optionally issued by an 129 Authorization Server and used to authorize calls to the client 130 registration endpoint. The type and format of this token are 131 likely service-specific and are out of scope for this 132 specification. The means by which the authorization server issues 133 this token as well as the means by which the registration endpoint 134 validates this token are out of scope for this specification. 136 1.3. Protocol Flow 138 +--------(A)- Initial Access Token 139 | 140 v 141 +-----------+ +---------------+ 142 | |--(B)- Client Registration Request -->| Client | 143 | Client or | | Registration | 144 | Developer |<-(C)- Client Information Response ---| Endpoint | 145 | | +---------------+ 146 +-----------+ 148 Figure 1: Abstract Protocol Flow 150 The abstract OAuth 2.0 Client dynamic registration flow illustrated 151 in Figure 1 describes the interaction between the client or developer 152 and the endpoint defined in this specification. This figure does not 153 demonstrate error conditions. This flow includes the following 154 steps: 156 (A) 157 Optionally, the client or developer is issued an initial access 158 token for use with the client registration endpoint. The method 159 by which the initial access token is issued to the client or 160 developer is out of scope for this specification. 161 (B) 162 The client or developer calls the client registration endpoint 163 with its desired registration metadata, optionally including the 164 initial access token from (A) if one is required by the 165 authorization server. 166 (C) 167 The authorization server registers the client and returns the 168 client's registered metadata, a client identifier that is unique 169 at the server, a set of client credentials such as a client secret 170 if applicable for this client, and possibly other values. 172 2. Client Metadata 174 Clients generally have an array of metadata associated with their 175 unique client identifier at the authorization server, such as the 176 list of valid redirect URIs. 178 The client metadata values serve two parallel purposes in the overall 179 OAuth 2.0 dynamic client registration protocol: 181 o the client requesting its desired values for each parameter to the 182 authorization server in a register (Section 3.1) request, and 183 o the authorization server informing the client of the current 184 values of each parameter that the client has been registered to 185 use through a client information response (Section 4.1). 187 An authorization server MAY override any value that a client requests 188 during the registration process (including any omitted values) and 189 replace the requested value with a default at the server's 190 discretion. The authorization server SHOULD provide documentation 191 for any fields that it requires to be filled in by the client or to 192 have particular values or formats. An authorization server MAY 193 ignore the values provided by the client for any field in this list. 195 Extensions and profiles of this specification MAY expand this list, 196 and authorization servers MUST accept all fields in this list. The 197 authorization server MUST ignore any additional parameters sent by 198 the Client that it does not understand. 200 redirect_uris 201 Array of redirect URIs for use in redirect-based flows such as the 202 authorization code and implicit grant types. It is RECOMMENDED 203 that clients using these flows register this parameter, and an 204 authorization server SHOULD require registration of valid redirect 205 URIs for all clients that use these grant types to protect against 206 token and credential theft attacks. 207 token_endpoint_auth_method 208 The requested authentication method for the token endpoint. 209 Values defined by this specification are: 211 * "none": The client is a public client as defined in OAuth 2.0 212 and does not have a client secret. 213 * "client_secret_post": The client uses the HTTP POST parameters 214 defined in OAuth 2.0 section 2.3.1. 215 * "client_secret_basic": the client uses HTTP Basic defined in 216 OAuth 2.0 section 2.3.1 218 Additional values can be defined via the IANA OAuth Token Endpoint 219 Authentication Methods Registry Section 5.1. Absolute URIs can 220 also be used as values for this parameter without being 221 registered. If unspecified or omitted, the default is 222 "client_secret_basic", denoting HTTP Basic Authentication Scheme 223 as specified in Section 2.3.1 of OAuth 2.0. 224 grant_types 225 Array of OAuth 2.0 grant types that the Client may use. These 226 grant types are defined as follows: 228 * "authorization_code": The Authorization Code Grant described in 229 OAuth 2.0 Section 4.1 230 * "implicit": The Implicit Grant described in OAuth 2.0 231 Section 4.2 232 * "password": The Resource Owner Password Credentials Grant 233 described in OAuth 2.0 Section 4.3 234 * "client_credentials": The Client Credentials Grant described in 235 OAuth 2.0 Section 4.4 236 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 237 Section 6. 239 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 240 Grant defined in OAuth JWT Bearer Token Profiles [OAuth.JWT]. 241 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 242 Bearer Grant defined in OAuth SAML 2 Bearer Token Profiles 243 [OAuth.SAML2]. 245 Authorization Servers MAY allow for other values as defined in 246 grant type extensions to OAuth 2.0. The extension process is 247 described in OAuth 2.0 Section 2.5. If the token endpoint is used 248 in the grant type, the value of this parameter MUST be the same as 249 the value of the "grant_type" parameter passed to the token 250 endpoint defined in the extension. 251 response_types 252 Array of the OAuth 2.0 response types that the Client may use. 253 These response types are defined as follows: 255 * "code": The Authorization Code response described in OAuth 2.0 256 Section 4.1. 257 * "token": The Implicit response described in OAuth 2.0 258 Section 4.2. 260 Authorization servers MAY allow for other values as defined in 261 response type extensions to OAuth 2.0. The extension process is 262 described in OAuth 2.0 Section 2.5. If the authorization endpoint 263 is used by the grant type, the value of this parameter MUST be the 264 same as the value of the "response_type" parameter passed to the 265 authorization endpoint defined in the extension. 267 2.1. Relationship Between Grant Types and Response Types 269 The "grant_types" and "response_types" values described above are 270 partially orthogonal, as they refer to arguments passed to different 271 endpoints in the OAuth protocol. However, they are related in that 272 the "grant_types" available to a client influence the 273 "response_types" that the client is allowed to use, and vice versa. 274 For instance, a "grant_types" value that includes 275 "authorization_code" implies a "response_types" value that includes 276 "code", as both values are defined as part of the OAuth 2.0 277 authorization code grant. As such, a server supporting these fields 278 SHOULD take steps to ensure that a client cannot register itself into 279 an inconsistent state. 281 The correlation between the two fields is listed in the table below. 283 +-------------------------------------------------+-----------------+ 284 | grant_types value includes: | response_types | 285 | | value includes: | 286 +-------------------------------------------------+-----------------+ 287 | authorization_code | code | 288 | implicit | token | 289 | password | (none) | 290 | client_credentials | (none) | 291 | refresh_token | (none) | 292 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 293 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 294 +-------------------------------------------------+-----------------+ 296 Extensions and profiles of this document that introduce new values to 297 either the "grant_types" or "response_types" parameter MUST document 298 all correspondences between these two parameter types. 300 3. Client Registration Endpoint 302 The client registration endpoint is an OAuth 2.0 endpoint defined in 303 this document that is designed to allow a client to be registered 304 with the authorization server. The client registration endpoint MUST 305 accept HTTP POST messages with request parameters encoded in the 306 entity body using the "application/json" format. The client 307 registration endpoint MUST be protected by a transport-layer security 308 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 309 /or TLS 1.0 [RFC2246] and MAY support additional transport-layer 310 mechanisms meeting its security requirements. When using TLS, the 311 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 312 [RFC6125]. 314 The client registration endpoint MAY be an OAuth 2.0 protected 315 resource and accept an initial access token in the form of an OAuth 316 2.0 [RFC6749] access token to limit registration to only previously 317 authorized parties. The method by which the initial access token is 318 obtained by the registrant is generally out-of-band and is out of 319 scope for this specification. The method by which the initial access 320 token is verified and validated by the client registration endpoint 321 is out of scope for this specification. 323 To support open registration and facilitate wider interoperability, 324 the client registration endpoint SHOULD allow initial registration 325 requests with no authorization (which is to say, with no OAuth 2.0 326 access token in the request). These requests MAY be rate-limited or 327 otherwise limited to prevent a denial-of-service attack on the client 328 registration endpoint. 330 The client registration endpoint MUST ignore all parameters it does 331 not understand. 333 3.1. Client Registration Request 335 This operation registers a new client to the authorization server. 336 The authorization server assigns this client a unique client 337 identifier, optionally assigns a client secret, and associates the 338 metadata given in the request with the issued client identifier. The 339 request includes any parameters described in Client Metadata 340 (Section 2) that the client wishes to specify for itself during the 341 registration. The authorization server MAY provision default values 342 for any items omitted in the client metadata. 344 To register, the client or developer sends an HTTP POST to the client 345 registration endpoint with a content type of "application/json". The 346 HTTP Entity Payload is a JSON [RFC4627] document consisting of a JSON 347 object and all parameters as top-level members of that JSON object. 349 For example, if the server supports open registration (with no 350 initial access token), the client could send the following 351 registration request to the client registration endpoint: 353 Following is a non-normative example request (with line wraps for 354 display purposes only): 356 POST /register HTTP/1.1 357 Content-Type: application/json 358 Accept: application/json 359 Host: server.example.com 361 { 362 "redirect_uris":["https://client.example.org/callback", 363 "https://client.example.org/callback2"], 364 "token_endpoint_auth_method":"client_secret_basic", 365 "scope":"read write dolphin", 366 "extension_parameter":"foo" 367 } 369 Alternatively, if the server supports authorized registration, the 370 developer or the client will be provisioned with an initial access 371 token (the method by which the initial access token is obtained is 372 out of scope for this specification). The developer or client sends 373 the following authorized registration request to the client 374 registration endpoint. Note that the initial access token sent in 375 this example as an OAuth 2.0 Bearer Token [RFC6750], but any OAuth 376 2.0 token type could be used by an authorization server: 378 Following is a non-normative example request (with line wraps for 379 display purposes only): 381 POST /register HTTP/1.1 382 Content-Type: application/json 383 Accept: application/json 384 Authorization: Bearer ey23f2.adfj230.af32-developer321 385 Host: server.example.com 387 { 388 "redirect_uris":["https://client.example.org/callback", 389 "https://client.example.org/callback2"], 390 "token_endpoint_auth_method":"client_secret_basic", 391 "scope":"read write dolphin", 392 "extension_parameter":"foo" 393 } 395 3.2. Client Registration Response 397 Upon successful registration, the authorization server generates a 398 new client identifier for the client. This client identifier MUST be 399 unique at the server and MUST NOT be in use by any other client. The 400 server responds with an HTTP 201 Created code and a body of type 401 "application/json" with content described in Client Information 402 Response (Section 4.1). 404 Upon an unsuccessful registration, the authorization server responds 405 with an error as described in Client Registration Error 406 (Section 4.2). 408 4. Responses 410 In response to certain requests from the client to either the client 411 registration endpoint as described in this specification, the 412 authorization server sends the following response bodies. 414 4.1. Client Information Response 416 The response contains the client identifier as well as the client 417 secret, if the client is a confidential client. The response MAY 418 contain additional fields as specified by extensions to this 419 specification. 421 client_id 422 REQUIRED. The unique client identifier, MUST NOT be currently 423 valid for any other registered client. 424 client_secret 425 OPTIONAL. The client secret. If issued, this MUST be unique for 426 each "client_id". This value is used by confidential clients to 427 authenticate to the token endpoint as described in OAuth 2.0 428 [RFC6749] Section 2.3.1. 429 client_id_issued_at 430 OPTIONAL. Time at which the Client Identifier was issued. The 431 time is represented as the number of seconds from 432 1970-01-01T0:0:0Z as measured in UTC until the date/time. 433 client_secret_expires_at 434 REQUIRED if "client_secret" is issued. Time at which the 435 "client_secret" will expire or 0 if it will not expire. The time 436 is represented as the number of seconds from 1970-01-01T0:0:0Z as 437 measured in UTC until the date/time. 439 Additionally, the Authorization Server MUST return all registered 440 metadata (Section 2) about this client, including any fields 441 provisioned by the authorization server itself. The authorization 442 server MAY reject or replace any of the client's requested metadata 443 values submitted during the registration or update requests and 444 substitute them with suitable values. 446 The response is an "application/json" document with all parameters as 447 top-level members of a JSON object [RFC4627]. 449 Following is a non-normative example response: 451 HTTP/1.1 200 OK 452 Content-Type: application/json 453 Cache-Control: no-store 454 Pragma: no-cache 456 { 457 "client_id":"s6BhdRkqt3", 458 "client_secret": "cf136dc3c1fc93f31185e5885805d", 459 "client_id_issued_at":2893256800 460 "client_secret_expires_at":2893276800 461 "redirect_uris":["https://client.example.org/callback", 462 "https://client.example.org/callback2"] 463 "scope": "read write dolphin", 464 "grant_types": ["authorization_code", "refresh_token"] 465 "token_endpoint_auth_method": "client_secret_basic", 466 "extension_parameter": "foo" 467 } 469 4.2. Client Registration Error Response 470 When an OAuth 2.0 error condition occurs, such as the client 471 presenting an invalid initial access token, the authorization server 472 returns an error response appropriate to the OAuth 2.0 token type. 474 When a registration error condition occurs, the authorization server 475 returns an HTTP 400 status code (unless otherwise specified) with 476 content type "application/json" consisting of a JSON object [RFC4627] 477 describing the error in the response body. 479 The JSON object contains two members: 481 error 482 The error code, a single ASCII string. 483 error_description 484 A human-readable text description of the error for debugging. 486 This specification defines the following error codes: 488 invalid_redirect_uri 489 The value of one or more "redirect_uris" is invalid. 490 invalid_client_metadata 491 The value of one of the client metadata (Section 2) fields is 492 invalid and the server has rejected this request. Note that an 493 Authorization server MAY choose to substitute a valid value for 494 any requested parameter of a client's metadata. 496 Following is a non-normative example of an error response (with line 497 wraps for display purposes only): 499 HTTP/1.1 400 Bad Request 500 Content-Type: application/json 501 Cache-Control: no-store 502 Pragma: no-cache 504 { 505 "error":"invalid_redirect_uri", 506 "error_description":"The redirect URI of http://sketchy.example.com 507 is not allowed for this server." 508 } 510 5. IANA Considerations 511 5.1. OAuth Token Endpoint Authentication Methods Registry 513 This specification establishes the OAuth Token Endpoint 514 Authentication Methods registry. 516 Additional values for use as "token_endpoint_auth_method" metadata 517 values are registered with a Specification Required ([RFC5226]) after 518 a two-week review period on the oauth-ext-review@ietf.org mailing 519 list, on the advice of one or more Designated Experts. However, to 520 allow for the allocation of values prior to publication, the 521 Designated Expert(s) may approve registration once they are satisfied 522 that such a specification will be published. 524 Registration requests must be sent to the oauth-ext-review@ietf.org 525 mailing list for review and comment, with an appropriate subject 526 (e.g., "Request to register token_endpoint_auth_method value: 527 example"). 529 Within the review period, the Designated Expert(s) will either 530 approve or deny the registration request, communicating this decision 531 to the review list and IANA. Denials should include an explanation 532 and, if applicable, suggestions as to how to make the request 533 successful. 535 IANA must only accept registry updates from the Designated Expert(s) 536 and should direct all requests for registration to the review mailing 537 list. 539 5.1.1. Registration Template 541 Token Endpoint Authorization Method name: 542 The name requested (e.g., "example"). This name is case 543 sensitive. Names that match other registered names in a case 544 insensitive manner SHOULD NOT be accepted. 546 Change controller: 547 For Standards Track RFCs, state "IETF". For others, give the name 548 of the responsible party. Other details (e.g., postal address, 549 email address, home page URI) may also be included. 551 Specification document(s): 552 Reference to the document(s) that specify the token endpoint 553 authorization method, preferably including a URI that can be used 554 to retrieve a copy of the document(s). An indication of the 555 relevant sections may also be included but is not required. 557 5.1.2. Initial Registry Contents 558 The OAuth Token Endpoint Authentication Methods registry's initial 559 contents are: 561 o Token Endpoint Authorization Method name: "none" 562 o Change controller: IETF 563 o Specification document(s): [[ this document ]] 565 o Token Endpoint Authorization Method name: "client_secret_post" 566 o Change controller: IETF 567 o Specification document(s): [[ this document ]] 569 o Token Endpoint Authorization Method name: "client_secret_basic" 570 o Change controller: IETF 571 o Specification document(s): [[ this document ]] 573 6. Security Considerations 575 Since requests to the client registration endpoint result in the 576 transmission of clear-text credentials (in the HTTP request and 577 response), the Authorization Server MUST require the use of a 578 transport-layer security mechanism when sending requests to the 579 registration endpoint. The server MUST support TLS 1.2 RFC 5246 580 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 581 transport-layer mechanisms meeting its security requirements. When 582 using TLS, the Client MUST perform a TLS/SSL server certificate 583 check, per RFC 6125 [RFC6125]. 585 For clients that use redirect-based grant types such as 586 "authorization_code" and "implicit", authorization servers SHOULD 587 require clients to register their "redirect_uris". Requiring clients 588 to do so can help mitigate attacks where rogue actors inject and 589 impersonate a validly registered client and intercept its 590 authorization code or tokens through an invalid redirect URI. 592 Public clients MAY register with an authorization server using this 593 protocol, if the authorization server's policy allows them. Public 594 clients use a "none" value for the "token_endpoint_auth_method" 595 metadata field and are generally used with the "implicit" grant type. 596 Often these clients will be short-lived in-browser applications 597 requesting access to a user's resources and access is tied to a 598 user's active session at the authorization server. Since such 599 clients often do not have long-term storage, it's possible that such 600 clients would need to re-register every time the browser application 601 is loaded. Additionally, such clients may not have ample opportunity 602 to unregister themselves using the delete action before the browser 603 closes. To avoid the resulting proliferation of dead client 604 identifiers, an authorization server MAY decide to expire 605 registrations for existing clients meeting certain criteria after a 606 period of time has elapsed. 608 Since different OAuth 2.0 grant types have different security and 609 usage parameters, an authorization server MAY require separate 610 registrations for a piece of software to support multiple grant 611 types. For instance, an authorization server might require that all 612 clients using the "authorization_code" grant type make use of a 613 client secret for the "token_endpoint_auth_method", but any clients 614 using the "implicit" grant type do not use any authentication at the 615 token endpoint. In such a situation, a server MAY disallow clients 616 from registering for both the "authorization_code" and "implicit" 617 grant types simultaneously. Similarly, the "authorization_code" 618 grant type is used to represent access on behalf of an end user, but 619 the "client_credentials" grant type represents access on behalf of 620 the client itself. For security reasons, an authorization server 621 could require that different scopes be used for these different use 622 cases, and as a consequence it MAY disallow these two grant types 623 from being registered together by the same client. In all of these 624 cases, the authorization server would respond with an 625 "invalid_client_metadata" error response (Section 4.2). 627 7. Normative References 629 [IANA.Language] 630 Internet Assigned Numbers Authority (IANA), "Language 631 Subtag Registry", 2005. 633 [JWK] Jones, M., "JSON Web Key (JWK)", draft-ietf-jose-json-web- 634 key (work in progress), May 2013. 636 [OAuth.JWT] 637 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 638 (JWT) Bearer Token Profiles for OAuth 2.0", draft-ietf- 639 oauth-jwt-bearer (work in progress), March 2013. 641 [OAuth.SAML2] 642 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 643 Bearer Assertion Profiles for OAuth 2.0", draft-ietf- 644 oauth-saml2-bearer (work in progress), March 2013. 646 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 647 Requirement Levels", BCP 14, RFC 2119, March 1997. 649 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 650 RFC 2246, January 1999. 652 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 653 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 654 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 656 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 657 Unique IDentifier (UUID) URN Namespace", RFC 4122, July 658 2005. 660 [RFC4627] Crockford, D., "The application/json Media Type for 661 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 663 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 664 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 665 May 2008. 667 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 668 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 670 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 671 Languages", BCP 47, RFC 5646, September 2009. 673 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 674 Verification of Domain-Based Application Service Identity 675 within Internet Public Key Infrastructure Using X.509 676 (PKIX) Certificates in the Context of Transport Layer 677 Security (TLS)", RFC 6125, March 2011. 679 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 680 6749, October 2012. 682 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 683 Framework: Bearer Token Usage", RFC 6750, October 2012. 685 Appendix A. Acknowledgments 687 The authors thank the OAuth Working Group, the User-Managed Access 688 Working Group, and the OpenID Connect Working Group participants for 689 their input to this document. In particular, the following 690 individuals have been instrumental in their review and contribution 691 to various versions of this document: Amanda Anganes, Derek Atkins, 692 Tim Bray, Domenico Catalano, Donald Coffin, Vladimir Dzhuvinov, 693 George Fletcher, Thomas Hardjono, Phil Hunt, William Kim, Torsten 694 Lodderstedt, Eve Maler, Josh Mandel, Nov Matake, Nat Sakimura, 695 Christian Scholz, and Hannes Tschofenig. 697 Appendix B. Use Cases 699 [[ Editor's Note: These are some of the collected use cases that this 700 protocol can address, they still need to be refactored into the two 701 specifications. ]] 703 In the OAuth 2.0 specification [RFC6749], a client is identified by 704 its own unique Client identifier ("client_id") at each authorization 705 server that it associates with. Dynamic registration as defined in 706 this document is one way for a client to get a client identifier and 707 associate a set of metadata with that identifier. Lack of such a 708 client identifier is the expected trigger for a client registration 709 operation. 711 In many cases, this client identifier is a unique, pairwise 712 association between a particular running instance of a piece of 713 client software and a particular running instance of an authorization 714 server software. In particular: 716 o A single instance of client software (such as a Web server) 717 talking to multiple authorization servers will need to register 718 with each authorization server separately, creating a distinct 719 client identifier with each authorization server. The client can 720 not make any assumption that the authorization servers are 721 correlating separate registrations of the client software together 722 without further profiles and extensions to this specification 723 document. The means by which a client discovers and 724 differentiates between multiple authorization servers is out of 725 scope for this specification. 726 o Multiple instances of client software (such as a native 727 application installed on multiple devices simultaneously) talking 728 to the same authorization server will need to each register with 729 that authorization server separately, creating a distinct client 730 identifier for each copy of the application. The authorization 731 server cannot make any assumption of correlation between these 732 clients without further specifications, profiles, and extensions 733 to this specification. The client can not make any assumption 734 that the authorization server will correlate separate 735 registrations of the client software together without further 736 profiles and extensions to this specification document. 738 A client identifier (and its associated credentials) could also be 739 shared between multiple instances of a client. Mechanisms for 740 sharing client identifiers between multiple instances of a piece of 741 software (either client or authorization server) are outside the 742 scope of this specification, as it is expected that every successful 743 registration request (Section 3.1) results in the issuance of a new 744 client identifier. 746 There are several patterns of OAuth client registration that dynamic 747 registration protocol can enable. The following non-normative 748 example lifecycle descriptions are not intended to be an exhaustive 749 list. It is assumed that the authorization server supports the 750 dynamic registration protocol and that all necessary discovery steps 751 (which are out of scope for this specification) have already been 752 performed. 754 B.1. Open Registration 756 Open registration, with no authorization required on the client 757 registration endpoint, works as follows: 759 a. A client needs to get OAuth 2.0 tokens from an authorization 760 server, but the client does not have a client identifier for that 761 authorization server. 762 b. The client sends an HTTP POST request to the client registration 763 endpoint at the authorization server and includes its metadata. 764 c. The authorization server issues a client identifier and returns 765 it to the client along with a registration access token and a 766 reference to the client's client configuration endpoint. 767 d. The client stores the returned response from the authorization 768 server. At a minimum, it should remember the values of 769 "client_id", "client_secret" (if present), 770 "registration_access_token", and "registration_client_uri". 771 e. The client uses the its "client_id" and "client_secret" (if 772 provided) to request OAuth 2.0 tokens using any valid OAuth 2.0 773 flow for which it is authorized. 774 f. If the client's "client_secret" expires or otherwise stops 775 working, the client sends an HTTP GET request to the 776 "registration_client_uri" with the "registration_access_token" as 777 its authorization. This response will contain the client's 778 refreshed "client_secret" along with any changed metadata values. 779 Its "client_id" will remain the same. 780 g. If the client needs to update its configuration on the 781 authorization server, it sends an HTTP PUT request to the 782 "registration_client_uri" with the "registration_access_token" as 783 its authorization. This response will contain the client's 784 changed metadata values. Its "client_id" will remain the same. 786 h. If the client is uninstalled or otherwise deprovisioned, it can 787 send an HTTP DELETE request to the "registration_client_uri" with 788 the "registration_access_token" as its authorization. This will 789 effectively deprovision the client from the authorization server. 791 B.2. Stateless Open Registration using JWT 793 Open registration, with no authorization required on the client 794 registration endpoint. The registration endpoint/Authorization 795 server maintain no state for the client. All information is storted 796 in the client_id that is returned to the client and passed back to 797 the Authorization server and Token Endpoint on subsiquent requests. 798 If the client is using the implicit flow then the JWT MUST include 799 the redirect URI and be signed by the AS for its later consumption. 800 If the client is registering it's public key for use in the self 801 signed assertion flow, the JWT MUST include the client's public key 802 in the signed JWT. If the client is using a symetric client secret, 803 the AS MUST include the secret as a claim in the JWT and encrypt or 804 sign and encrypt the token to itself as appropriate. This method is 805 transperent to the client and requires no aditional paramaters. 807 The flow works as follows: 809 a. A client needs to get OAuth 2.0 tokens from an authorization 810 server, but the client does not have a client identifier for that 811 authorization server. 812 b. The client sends an HTTP POST request to the client registration 813 endpoint at the authorization server and includes its metadata. 814 c. The authorization server creates a JWE containing the required 815 metadata such as redirect_uri and client secret for http basic 816 authentication. (For clients using the assertion flow for 817 authentication the registration endpoint can create a JWS 818 containing the clients public key) 819 d. The authorization server issues the JWT as the client identifier 820 and returns it to the client along with a JWT registration access 821 token and a reference to the client's client configuration 822 endpoint. (The client_id cannot be changed currently so updates 823 are not possable the registration access token would only allow 824 for reads) 825 e. The client stores the returned response from the authorization 826 server. At a minimum, it should remember the values of 827 "client_id", "client_secret" (if present), 828 "registration_access_token", and "registration_client_uri". 829 f. The client uses the its "client_id" and "client_secret" (if 830 provided) to request OAuth 2.0 tokens using any valid OAuth 2.0 831 flow for which it is authorized. 832 g. If the client's "client_secret" expires or otherwise stops 833 working, the client must re-register. 835 B.3. Protected Registration 837 An authorization server may require an initial access token for 838 requests to its registration endpoint. While the method by which a 839 client receives this initial Access token and the method by which the 840 authorization server validates this initial access token are out of 841 scope for this specification, a common approach is for the developer 842 to use a manual pre-registration portal at the authorization server 843 that issues an initial access token to the developer. This allows 844 the developer to package the initial access token with different 845 instances of the client application. While each copy of the 846 application would get its own client identifier (and registration 847 access token), all instances of the application would be tied back to 848 the developer by their shared use of this initial access token. 850 a. A developer is creating a client to use an authorization server 851 and knows that instances of the client will dynamically register 852 at runtime, but that the authorization server requires 853 authorization at the registration endpoint. 854 b. The developer visits a manual pre-registration page at the 855 authorization server and is issued an initial access token in the 856 form of an OAuth 2.0 Bearer Token [RFC6750]. 857 c. The developer packages that token with all instances of the 858 client application. 859 d. The client needs to get OAuth 2.0 tokens from an authorization 860 server, but the client does not have a client identifier for that 861 authorization server. 862 e. The client sends an HTTP POST request to the client registration 863 endpoint at the authorization server with its metadata, and the 864 initial access token as its authorization. 865 f. The authorization server issues a client identifier and returns 866 it to the client along with a registration access token and a 867 reference to the client's client configuration endpoint. 868 g. The client stores the returned response from the authorization 869 server. At a minimum, it should know the values of "client_id", 870 "client_secret" (if present), "registration_access_token", and 871 "registration_client_uri". 872 h. The client uses the its "client_id" and "client_secret" (if 873 provided) to request OAuth 2.0 tokens using any supported OAuth 874 2.0 flow for which this client is authorized. 875 i. If the client's "client_secret" expires or otherwise stops 876 working, the client sends an HTTP GET request to the 877 "registration_client_uri" with the "registration_access_token" as 878 its authorization. This response will contain the client's 879 refreshed "client_secret" along with any metadata values 880 registered to that client, some of which may have changed. Its 881 "client_id" will remain the same. 883 j. If the client needs to update its configuration on the 884 authorization server, it sends an HTTP PUT request to the 885 "registration_client_uri" with the "registration_access_token" as 886 its authorization. The response will contain the client's 887 changed metadata values. Its "client_id" will remain the same. 888 k. If the client is uninstalled or otherwise deprovisioned, it can 889 send an HTTP DELETE request to the "registration_client_uri" with 890 the "registration_access_token" as its authorization. This will 891 effectively deprovision the client from the Authorization Server. 893 B.4. Developer Automation 895 The dynamic registration protocol can also be used in place of a 896 manual registration portal, for instance as part of an automated 897 build and deployment process. In this scenario, the authorization 898 server may require an initial access token for requests to its 899 registration endpoint, as described in Protected Registration 900 (Appendix B.3). However, here the developer manages the client's 901 registration instead of the client itself. Therefore, the initial 902 registration token and registration access token all remain with the 903 developer. The developer packages the client identifier with the 904 client as part of the client's build process. 906 a. A developer is creating a client to use an authorization server 907 and knows that instances of the client will not dynamically 908 register at runtime. 909 b. If required for registrations at the authorization server, the 910 developer performs an OAuth 2.0 authorization of his build 911 environment against the authorization server using any valid 912 OAuth 2.0 flow. The authorization server and is issues an 913 initial access token to the developer's build environment in the 914 form of an OAuth 2.0 Bearer Token [RFC6750]. 915 c. The developer configures his build environment to send an HTTP 916 POST request to the client registration endpoint at the 917 authorization server with the client's metadata, using the 918 initial access token obtained the previous step as an OAuth 2.0 919 Bearer Token [RFC6750]. 920 d. The authorization server issues a client identifier and returns 921 it to the developer along with a registration access token and a 922 reference to the client's client configuration endpoint. 923 e. The developer packages the client identifier with the client and 924 stores the "registration_access_token", and 925 "registration_client_uri" in the deployment system. 926 f. The client uses the its "client_id" and "client_secret" (if 927 provided) to request OAuth 2.0 tokens using any supported OAuth 928 2.0 flow. 929 g. If the client's "client_secret" expires or otherwise stops 930 working, the developer's deployment system sends an HTTP GET 931 request to the "registration_client_uri" with the 932 "registration_access_token" as its authorization. This response 933 will contain the client's refreshed "client_secret" along with 934 any changed metadata values. Its "client_id" will remain the 935 same. These new values will then be packaged and shipped to or 936 retrieved by instances of the client, if necessary. 937 h. If the developer needs to update its configuration on the 938 authorization server, the deployment system sends an HTTP PUT 939 request to the "registration_client_uri" with the 940 "registration_access_token" as its authorization. This response 941 will contain the client's changed metadata values. Its 942 "client_id" will remain the same. These new values will then be 943 packaged and shipped to or retrieved by instances of the client, 944 if necessary. 945 i. If the client is deprovisioned, the developer's deployment system 946 can send an HTTP DELETE request to the "registration_client_uri" 947 with the "registration_access_token" as its authorization. This 948 will effectively deprovision the client from the authorization 949 server and prevent any instances of the client from functioning. 951 Appendix C. Document History 953 [[ to be removed by the RFC editor before publication as an RFC ]] 955 - 00 957 o Partitioned dyn-reg specification into core and management specs 959 [[ Previous changelog from draft-ietf-oauth-dyn-reg ]] 961 -14 963 o Added software_id and software_version metadata fields 964 o Added direct references to RFC6750 errors in read/update/delete 965 methods 967 -13 969 o Fixed broken example text in registration request and in delete 970 request 971 o Added security discussion of separating clients of different grant 972 types 973 o Fixed error reference to point to RFC6750 instead of RFC6749 974 o Clarified that servers must respond to all requests to 975 configuration endpoint, even if it's just an error code 976 o Lowercased all Terms to conform to style used in RFC6750 978 -12 979 o Improved definition of Initial Access Token 980 o Changed developer registration scenario to have the Initial Access 981 Token gotten through a normal OAuth 2.0 flow 982 o Moved non-normative client lifecycle examples to appendix 983 o Marked differentiating between auth servers as out of scope 984 o Added protocol flow diagram 985 o Added credential rotation discussion 986 o Called out Client Registration Endpoint as an OAuth 2.0 Protected 987 Resource 988 o Cleaned up several pieces of text 990 -11 992 o Added localized text to registration request and response 993 examples. 994 o Removed "client_secret_jwt" and "private_key_jwt". 995 o Clarified "tos_uri" and "policy_uri" definitions. 996 o Added the OAuth Token Endpoint Authentication Methods registry for 997 registering "token_endpoint_auth_method" metadata values. 998 o Removed uses of non-ASCII characters, per RFC formatting rules. 999 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1000 to "client_id_issued_at" for greater clarity. 1001 o Added explanatory text for different credentials (Initial Access 1002 Token, Registration Access Token, Client Credentials) and what 1003 they're used for. 1004 o Added Client Lifecycle discussion and examples. 1005 o Defined Initial Access Token in Terminology section. 1007 -10 1009 o Added language to point out that scope values are service-specific 1010 o Clarified normative language around client metadata 1011 o Added extensibility to token_endpoint_auth_method using absolute 1012 URIs 1013 o Added security consideration about registering redirect URIs 1014 o Changed erroneous 403 responses to 401's with notes about token 1015 handling 1016 o Added example for initial registration credential 1018 -09 1020 o Added method of internationalization for Client Metadata values 1021 o Fixed SAML reference 1023 -08 1025 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1026 x509_encryption_uri into a single jwks_uri parameter 1028 o Renamed grant_type to grant_types since it's a plural value 1029 o Formalized name of "OAuth 2.0" throughout document 1030 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1031 grant types 1032 o Added response_types parameter and explanatory text on its use 1033 with and relationship to grant_types 1035 -07 1037 o Changed registration_access_url to registration_client_uri 1038 o Fixed missing text in 5.1 1039 o Added Pragma: no-cache to examples 1040 o Changed "no such client" error to 403 1041 o Renamed Client Registration Access Endpoint to Client 1042 Configuration Endpoint 1043 o Changed all the parameter names containing "_url" to instead use 1044 "_uri" 1045 o Updated example text for forming Client Configuration Endpoint URL 1047 -06 1049 o Removed secret_rotation as a client-initiated action, including 1050 removing client secret rotation endpoint and parameters. 1051 o Changed _links structure to single value registration_access_url. 1052 o Collapsed create/update/read responses into client info response. 1053 o Changed return code of create action to 201. 1054 o Added section to describe suggested generation and composition of 1055 Client Registration Access URL. 1056 o Added clarifying text to PUT and POST requests to specify JSON in 1057 the body. 1058 o Added Editor's Note to DELETE operation about its inclusion. 1059 o Added Editor's Note to registration_access_url about alternate 1060 syntax proposals. 1062 -05 1064 o changed redirect_uri and contact to lists instead of space 1065 delimited strings 1066 o removed operation parameter 1067 o added _links structure 1068 o made client update management more RESTful 1069 o split endpoint into three parts 1070 o changed input to JSON from form-encoded 1071 o added READ and DELETE operations 1072 o removed Requirements section 1073 o changed token_endpoint_auth_type back to 1074 token_endpoint_auth_method to match OIDC who changed to match us 1076 -04 1078 o removed default_acr, too undefined in the general OAuth2 case 1079 o removed default_max_auth_age, since there's no mechanism for 1080 supplying a non-default max_auth_age in OAuth2 1081 o clarified signing and encryption URLs 1082 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1083 match OIDC 1085 -03 1087 o added scope and grant_type claims 1088 o fixed various typos and changed wording for better clarity 1089 o endpoint now returns the full set of client information 1090 o operations on client_update allow for three actions on metadata: 1091 leave existing value, clear existing value, replace existing value 1092 with new value 1094 -02 1096 o Reorganized contributors and references 1097 o Moved OAuth references to RFC 1098 o Reorganized model/protocol sections for clarity 1099 o Changed terminology to "client register" instead of "client 1100 associate" 1101 o Specified that client_id must match across all subsequent requests 1102 o Fixed RFC2XML formatting, especially on lists 1104 -01 1106 o Merged UMA and OpenID Connect registrations into a single document 1107 o Changed to form-paramter inputs to endpoint 1108 o Removed pull-based registration 1110 -00 1112 o Imported original UMA draft specification 1114 Authors' Addresses 1116 Justin Richer (editor) 1117 The MITRE Corporation 1119 Email: jricher@mitre.org 1120 John Bradley 1121 Ping Identity 1123 Email: ve7jtb@ve7jtb.com 1125 Michael B. Jones 1126 Microsoft 1128 Email: mbj@microsoft.com 1129 URI: http://self-issued.info/ 1131 Maciej Machulak 1132 Newcastle University 1134 Email: m.p.machulak@ncl.ac.uk 1135 URI: http://ncl.ac.uk/