idnits 2.17.1 draft-ietf-oauth-dyn-reg-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 05, 2013) is 4007 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 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 (~~), 3 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: November 06, 2013 Ping Identity 6 M.B. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 May 05, 2013 12 OAuth 2.0 Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-10 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 November 06, 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 . . . . . . . . . . . . . 8 62 3. Client Registration Endpoint . . . . . . . . . . . . . . . . 9 63 3.1. Client Registration Request . . . . . . . . . . . . . . . 10 64 3.2. Client Registration Response . . . . . . . . . . . . . . 11 65 4. Client Configuration Endpoint . . . . . . . . . . . . . . . . 11 66 4.1. Forming the Client Configuration Endpoint URL . . . . . . 12 67 4.2. Client Read Request . . . . . . . . . . . . . . . . . . . 12 68 4.3. Client Update Request . . . . . . . . . . . . . . . . . . 13 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 . . . . . . . . . . . 17 73 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 74 7. Security Considerations . . . . . . . . . . . . . . . . . . . 18 75 8. Normative References . . . . . . . . . . . . . . . . . . . . 20 76 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 21 77 Appendix B. Document History . . . . . . . . . . . . . . . . . . 21 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 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 The client metadata values serve two parallel purposes in the overall 150 OAuth 2.0 Dynamic Client Registration protocol: 152 o the Client requesting its desired values for each parameter to the 153 Authorization Server in a register (Section 3.1) or update 154 (Section 4.3) request, and 156 o the Authorization Server informing the Client of the current 157 values of each parameter that the Client has been registered to 158 use through a client information response (Section 5.1). 160 An Authorization Server MAY override any value that a Client requests 161 during the registration process (including any omitted values) and 162 replace the requested value with a default at the server's 163 discretion. The Authorization Server SHOULD provide documentation 164 for any fields that it requires to be filled in by the client or to 165 have particular values or formats. 167 Extensions and profiles of this specification MAY expand this list, 168 but Authorization Servers MUST accept or ignore all parameters on 169 this list. The Authorization Server MUST ignore any additional 170 parameters sent by the Client that it does not understand. 172 redirect_uris 173 Array of redirect URIs for use in redirect-based flows such as the 174 Authorization Code and Implicit grant types. It is RECOMMENDED 175 that clients using these flows register this parameter, and an 176 Authorization Server SHOULD require registration of valid redirect 177 URIs for all clients that use these grant types in order to 178 protect against token and credential theft attacks. 180 client_name 181 Human-readable name of the Client to be presented to the user. If 182 omitted, the Authorization Server MAY display the raw "client_id" 183 value to the user instead. It is RECOMMENDED that clients always 184 send this field. The value of this field MAY be internationalized 185 as described in Human Readable Client Metadata (Section 2.2). 187 client_uri 188 URL of the homepage of the Client. If present, the server SHOULD 189 display this URL to the end user in a clickable fashion. It is 190 RECOMMENDED that clients always send this field. The value of 191 this field MAY be internationalized as described in Human Readable 192 Client Metadata (Section 2.2). 194 logo_uri 195 URL that references a logo for the Client. If present, the server 196 SHOULD display this image to the end user during approval. The 197 value of this field MAY be internationalized as described in Human 198 Readable Client Metadata (Section 2.2). 200 contacts 201 Array of email addresses for people responsible for this Client. 202 The Authorization Server MAY make these addresses available to end 203 users for support requests for the Client. An Authorization 204 Server MAY use these email addresses as identifiers for an 205 administrative page for this client. 207 tos_uri 208 URL that points to a human-readable Terms of Service for the 209 Client. The Authorization Server SHOULD display this URL to the 210 End-User if it is given. The value of this field MAY be 211 internationalized as described in Human Readable Client Metadata 212 (Section 2.2). 214 token_endpoint_auth_method 215 The requested authentication type for the Token Endpoint. Valid 216 values are: 218 * "none": this is a public client as defined in OAuth 2.0 and 219 does not have a client secret 221 * "client_secret_post": the client uses the HTTP POST parameters 222 defined in OAuth 2.0 section 2.3.1 224 * "client_secret_basic": the client uses HTTP Basic defined in 225 OAuth 2.0 section 2.3.1 227 * "client_secret_jwt": the client uses the JWT Assertion 228 [OAuth.JWT] profile with a symmetric signature using the 229 "client_secret" issued by the server 231 * "private_key_jwt": the client uses the JWT Assertion 232 [OAuth.JWT] profile with its own private key, usually with its 233 public key location indicated by the "jwks_uri" field 235 Other authentication methods may be defined by extension. If 236 unspecified or omitted, the default is "client_secret_basic", 237 denoting HTTP Basic Authentication Scheme as specified in 238 Section 2.3.1 of OAuth 2.0. Other authentication methods MAY be 239 supported by using an absolute URI as the value of this parameter. 241 scope 242 Space separated list of scope values (as described in OAuth 2.0 243 Section 3.3 [RFC6749]) that the client can use when requesting 244 access tokens. The semantics of values in this list is service 245 specific. If omitted, an Authorization Server MAY register a 246 Client with a default set of scopes. 248 grant_types 249 Array of OAuth 2.0 grant types that the Client may use. These 250 grant types are defined as follows: 252 * "authorization_code": The Authorization Code Grant described in 253 OAuth 2.0 Section 4.1 255 * "implicit": The Implicit Grant described in OAuth 2.0 256 Section 4.2 258 * "password": The Resource Owner Password Credentials Grant 259 described in OAuth 2.0 Section 4.3 261 * "client_credentials": The Client Credentials Grant described in 262 OAuth 2.0 Section 4.4 264 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 265 Section 6. 267 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 268 grant type defined in OAuth JWT Bearer Token Profiles 269 [OAuth.JWT]. 271 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 272 Bearer grant type defined in OAuth SAML 2 Bearer Token Profiles 273 [OAuth.SAML2]. 275 Authorization Servers MAY allow for other values as defined in 276 grant type extensions to OAuth 2.0. The extension process is 277 described in OAuth 2.0 Section 2.5, and the value of this 278 parameter MUST be the same as the value of the "grant_type" 279 parameter passed to the Token Endpoint defined in the extension. 281 response_types 282 Array of the OAuth 2.0 response types that the Client may use. 283 These response types are defined as follows: 285 * "code": The Authorization Code response described in OAuth 2.0 286 Section 4.1 288 * "token": The Implicit response described in OAuth 2.0 289 Section 4.2 291 Authorization Servers MAY allow for other values as defined in 292 response type extensions to OAuth 2.0. The extension process is 293 described in OAuth 2.0 Section 2.5, and the value of this 294 parameter MUST be the same as the value of the "response_type" 295 parameter passed to the Authorization Endpoint defined in the 296 extension. 298 policy_uri 299 A URL location that the Client provides to the End-User to read 300 about the how the profile data will be used. The Authorization 301 Server SHOULD display this URL to the End-User if it is given. 302 The value of this field MAY be internationalized as described in 303 Human Readable Client Metadata (Section 2.2). 305 jwks_uri 306 URL for the Client's JSON Web Key Set [JWK] document that is used 307 for signing requests, such as requests to the Token Endpoint using 308 the "private_key_jwt" assertion client credential. The keys MAY 309 also be used for higher level protocols that require signing or 310 encryption. 312 2.1. Relationship Between Grant Types and Response Types 314 The "grant_types" and "response_types" values described above are 315 partially orthogonal, as they refer to arguments passed to different 316 endpoints in the OAuth protocol. However, they are related in that 317 the "grant_types" available to a client influence the 318 "response_types" that the client is allowed to use, and vice versa. 319 For instance, a "grant_types" value that includes 320 "authorization_code" implies a "response_types" value that includes 321 code, as both values are defined as part of the OAuth 2.0 322 Authorization Code Grant. As such, a server supporting these fields 323 SHOULD take steps to ensure that a client cannot register itself into 324 an inconsistent state. 326 The correlation between the two fields is listed in the table below. 328 +-----------------------------------------------+-------------------+ 329 | grant_types value includes: | response_types | 330 | | value includes: | 331 +-----------------------------------------------+-------------------+ 332 | authorization_code | code | 333 | implicit | token | 334 | password | (none) | 335 | client_credentials | (none) | 336 | refresh_token | (none) | 337 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 338 +-----------------------------------------------+-------------------+ 340 Extensions and profiles of this document that introduce new values to 341 either the "grant_types" or "response_types" parameter MUST document 342 all correspondences between the parameter types. 344 2.2. Human Readable Client Metadata 346 Human-readable Client Metadata values and Client Metadata values that 347 reference human-readable values MAY be represented in multiple 348 languages and scripts. For example, the values of fields such as 349 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 350 might have multiple locale-specific values in some Client 351 registrations. 353 To specify the languages and scripts, BCP47 [RFC5646] language tags 354 are added to Client Metadata member names, delimited by a # 355 character. Since JSON member names are case sensitive, it is 356 RECOMMENDED that language tag values used in Claim Names be spelled 357 using the character case with which they are registered in the IANA 358 Language Subtag Registry [IANA.Language]. In particular, normally 359 language names are spelled with lowercase characters, region names 360 are spelled with uppercase characters, and languages are spelled with 361 mixed case characters. However, since BCP47 language tag values are 362 case insensitive, implementations SHOULD interpret the language tag 363 values supplied in a case insensitive manner. Per the 364 recommendations in BCP47, language tag values used in Metadata member 365 names should only be as specific as necessary. For instance, using 366 "fr" might be sufficient in many contexts, rather than "fr-CA" or 367 "fr-FR". 369 For example, a Client could represent its name in English as 370 ""client_name#en": "My Client"" and its name in Japanese as 371 ""client_name#ja-Jpan-JP": 372 "クライアント名"" within 373 the same registration request. The Authorization Server MAY display 374 any or all of these names to the Resource Owner during the 375 authorization step, choosing which name to display based on system 376 configuration, user preferences or other factors. 378 If any human-readable field is sent without a language tag, parties 379 using it MUST NOT make any assumptions about the language, character 380 set, or script of the string value, and the string value MUST be used 381 as-is wherever it is presented in a user interface. To facilitate 382 interoperability, it is RECOMMENDED that clients and servers use a 383 human-readable field without any language tags in addition to any 384 language-specific fields, and it is RECOMMENDED that any human- 385 readable fields sent without language tags contain values suitable 386 for display on a wide variety of systems. 388 Implementer's Note: Many JSON libraries make it possible to reference 389 members of a JSON object as members of an Object construct in the 390 native programming environment of the library. However, while the 391 "#" character is a valid character inside of a JSON object's member 392 names, it is not a valid character for use in an object member name 393 in many programming environments. Therefore, implementations will 394 need to use alternative access forms for these claims. For instance, 395 in JavaScript, if one parses the JSON as follows, "var j = 396 JSON.parse(json);", then the member "client_name#en-us" can be 397 accessed using the JavaScript syntax "j["client_name#en-us"]". 399 3. Client Registration Endpoint 401 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 402 this document that is designed to allow a Client to register itself 403 with the Authorization Server. The Client Registration Endpoint MUST 404 accept HTTP POST messages with request parameters encoded in the 405 entity body using the "application/json" format. The Client 406 Registration Endpoint MUST be protected by a transport-layer security 407 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] and 408 /or TLS 1.0 [RFC2246] and MAY support additional transport-layer 409 mechanisms meeting its security requirements. When using TLS, the 410 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 411 [RFC6125]. 413 The Client Registration Endpoint MAY accept an initial authorization 414 credential in the form of an OAuth 2.0 [RFC6749] access token in 415 order to limit registration to only previously authorized parties. 416 The method by which this access token is obtained by the registrant 417 is generally out-of-band and is out of scope of this specification. 419 In order to support open registration and facilitate wider 420 interoperability, the Client Registration Endpoint SHOULD allow 421 initial registration requests with no authentication. These requests 422 MAY be rate-limited or otherwise limited to prevent a denial-of- 423 service attack on the Client Registration Endpoint. 425 In order to facilitate registered clients updating their information, 426 the Client Registration Endpoint issues a Request Access Token for 427 clients to securely identify themselves in future connections to the 428 Client Configuration Endpoint (Section 4). As such, the Client 429 Configuration Endpoint MUST accept requests with OAuth 2.0 Bearer 430 Tokens [RFC6750] for these operations, whether or not the initial 431 registration call requires authentication of some form. 433 The Client Registration Endpoint MUST ignore all parameters it does 434 not understand. 436 3.1. Client Registration Request 438 This operation registers a new Client to the Authorization Server. 439 The Authorization Server assigns this client a unique Client 440 Identifier, optionally assigns a Client Secret, and associates the 441 metadata given in the request with the issued Client Identifier. The 442 request includes any parameters described in Client Metadata 443 (Section 2) that the client wishes to specify for itself during the 444 registration. The Authorization Server MAY provision default values 445 for any items omitted in the Client Metadata. 447 The Client sends an HTTP POST to the Client Registration Endpoint 448 with a content type of "application/json". The HTTP Entity Payload 449 is a JSON [RFC4627] document consisting of a JSON object and all 450 parameters as top-level members of that JSON object. 452 For example, a client could send the following open registration 453 request to the Client Registration Endpoint: 455 Following is a non-normative example request (with line wraps for 456 display purposes only): 458 POST /register HTTP/1.1 459 Content-Type: application/json 460 Accept: application/json 461 Host: server.example.com 463 { 464 "redirect_uris":["https://client.example.org/callback", 465 "https://client.example.org/callback2"] 466 "client_name":"My Example Client", 467 "token_endpoint_auth_method":"client_secret_basic", 468 "scope":"read write dolphin", 469 "logo_uri":"https://client.example.org/logo.png", 470 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 471 } 472 Alternatively, if the client has been provisioned with an initial 473 authorization credential, it could send the following registration 474 request to the Client Registration Endpoint: 476 Following is a non-normative example request (with line wraps for 477 display purposes only): 479 POST /register HTTP/1.1 480 Content-Type: application/json 481 Accept: application/json 482 Authorization: Bearer ey23f2.adfj230.af32-developer321 483 Host: server.example.com 485 { 486 "redirect_uris":["https://client.example.org/callback", 487 "https://client.example.org/callback2"] 488 "client_name":"My Example Client", 489 "token_endpoint_auth_method":"client_secret_basic", 490 "scope":"read write dolphin", 491 "logo_uri":"https://client.example.org/logo.png", 492 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 493 } 495 3.2. Client Registration Response 497 Upon successful registration, the Authorization Server generates a 498 new Client Identifier for the client. This Client Identifier MUST be 499 unique at the server and MUST NOT be in use by any other client. The 500 server responds with an HTTP 201 Created code and a body of type 501 "application/json" with content described in Client Information 502 Response (Section 5.1). 504 Upon an unsuccessful registration, the Authorization Server responds 505 with an error as described in Client Registration Error 506 (Section 5.2). 508 4. Client Configuration Endpoint 510 The Client Configuration Endpoint is an OAuth 2.0 protected endpoint 511 that is provisioned by the server for a specific client to be able to 512 view and update its registered information. The Client MUST include 513 its Registration Access Token in all calls to this endpoint as an 514 OAuth 2.0 Bearer Token [RFC6750]. 516 Operations on this endpoint are switched through the use of different 517 HTTP methods [RFC2616]. 519 4.1. Forming the Client Configuration Endpoint URL 521 The Authorization Server MUST provide the client with the fully 522 qualified URL in the "registration_client_uri" element of the Client 523 Information Response (Section 5.1). The Authorization Server MUST 524 NOT expect the client to construct or discover this URL on its own. 525 The Client MUST use the URL as given by the server and MUST NOT 526 construct this URL from component pieces. 528 Depending on deployment characteristics, the Client Configuration 529 Endpoint URL may take any number of forms. It is RECOMMENDED that 530 this endpoint URL be formed through the use of a server-constructed 531 URL string which combines the Client Registration Endpoint's URL and 532 the issued client_id for this Client, with the latter as either a 533 path parameter or a query parameter. For example, a Client with the 534 Client ID "s6BhdRkqt3" could be given a Client Configuration Endpoint 535 URL of "https://server.example.com/register/s6BhdRkqt3" (path 536 parameter) or of "https://server.example.com/ 537 register?client_id=s6BhdRkqt3" (query parameter). In both of these 538 cases, the client simply follows the URL as given. 540 These common patterns can help the Server to more easily determine 541 the client to which the request pertains, which MUST be matched 542 against the client to which the Registration Access Token was issued. 543 If desired, the server MAY simply return the Client Registration 544 Endpoint URL as the Client Configuration Endpoint URL and change 545 behavior based on the authentication context provided by the 546 Registration Access Token. 548 4.2. Client Read Request 550 In order to read the current configuration of the Client on the 551 Authorization Server, the Client makes an HTTP GET request to the 552 Client Configuration Endpoint, authenticating with its Registration 553 Access Token. 555 Following is a non-normative example request (with line wraps for 556 display purposes only): 558 GET /register/s6BhdRkqt3 HTTP/1.1 559 Accept: application/json 560 Host: server.example.com 561 Authorization: Bearer reg-23410913-abewfq.123483 563 Upon successful read of the information for a currently active 564 Client, the Authorization Server responds with an HTTP 200 OK with 565 content type of "application/json" and a payload as described in 566 Client Information Response (Section 5.1). 568 If the client does not exist on this server, the server MUST respond 569 with HTTP 401 Unauthorized and the Registration Access Token used to 570 make this request SHOULD be immediately revoked. 572 If the Client does not have permission to read its record, the server 573 MUST return an HTTP 403 Forbidden. 575 4.3. Client Update Request 577 This operation updates a previously-registered client with new 578 metadata at the Authorization Server. This request is authenticated 579 by the Registration Access Token issued to the client. 581 The Client sends an HTTP PUT to the Client Configuration Endpoint 582 with a content type of "application/json". The HTTP Entity Payload 583 is a JSON [RFC4627] document consisting of a JSON object and all 584 parameters as top- level members of that JSON object. 586 This request MUST include all fields described in Client Metadata 587 (Section 2) as returned to the Client from a previous register, read, 588 or update operation. The Client MUST NOT include the 589 "registration_access_token", "registration_client_uri", "expires_at", 590 or "issued_at" fields described in Client Information Response 591 (Section 5.1). 593 Valid values of Client Metadata fields in this request MUST replace, 594 not augment, the values previously associated with this Client. 595 Omitted fields MUST be treated as null or empty values by the server. 597 The Client MUST include its "client_id" field in the request, and it 598 MUST be the same as its currently-issued Client Identifier. If the 599 client includes the "client_secret" field in the request, the value 600 of this field MUST match the currently-issued Client Secret for that 601 Client. The Client MUST NOT be allowed to overwrite its existing 602 Client Secret with its own chosen value. 604 For all metadata fields, the Authorization Server MAY replace any 605 invalid values with suitable default values, and it MUST return any 606 such fields to the Client in the response. 608 For example, a client could send the following request to the Client 609 Registration Endpoint to update the client registration in the above 610 example with new information: 612 Following is a non-normative example request (with line wraps for 613 display purposes only): 615 PUT /register/s6BhdRkqt3 HTTP/1.1 616 Accept: application/json 617 Host: server.example.com 618 Authorization: Bearer reg-23410913-abewfq.123483 620 { 621 "client_id":"s6BhdRkqt3", 622 "client_secret": "cf136dc3c1fc93f31185e5885805d", 623 "redirect_uris":["https://client.example.org/callback", 624 "https://client.example.org/alt"], 625 "scope": "read write dolphin", 626 "grant_types": ["authorization_code", "refresh_token"] 627 "token_endpoint_auth_method": "client_secret_basic", 628 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 629 "client_name":"My New Example", 630 "logo_uri":"https://client.example.org/newlogo.png" 631 } 633 Upon successful update, the Authorization Server responds with an 634 HTTP 200 OK Message with content type "application/json" and a 635 payload as described in Client Information Response (Section 5.1). 636 The Authorization Server MAY include a new Client Secret and/or 637 Registration Access Token in its response. If so, the Client MUST 638 immediately discard its previous Client Secret and/or Registration 639 Access Token. 641 If the client does not exist on this server, the server MUST respond 642 with HTTP 401 Unauthorized, and the Registration Access Token used to 643 make this request SHOULD be immediately revoked. 645 If the Client is not allowed to update its records, the server MUST 646 respond with HTTP 403 Forbidden. 648 If the Client attempts to set an invalid metadata field and the 649 Authorization Server does not set a default value, the Authorization 650 Server responds with an error as described in Client Registration 651 Error Response (Section 5.2). 653 4.4. Client Delete Request 655 In order to deprovision itself on the Authorization Server, the 656 Client makes an HTTP DELETE request to the Client Configuration 657 Endpoint. This request is authenticated by the Registration Access 658 Token issued to the client. 660 Following is a non-normative example request (with line wraps for 661 display purposes only): 663 DELETE /register/s6BhdRkqt3 HTTP/1.1 664 Accept: application/json 665 Host: server.example.com 666 Authorization: Bearer reg-23410913-abewfq.123483 668 A successful delete action will invalidate the client_id, 669 client_secret, and registration_access_token for this client, thereby 670 preventing the client_id from being used at either the Authorization 671 Endpoint or Token Endpoint of the Authorization Server. The 672 Authorization Server SHOULD immediately invalidate all existing 673 authorization grants and currently-active tokens associated with this 674 Client. 676 If a Client has been successfully deprovisioned, the Authorization 677 Server responds with an HTTP 204 No Content message. 679 If the server does not support the delete method, the server MUST 680 respond with an HTTP 405 Not Supported. 682 If the client does not exist on this server, the server MUST respond 683 with HTTP 401 Unauthorized and the Registration Access Token used to 684 make this request SHOULD be immediately revoked. 686 If the client is not allowed to delete itself, the server MUST 687 respond with HTTP 403 Forbidden. 689 Following is a non-normative example response: 691 HTTP/1.1 204 No Content 692 Cache-Control: no-store 693 Pragma: no-cache 695 5. Responses 697 In response to certain requests from the Client to either the Client 698 Registration Endpoint or the Client Configuration Endpoint as 699 described in this specification, the Authorization Server sends the 700 following response bodies. 702 5.1. Client Information Response 703 The response contains the Client Identifier as well as the Client 704 Secret, if the Client is a confidential Client. The response also 705 contains the fully qualified URL to the Client Configuration Endpoint 706 for this specific client that the client may use to obtain and update 707 information about itself. The response also contains a Registration 708 Access Token that is to be used by the client to perform subsequent 709 operations at the Client Configuration Endpoint. 711 client_id 712 REQUIRED. The unique Client identifier, MUST NOT be currently 713 valid for any other registered Client. 715 client_secret 716 OPTIONAL. The Client secret. If issued, this MUST be unique for 717 each "client_id". This value is used by confidential clients to 718 authenticate to the Token Endpoint as described in OAuth 2.0 719 Section 2.3.1. 721 expires_at 722 REQUIRED if "client_secret" is issued. Time at which the 723 "client_secret" will expire or 0 if it will not expire. The time 724 is represented as the number of seconds from 1970-01-01T0:0:0Z as 725 measured in UTC until the date/time. 727 issued_at 728 OPTIONAL. Time at which the Client Identifier was issued. The 729 time is represented as the number of seconds from 730 1970-01-01T0:0:0Z as measured in UTC until the date/time. 732 registration_access_token 733 REQUIRED. The Access token to be used by the client to perform 734 actions on the Client Configuration Endpoint. 736 registration_client_uri 737 REQUIRED. The fully qualified URL of the Client Configuration 738 Endpoint for this client. The Client MUST use this URL as given 739 when communicating with the Client Configuration Endpoint. 741 Additionally, the Authorization Server MUST return all registered 742 metadata (Section 2) about this client, including any fields 743 provisioned by the Authorization Server itself. The Authorization 744 Server MAY reject or replace any of the client's requested metadata 745 values submitted during the registration or update requests and 746 substitute them with suitable values. 748 The response is an "application/json" document with all parameters as 749 top-level members of a JSON object [RFC4627]. 751 Following is a non-normative example response: 753 HTTP/1.1 200 OK 754 Content-Type: application/json 755 Cache-Control: no-store 756 Pragma: no-cache 758 { 759 "registration_access_token": "reg-23410913-abewfq.123483", 760 "registration_client_uri": 761 "https://server.example.com/register/s6BhdRkqt3", 762 "client_id":"s6BhdRkqt3", 763 "client_secret": "cf136dc3c1fc93f31185e5885805d", 764 "expires_at":2893276800 765 "redirect_uris":["https://client.example.org/callback", 766 "https://client.example.org/callback2"] 767 "scope": "read write dolphin", 768 "grant_types": ["authorization_code", "refresh_token"] 769 "token_endpoint_auth_method": "client_secret_basic", 770 "logo_uri": "https://client.example.org/logo.png", 771 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 772 } 774 5.2. Client Registration Error Response 776 When an OAuth 2.0 error condition occurs, such as the client 777 presenting an invalid Registration Access Token, the Authorization 778 Server returns an Error Response as defined in Section 5.2 of the 779 OAuth 2.0 specification. 781 When a registration error condition occurs, the Authorization Server 782 returns an HTTP 400 status code with content type "application/json" 783 consisting of a JSON object [RFC4627] describing the error in the 784 response body. 786 The JSON object contains two members: 788 error 789 The error code, a single ASCII string. 791 error_description 792 A human-readable text description of the error for debugging. 794 This specification defines the following error codes: 796 invalid_redirect_uri 797 The value of one or more "redirect_uris" is invalid. 799 invalid_client_metadata 800 The value of one of the client metadata (Section 2) fields is 801 invalid and the server has rejected this request. Note that an 802 Authorization server MAY choose to substitute a valid value for 803 any requested parameter of a client's metadata. 805 invalid_client_id 806 Value of "client_id" is invalid. 808 Following is a non-normative example of an error response (with line 809 wraps for display purposes only): 811 HTTP/1.1 400 Bad Request 812 Content-Type: application/json 813 Cache-Control: no-store 814 Pragma: no-cache 816 { 817 "error":"invalid_redirect_uri", 818 "error_description":"The redirect URI of http://sketchy.example.com 819 is not allowed for this server." 820 } 822 6. IANA Considerations 824 This document makes no requests of IANA. 826 7. Security Considerations 828 Since requests to the Client Registration Endpoint result in the 829 transmission of clear-text credentials (in the HTTP request and 830 response), the server MUST require the use of a transport-layer 831 security mechanism when sending requests to the Registration 832 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 833 TLS 1.0 [RFC2246] and MAY support additional transport-layer 834 mechanisms meeting its security requirements. When using TLS, the 835 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 836 [RFC6125]. 838 As this endpoint is an OAuth 2.0 Protected Resource, requests to the 839 Registration Endpoint SHOULD have some rate limiting on failures to 840 prevent the Registration Access Token from being disclosed though 841 repeated access attempts. 843 For clients that use redirect-based grant types such as Authorization 844 Code and Implicit, Authorization Servers SHOULD require clients to 845 pre-register their "redirect_uris". Requiring Clients to do so can 846 help mitigate attacks where rogue actors inject and impersonate a 847 validly registered client and intercept its authorization code or 848 tokens through an invalid redirect URI. 850 The authorization server MUST treat all client metadata as self- 851 asserted. A rogue Client might use the name and logo for the 852 legitimate Client, which it is trying to impersonate. An 853 Authorization Server needs to take steps to mitigate this phishing 854 risk, since the logo could confuse users into thinking they're 855 logging in to the legitimate Client. For instance, an Authorization 856 Server could warn if the domain/site of the logo doesn't match the 857 domain/site of redirect URIs. An Authorization Server can also 858 present warning messages to end users about untrusted Clients in all 859 cases, especially if such clients have been dynamically registered 860 and have not been trusted by any users at the Authorization Server 861 before. 863 In a situation where the Authorization Server is supporting open 864 Client registration, it must be extremely careful with any URL 865 provided by the Client that will be displayed to the user (e.g. 866 "logo_uri" and "policy_uri"). A rogue Client could specify a 867 registration request with a reference to a drive-by download in the 868 "policy_uri". The Authorization Server should check to see if the 869 "logo_uri" and "policy_uri" have the same host as the hosts defined 870 in the array of "redirect_uris". 872 While the Client Secret can expire, the Registration Access Token 873 should not expire while a client is still actively registered. If 874 this token were to expire, a Client could be left in a situation 875 where it has no means of updating itself and must register itself 876 anew. As the Registration Access Tokens are long-term credentials, 877 and since the Registration Access Token is a Bearer token and acts as 878 the sole authentication for use at the Client Configuration Endpoint, 879 it MUST be protected by the Client as described in OAuth 2.0 Bearer 880 [RFC6750]. 882 If a Client is deprovisioned from a server, any outstanding 883 Registration Access Tokens for that client MUST be invalidated at the 884 same time. Otherwise, this can lead to an inconsistent state wherein 885 a Client could make requests to the Client Configuration Endpoint 886 where the authentication would succeed but the action would fail 887 because the Client is no longer valid. 889 8. Normative References 891 [IANA.Language] 892 Internet Assigned Numbers Authority (IANA), "Language 893 Subtag Registry", 2005. 895 [JWK] Jones, M.B., "JSON Web Key (JWK)", draft-ietf-jose-json- 896 web-key (work in progress), April 2013. 898 [OAuth.JWT] 899 Jones, M.B., Campbell, B., and C. Mortimore, "JSON Web 900 Token (JWT) Bearer Token Profiles for OAuth 2.0", draft- 901 ietf-oauth-jwt-bearer (work in progress), March 2013. 903 [OAuth.SAML2] 904 Campbell, B., Mortimore, C., and M.B. Jones, "SAML 2.0 905 Bearer Assertion Profiles for OAuth 2.0", draft-ietf- 906 oauth-saml2-bearer (work in progress), March 2013. 908 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 909 Requirement Levels", BCP 14, RFC 2119, March 1997. 911 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 912 RFC 2246, January 1999. 914 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 915 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 916 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 918 [RFC4627] Crockford, D., "The application/json Media Type for 919 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 921 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 922 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 924 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 925 Languages", BCP 47, RFC 5646, September 2009. 927 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 928 Verification of Domain-Based Application Service Identity 929 within Internet Public Key Infrastructure Using X.509 930 (PKIX) Certificates in the Context of Transport Layer 931 Security (TLS)", RFC 6125, March 2011. 933 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 934 6749, October 2012. 936 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 937 Framework: Bearer Token Usage", RFC 6750, October 2012. 939 Appendix A. Acknowledgments 941 The authors thank the OAuth Working Group, the User-Managed Access 942 Working Group, and the OpenID Connect Working Group participants for 943 their input to this document. In particular, the following 944 individuals have been instrumental in their review and contribution 945 to various versions of this document: Amanda Anganes, Tim Bray, 946 Domenico Catalano, George Fletcher, Torsten Lodderstedt, Eve Maler, 947 Nov Matake, Thomas Hardjono, Nat Sakimura, and Christian Scholz. 949 Appendix B. Document History 951 [[ to be removed by the RFC editor before publication as an RFC ]] 953 -10 955 o Added language to point out that scope values are service-specific 957 o Clarified normative language around client metadata 959 o Added extensibility to token_endpoint_auth_method using absolute 960 URIs 962 o Added security consideration about registering redirect URIs 964 o Changed erroneous 403 responses to 401's with notes about token 965 handling 967 o Added example for initial registration credential 969 -09 971 o Added method of internationalization for Client Metadata values 973 o Fixed SAML reference 975 -08 977 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 978 x509_encryption_uri into a single jwks_uri parameter 980 o Renamed grant_type to grant_types since it's a plural value 982 o Formalized name of "OAuth 2.0" throughout document 983 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 984 grant types 986 o Added response_types parameter and explanatory text on its use 987 with and relationship to grant_types 989 -07 991 o Changed registration_access_url to registration_client_uri 993 o Fixed missing text in 5.1 995 o Added Pragma: no-cache to examples 997 o Changed "no such client" error to 403 999 o Renamed Client Registration Access Endpoint to Client 1000 Configuration Endpoint 1002 o Changed all the parameter names containing "_url" to instead use 1003 "_uri" 1005 o Updated example text for forming Client Configuration Endpoint URL 1007 -06 1009 o Removed secret_rotation as a client-initiated action, including 1010 removing client secret rotation endpoint and parameters. 1012 o Changed _links structure to single value registration_access_url. 1014 o Collapsed create/update/read responses into client info response. 1016 o Changed return code of create action to 201. 1018 o Added section to describe suggested generation and composition of 1019 Client Registration Access URL. 1021 o Added clarifying text to PUT and POST requests to specify JSON in 1022 the body. 1024 o Added Editor's Note to DELETE operation about its inclusion. 1026 o Added Editor's Note to registration_access_url about alternate 1027 syntax proposals. 1029 -05 1030 o changed redirect_uri and contact to lists instead of space 1031 delimited strings 1033 o removed operation parameter 1035 o added _links structure 1037 o made client update management more RESTful 1039 o split endpoint into three parts 1041 o changed input to JSON from form-encoded 1043 o added READ and DELETE operations 1045 o removed Requirements section 1047 o changed token_endpoint_auth_type back to 1048 token_endpoint_auth_method to match OIDC who changed to match us 1050 -04 1052 o removed default_acr, too undefined in the general OAuth2 case 1054 o removed default_max_auth_age, since there's no mechanism for 1055 supplying a non-default max_auth_age in OAuth2 1057 o clarified signing and encryption URLs 1059 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1060 match OIDC 1062 -03 1064 o added scope and grant_type claims 1066 o fixed various typos and changed wording for better clarity 1068 o endpoint now returns the full set of client information 1070 o operations on client_update allow for three actions on metadata: 1071 leave existing value, clear existing value, replace existing value 1072 with new value 1074 -02 1076 o Reorganized contributors and references 1077 o Moved OAuth references to RFC 1079 o Reorganized model/protocol sections for clarity 1081 o Changed terminology to "client register" instead of "client 1082 associate" 1084 o Specified that client_id must match across all subsequent requests 1086 o Fixed RFC2XML formatting, especially on lists 1088 -01 1090 o Merged UMA and OpenID Connect registrations into a single document 1092 o Changed to form-paramter inputs to endpoint 1094 o Removed pull-based registration 1096 -00 1098 o Imported original UMA draft specification 1100 Authors' Addresses 1102 Justin Richer (editor) 1103 The MITRE Corporation 1105 Email: jricher@mitre.org 1107 John Bradley 1108 Ping Identity 1110 Email: ve7jtb@ve7jtb.com 1112 Michael B. Jones 1113 Microsoft 1115 Email: mbj@microsoft.com 1117 Maciej Machulak 1118 Newcastle University 1120 Email: m.p.machulak@ncl.ac.uk 1121 URI: http://ncl.ac.uk/