idnits 2.17.1 draft-ietf-oauth-dyn-reg-09.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 : ---------------------------------------------------------------------------- No issues found here. 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 (March 29, 2013) is 4044 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' ** 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 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). 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: September 30, 2013 Ping Identity 6 M.B. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 March 29, 2013 12 OAuth 2.0 Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-09 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth 2.0 Clients at an Authorization Server and 19 methods for the dynamically registered client to manage its 20 registration. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on September 30, 2013. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 4 60 2.1. Relationship Between Grant Types and Response Types . . . 7 61 2.2. Human Readable Client Metadata . . . . . . . . . . . . . 7 62 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 9 63 3.1. Client Registration Request . . . . . . . . . . . . . . . 9 64 3.2. Client Registration Response . . . . . . . . . . . . . . 10 65 4. Client Configuration Endpoint . . . . . . . . . . . . . . . . 10 66 4.1. Forming the Client Configuration Endpoint URL . . . . . . 11 67 4.2. Client Read Request . . . . . . . . . . . . . . . . . . . 11 68 4.3. Client Update Request . . . . . . . . . . . . . . . . . . 12 69 4.4. Client Delete Request . . . . . . . . . . . . . . . . . . 14 70 5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 15 71 5.1. Client Information Response . . . . . . . . . . . . . . . 15 72 5.2. Client Registration Error Response . . . . . . . . . . . 16 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 75 8. Normative References . . . . . . . . . . . . . . . . . . . . 19 76 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 20 77 Appendix B. Document History . . . . . . . . . . . . . . . . . . 20 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 80 1. Introduction 82 In some use-case scenarios, it is desirable or necessary to allow 83 OAuth 2.0 clients to obtain authorization from an OAuth 2.0 84 authorization server without requiring the two parties to interact 85 beforehand. Nevertheless, in order for the authorization server to 86 accurately and securely represent to end-users which client is 87 seeking authorization to access the end-user's resources, a method 88 for automatic and unique registration of clients is needed. The 89 OAuth 2.0 authorization framework does not define how the 90 relationship between the Client and the Authorization Server is 91 initialized, or how a given client is assigned a unique Client 92 Identifier. Historically, this has happened out-of-band from the 93 OAuth 2.0 protocol. This draft provides a mechanism for a client to 94 register itself with the Authorization Server, which can be used to 95 dynamically provision a Client Identifier, and optionally a Client 96 Secret. 98 As part of the registration process, this specification also defines 99 a mechanism for the client to present the Authorization Server with a 100 set of metadata, such as a display name and icon to be presented to 101 the user during the authorization step. This draft also provides a 102 mechanism for the Client to read and update this information after 103 the initial registration action. 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 o Client Registration Endpoint: The OAuth 2.0 Endpoint through which 125 a Client can request new registration. The means of the Client 126 obtaining the URL for this endpoint are out of scope for this 127 specification. 129 o Client Configuration Endpoint: The OAuth 2.0 Endpoint through 130 which a specific Client can manage its registration information, 131 provided by the Authorization Server to the Client. This URL for 132 this endpoint is communicated to the client by the Authorization 133 Server in the Client Information Response. 135 o Registration Access Token: An OAuth 2.0 Bearer Token issued by the 136 Authorization Server through the Client Registration Endpoint 137 which is used by the Client to authenticate itself during read, 138 update, and delete operations. This token is associated with a 139 particular Client. 141 2. Client Metadata 143 Clients generally have an array of metadata associated with their 144 unique Client Identifier at the Authorization Server. These can 145 range from human-facing display strings, such as a client name, to 146 items that impact the security of the protocol, such as the list of 147 valid redirect URIs. 149 Extensions and profiles of this specification MAY expand this list, 150 but MUST at least accept all parameters on this list. The 151 Authorization Server MUST ignore any additional parameters sent by 152 the Client that it does not understand. 154 [[ Editor's note: normative language in the table below is meant to 155 apply to the *client* when sending the request. The paragraph above 156 is meant to say that the server must at least accept all parameters 157 and not fail with an error at an unknown parameter, especially if 158 it's in the list below. Also, extensions need to explicitly call out 159 if they're not going to do something with one of these basic 160 parameters instead of just ignoring their existence. This is meant 161 to be the *minimum set* of parameters for interoperability. ]] 163 redirect_uris 164 RECOMMENDED. Array of redirect URIs for use in the Authorization 165 Code and Implicit grant types. An Authorization Server SHOULD 166 require registration of valid redirect URIs for all clients that 167 use these grant types in order to protect against token and 168 credential theft attacks. 170 client_name 171 RECOMMENDED. Human-readable name of the Client to be presented to 172 the user. If omitted, the Authorization Server MAY display to the 173 user the raw "client_id" value instead. The value of this field 174 MAY be internationalized as described in Human Readable Client 175 Metadata (Section 2.2). 177 client_uri 178 RECOMMENDED. URL of the homepage of the Client. If present, the 179 server SHOULD display this URL to the end user in a clickable 180 fashion. The value of this field MAY be internationalized as 181 described in Human Readable Client Metadata (Section 2.2). 183 logo_uri 184 OPTIONAL. URL that references a logo for the Client. If present, 185 the server SHOULD display this image to the end user during 186 approval.The value of this field MAY be internationalized as 187 described in Human Readable Client Metadata (Section 2.2). 189 contacts 190 OPTIONAL. Array of email addresses for people responsible for 191 this Client. The Authorization Server MAY make these addresses 192 available to end users for support requests for the Client. An 193 Authorization Server MAY use these email addresses as identifiers 194 for an administrative page for this client. 196 tos_uri 197 OPTIONAL. URL that points to a human-readable Terms of Service 198 for the Client. The Authorization Server SHOULD display this URL 199 to the End-User if it is given. The value of this field MAY be 200 internationalized as described in Human Readable Client Metadata 201 (Section 2.2). 203 token_endpoint_auth_method 204 OPTIONAL. The requested authentication type for the Token 205 Endpoint. Valid values are: 207 * "none": this is a public client as defined in OAuth 2.0 and 208 does not have a client secret 210 * "client_secret_post": the client uses the HTTP POST parameters 211 defined in OAuth 2.0 section 2.3.1 213 * "client_secret_basic": the client uses HTTP Basic defined in 214 OAuth 2.0 section 2.3.1 216 * "client_secret_jwt": the client uses the JWT Assertion profile 217 with a symmetric secret issued by the server 219 * "private_key_jwt": the client uses the JWT Assertion profile 220 with its own private key 222 Other authentication methods may be defined by extension. If 223 unspecified or omitted, the default is "client_secret_basic", 224 denoting HTTP Basic Authentication Scheme as specified in 225 Section 2.3.1 of OAuth 2.0. 227 scope 228 OPTIONAL. Space separated list of scope values (as described in 229 OAuth 2.0 Section 3.3 [RFC6749]) that the client is declaring that 230 it may use when requesting access tokens. If omitted, an 231 Authorization Server MAY register a Client with a default set of 232 scopes. 234 grant_types 235 OPTIONAL. Array of OAuth 2.0 grant types that the Client may use. 236 These grant types are defined as follows: 238 * "authorization_code": The Authorization Code Grant described in 239 OAuth 2.0 Section 4.1. 241 * "implicit": The Implicit Grant described in OAuth 2.0 242 Section 4.2. 244 * "password": The Resource Owner Password Credentials Grant 245 described in OAuth 2.0 Section 4.3 247 * "client_credentials": The Client Credentials Grant described in 248 OAuth 2.0 Section 4.4 250 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 251 Section 6. 253 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 254 grant type defined in OAuth JWT Bearer Token Profiles 255 [OAuth.JWT]. 257 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 258 Bearer grant type defined in OAuth SAML 2 Bearer Token Profiles 259 [OAuth.SAML2]. 261 Authorization Servers MAY allow for other values as defined in 262 grant type extensions to OAuth 2.0. The extension process is 263 described in OAuth 2.0 Section 2.5, and the value of this 264 parameter MUST be the same as the value of the "grant_type" 265 parameter passed to the Token Endpoint defined in the extension. 267 response_types 268 OPTIONAL. Array of the OAuth 2.0 response types that the Client 269 may use. These response types are defined as follows: 271 * "code": The Authorization Code response described in OAuth 2.0 272 Section 4.1. 274 * "token": The Implicit response described in OAuth 2.0 275 Section 4.2 277 Authorization Servers MAY allow for other values as defined in 278 response type extensions to OAuth 2.0. The extension process is 279 described in OAuth 2.0 Section 2.5, and the value of this 280 parameter MUST be the same as the value of the "response_type" 281 parameter passed to the Authorization Endpoint defined in the 282 extension. 284 policy_uri 285 OPTIONAL. A URL location that the Client provides to the End-User 286 to read about the how the profile data will be used. The 287 Authorization Server SHOULD display this URL to the End-User if it 288 is given. The value of this field MAY be internationalized as 289 described in Human Readable Client Metadata (Section 2.2). 291 jwks_uri 292 OPTIONAL. URL for the Client's JSON Web Key Set [JWK] document 293 that is used for signing requests, such as requests to the Token 294 Endpoint using the "private_key_jwt" assertion client credential. 295 The keys MAY also be used for higher level protocols that require 296 signing or encryption. 298 2.1. Relationship Between Grant Types and Response Types 300 The "grant_types" and "response_types" values described above are 301 partially orthogonal, as they refer to arguments passed to different 302 endpoints in the OAuth protocol. However, they are related in that 303 the "grant_types" available to a client influence the 304 "response_types" that the client is allowed to use, and vice versa. 305 For instance, a "grant_types" value that includes 306 "authorization_code" implies a "response_types" value that includes 307 code, as both values are defined as part of the OAuth 2.0 308 Authorization Code Grant. As such, a server supporting these fields 309 SHOULD take steps to ensure that a client cannot register itself into 310 an inconsistent state. 312 The correlation between the two fields is listed in the table below. 314 +-----------------------------------------------+-------------------+ 315 | grant_types value includes: | response_types | 316 | | value includes: | 317 +-----------------------------------------------+-------------------+ 318 | authorization_code | code | 319 | implicit | token | 320 | password | (none) | 321 | client_credentials | (none) | 322 | refresh_token | (none) | 323 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 324 +-----------------------------------------------+-------------------+ 326 Extensions and profiles of this document that introduce new values to 327 either the "grant_types" or "response_types" parameter MUST document 328 all correspondences between the parameter types. 330 2.2. Human Readable Client Metadata 331 Human-readable Client Metadata values and Client Metadata values that 332 reference human-readable values MAY be represented in multiple 333 languages and scripts. For example, the values of fields such as 334 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 335 might have multiple locale-specific values in some Client 336 registrations. 338 To specify the languages and scripts, BCP47 [RFC5646] language tags 339 are added to Client Metadata member names, delimited by a # 340 character. Since JSON member names are case sensitive, it is 341 RECOMMENDED that language tag values used in Claim Names be spelled 342 using the character case with which they are registered in the IANA 343 Language Subtag Registry [IANA.Language]. In particular, normally 344 language names are spelled with lowercase characters, region names 345 are spelled with uppercase characters, and languages are spelled with 346 mixed case characters. However, since BCP47 language tag values are 347 case insensitive, implementations SHOULD interpret the language tag 348 values supplied in a case insensitive manner. Per the 349 recommendations in BCP47, language tag values used in Metadata member 350 names should only be as specific as necessary. For instance, using 351 "fr" might be sufficient in many contexts, rather than "fr-CA" or 352 "fr-FR". 354 For example, a Client could represent its name in English as 355 ""client_name#en": "My Client"" and its name in Japanese as 356 ""client_name#ja-Jpan-JP": 357 "クライアント名"" within 358 the same registration request. The Authorization Server MAY display 359 any or all of these names to the Resource Owner during the 360 authorization step, choosing which name to display based on system 361 configuration, user preferences or other factors. 363 If any human-readable field is sent without a language tag, parties 364 using it MUST NOT make any assumptions about the language, character 365 set, or script of the string value, and the string value MUST be used 366 as-is wherever it is presented in a user interface. To facilitate 367 interoperability, it is RECOMMENDED that clients and servers use a 368 human-readable field without any language tags in addition to any 369 language-specific fields, and it is RECOMMENDED that any human- 370 readable fields sent without language tags contain values suitable 371 for display on a wide variety of systems. 373 Implementer's Note: Many JSON libraries make it possible to reference 374 members of a JSON object as members of an Object construct in the 375 native programming environment of the library. However, while the 376 "#" character is a valid character inside of a JSON object's member 377 names, it is not a valid character for use in an object member name 378 in many programming environments. Therefore, implementations will 379 need to use alternative access forms for these claims. For instance, 380 in JavaScript, if one parses the JSON as follows, "var j = 381 JSON.parse(json);", then the member "client_name#en-us" can be 382 accessed using the JavaScript syntax "j["client_name#en-us"]". 384 3. Client Registration Endpoint 386 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 387 this document that is designed to allow a Client to register itself 388 with the Authorization Server. The Client Registration Endpoint MUST 389 accept HTTP POST messages with request parameters encoded in the 390 entity body using the "application/json" format. The Client 391 Registration Endpoint MUST be protected by a transport-layer security 392 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 393 /or TLS 1.0 [RFC2246] and MAY support additional transport-layer 394 mechanisms meeting its security requirements. When using TLS, the 395 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 396 [RFC6125]. 398 The Client Registration Endpoint MAY accept an initial authorization 399 credential in the form of an OAuth 2.0 [RFC6749] access token in 400 order to limit registration to only previously authorized parties. 401 The method by which this access token is obtained by the registrant 402 is generally out-of-band and is out of scope of this specification. 404 In order to support open registration and facilitate wider 405 interoperability, the Client Registration Endpoint SHOULD allow 406 initial registration requests with no authentication. These requests 407 MAY be rate-limited or otherwise limited to prevent a denial-of- 408 service attack on the Client Registration Endpoint. 410 In order to facilitate registered clients updating their information, 411 the Client Registration Endpoint issues a Request Access Token for 412 clients to securely identify themselves in future connections to the 413 Client Configuration Endpoint (Section 4). As such, the Client 414 Configuration Endpoint MUST accept requests with OAuth 2.0 Bearer 415 Tokens [RFC6750] for these operations, whether or not the initial 416 registration call requires authentication of some form. 418 The Client Registration Endpoint MUST ignore all parameters it does 419 not understand. 421 3.1. Client Registration Request 423 This operation registers a new Client to the Authorization Server. 424 The Authorization Server assigns this client a unique Client 425 Identifier, optionally assigns a Client Secret, and associates the 426 metadata given in the request with the issued Client Identifier. The 427 request includes any parameters described in Client Metadata 428 (Section 2) that the client wishes to specify for itself during the 429 registration. The Authorization Server MAY provision default values 430 for any items omitted in the Client Metadata. 432 The Client sends an HTTP POST to the Client Registration Endpoint 433 with a content type of "application/json". The HTTP Entity Payload 434 is a JSON [RFC4627] document consisting of a JSON object and all 435 parameters as top-level members of that JSON object. 437 For example, a client could send the following registration request 438 to the Client Registration Endpoint: 440 Following is a non-normative example request (with line wraps for 441 display purposes only): 443 POST /register HTTP/1.1 444 Content-Type: application/json 445 Accept: application/json 446 Host: server.example.com 448 { 449 "redirect_uris":["https://client.example.org/callback", 450 "https://client.example.org/callback2"] 451 "client_name":"My Example Client", 452 "token_endpoint_auth_method":"client_secret_basic", 453 "scope":"read write dolphin", 454 "logo_uri":"https://client.example.org/logo.png", 455 "jwk_uri":"https://client.example.org/my_rsa_public_key.jwk" 456 } 458 3.2. Client Registration Response 460 Upon successful registration, the Authorization Server generates a 461 new Client Identifier for the client. This Client Identifier MUST be 462 unique at the server and MUST NOT be in use by any other client. The 463 server responds with an HTTP 201 Created code and a body of type 464 "application/json" with content described in Client Information 465 Response (Section 5.1). 467 Upon an unsuccessful registration, the Authorization Server responds 468 with an error as described in Client Registration Error 469 (Section 5.2). 471 4. Client Configuration Endpoint 472 The Client Configuration Endpoint is an OAuth 2.0 protected endpoint 473 that is provisioned by the server for a specific client to be able to 474 view and update its registered information. The Client MUST include 475 its Registration Access Token in all calls to this endpoint as an 476 OAuth 2.0 Bearer Token [RFC6750]. 478 Operations on this endpoint are switched through the use of different 479 HTTP methods [RFC2616]. 481 4.1. Forming the Client Configuration Endpoint URL 483 The Authorization Server MUST provide the client with the fully 484 qualified URL in the "registration_client_uri" element of the Client 485 Information Response (Section 5.1). The Authorization Server MUST 486 NOT expect the client to construct or discover this URL on its own. 487 The Client MUST use the URL as given by the server and MUST NOT 488 construct this URL from component pieces. 490 Depending on deployment characteristics, the Client Configuration 491 Endpoint URL may take any number of forms. It is RECOMMENDED that 492 this endpoint URL be formed through the use of a server-constructed 493 URL string which combines the Client Registration Endpoint's URL and 494 the issued client_id for this Client, with the latter as either a 495 path parameter or a query parameter. For example, a Client with the 496 Client ID "s6BhdRkqt3" could be given a Client Configuration Endpoint 497 URL of "https://server.example.com/register/s6BhdRkqt3" (path 498 parameter) or of "https://server.example.com/ 499 register?client_id=s6BhdRkqt3" (query parameter). In both of these 500 cases, the client simply follows the URL as given. 502 These common patterns can help the Server to more easily determine 503 the client to which the request pertains, which MUST be matched 504 against the client to which the Registration Access Token was issued. 505 If desired, the server MAY simply return the Client Registration 506 Endpoint URL as the Client Configuration Endpoint URL and change 507 behavior based on the authentication context provided by the 508 Registration Access Token. 510 4.2. Client Read Request 512 In order to read the current configuration of the Client on the 513 Authorization Server, the Client makes an HTTP GET request to the 514 Client Configuration Endpoint, authenticating with its Registration 515 Access Token. 517 Following is a non-normative example request (with line wraps for 518 display purposes only): 520 GET /register/s6BhdRkqt3 HTTP/1.1 521 Accept: application/json 522 Host: server.example.com 523 Authorization: Bearer reg-23410913-abewfq.123483 525 Upon successful read of the information for a currently active 526 Client, the Authorization Server responds with an HTTP 200 OK with 527 content type of "application/json" and a payload as described in 528 Client Information Response (Section 5.1). 530 If the client does not exist on this server, the server MUST return 531 an HTTP 403 Forbidden. 533 If the Client does not have permission to read its record, the server 534 MUST return an HTTP 403 Forbidden. 536 4.3. Client Update Request 538 This operation updates a previously-registered client with new 539 metadata at the Authorization Server. This request is authenticated 540 by the Registration Access Token issued to the client. 542 The Client sends an HTTP PUT to the Client Configuration Endpoint 543 with a content type of "application/json". The HTTP Entity Payload 544 is a JSON [RFC4627] document consisting of a JSON object and all 545 parameters as top- level members of that JSON object. 547 This request MUST include all fields described in Client Metadata 548 (Section 2) as returned to the Client from a previous register, read, 549 or update operation. The Client MUST NOT include the 550 "registration_access_token", "registration_client_uri", "expires_at", 551 or "issued_at" fields described in Client Information Response 552 (Section 5.1). 554 Valid values of Client Metadata fields in this request MUST replace, 555 not augment, the values previously associated with this Client. 556 Omitted fields MUST be treated as null or empty values by the server. 558 The Client MUST include its "client_id" field in the request, and it 559 MUST be the same as its currently-issued Client Identifier. If the 560 client includes the "client_secret" field in the request, the value 561 of this field MUST match the currently-issued Client Secret for that 562 Client. The Client MUST NOT be allowed to overwrite its existing 563 Client Secret with its own chosen value. 565 For all metadata fields, the Authorization Server MAY replace any 566 invalid values with suitable default values, and it MUST return any 567 such fields to the Client in the response. 569 For example, a client could send the following request to the Client 570 Registration Endpoint to update the client registration in the above 571 example with new information: 573 Following is a non-normative example request (with line wraps for 574 display purposes only): 576 PUT /register/s6BhdRkqt3 HTTP/1.1 577 Accept: application/json 578 Host: server.example.com 579 Authorization: Bearer reg-23410913-abewfq.123483 581 { 582 "client_id":"s6BhdRkqt3", 583 "client_secret": "cf136dc3c1fc93f31185e5885805d", 584 "redirect_uris":["https://client.example.org/callback", 585 "https://client.example.org/alt"], 586 "scope": "read write dolphin", 587 "grant_types": ["authorization_code", "refresh_token"] 588 "token_endpoint_auth_method": "client_secret_basic", 589 "jwk_uri": "https://client.example.org/my_rsa_public_key.jwk" 590 "client_name":"My New Example", 591 "logo_uri":"https://client.example.org/newlogo.png" 592 } 594 Upon successful update, the Authorization Server responds with an 595 HTTP 200 OK Message with content type "application/json" and a 596 payload as described in Client Information Response (Section 5.1). 597 The Authorization Server MAY include a new Client Secret and/or 598 Registration Access Token in its response. If so, the Client MUST 599 immediately discard its previous Client Secret and/or Registration 600 Access Token. 602 If the Client does not exist on this server, the server MUST return 603 an HTTP 403 Forbidden. 605 If the Client is not allowed to update its records, the server MUST 606 respond with HTTP 403 Forbidden. 608 If the Client attempts to set an invalid metadata field and the 609 Authorization Server does not set a default value, the Authorization 610 Server responds with an error as described in Client Registration 611 Error Response (Section 5.2). 613 4.4. Client Delete Request 615 [[ Editor's note: The utility and nature of this function are still 616 under active discussion. This is a proposed set of functionality 617 that a server MAY choose to implement, else give a 405 response to 618 any client that tries, if it can't support it. ]] 620 In order to deprovision itself on the Authorization Server, the 621 Client makes an HTTP DELETE request to the Client Configuration 622 Endpoint. This request is authenticated by the Registration Access 623 Token issued to the client. 625 Following is a non-normative example request (with line wraps for 626 display purposes only): 628 DELETE /register/s6BhdRkqt3 HTTP/1.1 629 Accept: application/json 630 Host: server.example.com 631 Authorization: Bearer reg-23410913-abewfq.123483 633 A successful delete action will invalidate the client_id, 634 client_secret, and registration_access_token for this client, thereby 635 preventing the client_id from being used at either the Authorization 636 Endpoint or Token Endpoint of the Authorization Server. The 637 Authorization Server SHOULD immediately invalidate all existing 638 authorization grants and currently-active tokens associated with this 639 Client. 641 If a Client has been successfully deprovisioned, the Authorization 642 Server responds with an HTTP 204 No Content message. 644 If there is no such client, the server responds with an HTTP 403 645 Forbidden. 647 If the client is not allowed to delete itself, the server responds 648 with HTTP 403 Forbidden. 650 If the server does not support the delete method, it responds with an 651 HTTP 405 Not Supported. 653 Following is a non-normative example response: 655 HTTP/1.1 204 No Content 656 Cache-Control: no-store 657 Pragma: no-cache 659 5. Responses 661 In response to certain requests from the Client to either the Client 662 Registration Endpoint or the Client Configuration Endpoint as 663 described in this specification, the Authorization Server sends the 664 following response bodies. 666 5.1. Client Information Response 668 The response contains the Client Identifier as well as the Client 669 Secret, if the Client is a confidential Client. The response also 670 contains the fully qualified URL to the Client Configuration Endpoint 671 for this specific client that the client may use to obtain and update 672 information about itself. The response also contains a Registration 673 Access Token that is to be used by the client to perform subsequent 674 operations at the Client Configuration Endpoint. 676 client_id 677 REQUIRED. The unique Client identifier, MUST NOT be currently 678 valid for any other registered Client. 680 client_secret 681 OPTIONAL. The Client secret. If issued, this MUST be unique for 682 each "client_id". This value is used by confidential clients to 683 authenticate to the Token Endpoint as described in OAuth 2.0 684 Section 2.3.1. 686 expires_at 687 REQUIRED if "client_secret" is issued. The number of seconds from 688 1970-01-01T0:0:0Z as measured in UTC that the "client_secret" will 689 expire or "0" if it does not expire. See RFC 3339 [RFC3339] for 690 details regarding date/times in general and UTC in particular. 692 issued_at 693 OPTIONAL. Specifies the timestamp when the Client Identifier was 694 issued. The timestamp value MUST be a positive integer. The 695 value is expressed in the number of seconds since January 1, 1970 696 00:00:00 GMT. 698 registration_access_token 699 REQUIRED. The Access token to be used by the client to perform 700 actions on the Client Configuration Endpoint. 702 registration_client_uri 703 REQUIRED. The fully qualified URL of the Client Configuration 704 Endpoint for this client. The Client MUST use this URL as given 705 when communicating with the Client Configuration Endpoint. 707 Additionally, the Authorization Server MUST return all registered 708 metadata (Section 2) about this client, including any fields 709 provisioned by the Authorization Server itself. The Authorization 710 Server MAY reject or replace any of the client's requested metadata 711 values submitted during the registration or update requests and 712 substitute them with suitable values. 714 The response is an "application/json" document with all parameters as 715 top-level members of a JSON object [RFC4627]. 717 Following is a non-normative example response: 719 HTTP/1.1 200 OK 720 Content-Type: application/json 721 Cache-Control: no-store 722 Pragma: no-cache 724 { 725 "registration_access_token": "reg-23410913-abewfq.123483", 726 "registration_client_uri": 727 "https://server.example.com/register/s6BhdRkqt3", 728 "client_id":"s6BhdRkqt3", 729 "client_secret": "cf136dc3c1fc93f31185e5885805d", 730 "expires_at":2893276800 731 "redirect_uris":["https://client.example.org/callback", 732 "https://client.example.org/callback2"] 733 "scope": "read write dolphin", 734 "grant_types": ["authorization_code", "refresh_token"] 735 "token_endpoint_auth_method": "client_secret_basic", 736 "logo_uri": "https://client.example.org/logo.png", 737 "jwk_uri": "https://client.example.org/my_rsa_public_key.jwk" 738 } 740 5.2. Client Registration Error Response 742 When an OAuth 2.0 error condition occurs, such as the client 743 presenting an invalid Registration Access Token, the Authorization 744 Server returns an Error Response as defined in Section 5.2 of the 745 OAuth 2.0 specification. 747 When a registration error condition occurs, the Authorization Server 748 returns an HTTP 400 status code with content type "application/json" 749 consisting of a JSON object [RFC4627] describing the error in the 750 response body. 752 The JSON object contains two members: 754 error 755 The error code, a single ASCII string. 757 error_description 758 A human-readable text description of the error for debugging. 760 This specification defines the following error codes: 762 invalid_redirect_uri 763 The value of one or more "redirect_uris" is invalid. 765 invalid_client_metadata 766 The value of one of the client metadata (Section 2) fields is 767 invalid and the server has rejected this request. Note that an 768 Authorization server MAY choose to substitute a valid value for 769 any requested parameter of a client's metadata. 771 invalid_client_id 772 Value of "client_id" is invalid. 774 Following is a non-normative example of an error response (with line 775 wraps for display purposes only): 777 HTTP/1.1 400 Bad Request 778 Content-Type: application/json 779 Cache-Control: no-store 780 Pragma: no-cache 782 { 783 "error":"invalid_redirect_uri", 784 "error_description":"The redirect URI of http://sketchy.example.com 785 is not allowed for this server." 786 } 788 6. IANA Considerations 790 This document makes no requests of IANA. 792 7. Security Considerations 793 Since requests to the Client Registration Endpoint result in the 794 transmission of clear-text credentials (in the HTTP request and 795 response), the server MUST require the use of a transport-layer 796 security mechanism when sending requests to the Registration 797 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 798 TLS 1.0 [RFC2246] and MAY support additional transport-layer 799 mechanisms meeting its security requirements. When using TLS, the 800 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 801 [RFC6125]. 803 As this endpoint is an OAuth 2.0 Protected Resource, requests to the 804 Registration Endpoint SHOULD have some rate limiting on failures to 805 prevent the Registration Access Token from being disclosed though 806 repeated access attempts. 808 The authorization server MUST treat all client metadata as self- 809 asserted. A rogue Client might use the name and logo for the 810 legitimate Client, which it is trying to impersonate. An 811 Authorization Server needs to take steps to mitigate this phishing 812 risk, since the logo could confuse users into thinking they're 813 logging in to the legitimate Client. For instance, an Authorization 814 Server could warn if the domain/site of the logo doesn't match the 815 domain/site of redirect URIs. An Authorization Server can also 816 present warning messages to end users about untrusted Clients in all 817 cases, especially if such clients have been dynamically registered 818 and have not been trusted by any users at the Authorization Server 819 before. 821 In a situation where the Authorization Server is supporting open 822 Client registration, it must be extremely careful with any URL 823 provided by the Client that will be displayed to the user (e.g. 824 "logo_uri" and "policy_uri"). A rogue Client could specify a 825 registration request with a reference to a drive-by download in the 826 "policy_uri". The Authorization Server should check to see if the 827 "logo_uri" and "policy_uri" have the same host as the hosts defined 828 in the array of "redirect_uris". 830 While the Client Secret can expire, the Registration Access Token 831 should not expire while a client is still actively registered. If 832 this token were to expire, a Client could be left in a situation 833 where it has no means of updating itself and must register itself 834 anew. As the Registration Access Tokens are long-term credentials, 835 and since the Registration Access Token is a Bearer token and acts as 836 the sole authentication for use at the Client Configuration Endpoint, 837 it MUST be protected by the Client as described in OAuth 2.0 Bearer 838 [RFC6750]. 840 If a Client is deprovisioned from a server, any outstanding 841 Registration Access Tokens for that client MUST be invalidated at the 842 same time. Otherwise, this can lead to an inconsistent state wherein 843 a Client could make requests to the Client Configuration Endpoint 844 where the authentication would succeed but the action would fail 845 because the Client is no longer valid. 847 8. Normative References 849 [IANA.Language] 850 Internet Assigned Numbers Authority (IANA), "Language 851 Subtag Registry", 2005. 853 [JWK] Jones, M.B., "JSON Web Key (JWK)", May 2012. 855 [OAuth.JWT] 856 Jones, M.B., Campbell, B., and C. Mortimore, "JSON Web 857 Token (JWT) Bearer Token Profiles for OAuth 2.0", draft- 858 ietf-oauth-jwt-bearer (work in progress), December 2012. 860 [OAuth.SAML2] 861 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 862 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer 863 (work in progress), November 2012. 865 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 866 Requirement Levels", BCP 14, RFC 2119, March 1997. 868 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 869 RFC 2246, January 1999. 871 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 872 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 873 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 875 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 876 Internet: Timestamps", RFC 3339, July 2002. 878 [RFC4627] Crockford, D., "The application/json Media Type for 879 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 881 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 882 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 884 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 885 Languages", BCP 47, RFC 5646, September 2009. 887 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 888 Verification of Domain-Based Application Service Identity 889 within Internet Public Key Infrastructure Using X.509 890 (PKIX) Certificates in the Context of Transport Layer 891 Security (TLS)", RFC 6125, March 2011. 893 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 894 6749, October 2012. 896 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 897 Framework: Bearer Token Usage", RFC 6750, October 2012. 899 Appendix A. Acknowledgments 901 The authors thank the OAuth Working Group, the User-Managed Access 902 Working Group, and the OpenID Connect Working Group participants for 903 their input to this document. In particular, the following 904 individuals have been instrumental in their review and contribution 905 to various versions of this document: Amanda Anganes, Tim Bray, 906 Domenico Catalano, George Fletcher, Torsten Lodderstedt, Eve Maler, 907 Thomas Hardjono, Nat Sakimura, and Christian Scholz. 909 Appendix B. Document History 911 [[ to be removed by the RFC editor before publication as an RFC ]] 913 -09 915 o Added method of internationalization for Client Metadata values 917 o Fixed SAML reference 919 -08 921 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 922 x509_encryption_uri into a single jwks_uri parameter 924 o Renamed grant_type to grant_types since it's a plural value 926 o Formalized name of "OAuth 2.0" throughout document 928 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 929 grant types 931 o Added response_types parameter and explanatory text on its use 932 with and relationship to grant_types 934 -07 935 o Changed registration_access_url to registration_client_uri 937 o Fixed missing text in 5.1 939 o Added Pragma: no-cache to examples 941 o Changed "no such client" error to 403 943 o Renamed Client Registration Access Endpoint to Client 944 Configuration Endpoint 946 o Changed all the parameter names containing "_url" to instead use 947 "_uri" 949 o Updated example text for forming Client Configuration Endpoint URL 951 -06 953 o Removed secret_rotation as a client-initiated action, including 954 removing client secret rotation endpoint and parameters. 956 o Changed _links structure to single value registration_access_url. 958 o Collapsed create/update/read responses into client info response. 960 o Changed return code of create action to 201. 962 o Added section to describe suggested generation and composition of 963 Client Registration Access URL. 965 o Added clarifying text to PUT and POST requests to specify JSON in 966 the body. 968 o Added Editor's Note to DELETE operation about its inclusion. 970 o Added Editor's Note to registration_access_url about alternate 971 syntax proposals. 973 -05 975 o changed redirect_uri and contact to lists instead of space 976 delimited strings 978 o removed operation parameter 980 o added _links structure 982 o made client update management more RESTful 983 o split endpoint into three parts 985 o changed input to JSON from form-encoded 987 o added READ and DELETE operations 989 o removed Requirements section 991 o changed token_endpoint_auth_type back to 992 token_endpoint_auth_method to match OIDC who changed to match us 994 -04 996 o removed default_acr, too undefined in the general OAuth2 case 998 o removed default_max_auth_age, since there's no mechanism for 999 supplying a non-default max_auth_age in OAuth2 1001 o clarified signing and encryption URLs 1003 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1004 match OIDC 1006 -03 1008 o added scope and grant_type claims 1010 o fixed various typos and changed wording for better clarity 1012 o endpoint now returns the full set of client information 1014 o operations on client_update allow for three actions on metadata: 1015 leave existing value, clear existing value, replace existing value 1016 with new value 1018 -02 1020 o Reorganized contributors and references 1022 o Moved OAuth references to RFC 1024 o Reorganized model/protocol sections for clarity 1026 o Changed terminology to "client register" instead of "client 1027 associate" 1029 o Specified that client_id must match across all subsequent requests 1030 o Fixed RFC2XML formatting, especially on lists 1032 -01 1034 o Merged UMA and OpenID Connect registrations into a single document 1036 o Changed to form-paramter inputs to endpoint 1038 o Removed pull-based registration 1040 -00 1042 o Imported original UMA draft specification 1044 Authors' Addresses 1046 Justin Richer (editor) 1047 The MITRE Corporation 1049 Email: jricher@mitre.org 1051 John Bradley 1052 Ping Identity 1054 Email: ve7jtb@ve7jtb.com 1056 Michael B. Jones 1057 Microsoft 1059 Email: mbj@microsoft.com 1061 Maciej Machulak 1062 Newcastle University 1064 Email: m.p.machulak@ncl.ac.uk 1065 URI: http://ncl.ac.uk/