idnits 2.17.1 draft-ietf-oauth-dyn-reg-02.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 (November 27, 2012) is 4165 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'JWA' is defined on line 751, but no explicit reference was found in the text == Unused Reference: 'JWE' is defined on line 753, but no explicit reference was found in the text == Unused Reference: 'JWS' is defined on line 758, but no explicit reference was found in the text == Unused Reference: 'JWT' is defined on line 761, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 770, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 778, but no explicit reference was found in the text == Unused Reference: 'RFC5785' is defined on line 784, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'JWA' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWE' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWK' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWS' -- Possible downref: Non-RFC (?) normative reference: ref. 'JWT' ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5785 (Obsoleted by RFC 8615) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 6 errors (**), 0 flaws (~~), 9 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track J. Bradley 5 Expires: May 31, 2013 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 November 27, 2012 12 OAuth Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-02 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth Clients at an Authorizaiton Server. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on May 31, 2013. 37 Copyright Notice 39 Copyright (c) 2012 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 56 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 4 58 1.3.1. The client needs to be uniquely identifiable by 59 the authorization server . . . . . . . . . . . . . . . 4 60 1.3.2. The authorization server must collect metadata 61 about a client for later user interaction . . . . . . 4 62 1.3.3. The authorization server should have the option of 63 strongly authenticating the client and its metadata . 4 64 1.3.4. Dynamic client registration must be possible from 65 both web-server applications and applications with 66 other capabilities and limitations, such as native 67 applications . . . . . . . . . . . . . . . . . . . . . 4 68 1.3.5. Transaction integrity must be ensured . . . . . . . . 5 69 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 5 70 3. Client Registration Endpoint . . . . . . . . . . . . . . . . . 7 71 3.1. Client Registration Request . . . . . . . . . . . . . . . 9 72 3.2. Client Registration Response . . . . . . . . . . . . . . . 10 73 3.3. Client Update Request . . . . . . . . . . . . . . . . . . 11 74 3.4. Client Update Response . . . . . . . . . . . . . . . . . . 12 75 3.5. Rotate Secret Request . . . . . . . . . . . . . . . . . . 12 76 3.6. Rotate Secret Response . . . . . . . . . . . . . . . . . . 13 77 3.7. Client Registration Error Response . . . . . . . . . . . . 14 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 80 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 81 7. Document History . . . . . . . . . . . . . . . . . . . . . . . 16 82 8. Normative References . . . . . . . . . . . . . . . . . . . . . 17 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 85 1. Introduction 87 In some use-case scenarios, it is desirable or necessary to allow 88 OAuth clients to obtain authorization from an OAuth authorization 89 server without the two parties having previously interacted. 90 Nevertheless, in order for the authorization server to accurately 91 represent to end-users which client is seeking authorization to 92 access the end-user's resources, a method for automatic and unique 93 registration of clients is needed. The OAuth2 authorization 94 framework does not define how the relationship between the Client and 95 the Authorization Server is initialized, or how a given client is 96 assigned a unique Client Identifier. Historically, this has happened 97 out-of-band from the OAuth protocol. This draft provides a mechanism 98 for a client to register itself with the Authorization Server, which 99 can be used to dynamically provision a Client Identifier, and 100 optionally a Client Secret. 102 As part of the registration process, this specification also defines 103 a mechanism for the client to present the Authorization Server with a 104 set of metadata, such as a display name and icon to be presented to 105 the user during the authorization step. This draft provides a method 106 for the client to register and update this information over time. 108 1.1. Notational Conventions 110 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 111 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 112 document are to be interpreted as described in [RFC2119]. 114 Unless otherwise noted, all the protocol parameter names and values 115 are case sensitive. 117 1.2. Terminology 119 This specification uses the terms "Access Token", "Refresh Token", 120 "Authorization Code", "Authorization Grant", "Authorization Server", 121 "Authorization Endpoint", "Client", "Client Identifier", "Client 122 Secret", "Protected Resource", "Resource Owner", "Resource Server", 123 and "Token Endpoint" defined by OAuth 2.0 [RFC6750]. 125 This specification defines the following additional terms: 127 o Client Registration Endpoint: The OAuth 2.0 Endpoint through which 128 a Client can request new registration and manage the metadata 129 associated with it. 131 o Registration Access Token: An OAuth 2.0 Bearer Token issued by the 132 Authorization Server through the Client Registration Endpoint 133 which is used by the Client to authenticate itself during update 134 and secret rotation operations. 136 1.3. Requirements 138 [[ Following are proposed requirements for dynamic client 139 registration. This section is intended for discussion and will 140 likely be removed in the final draft. ]] 142 1.3.1. The client needs to be uniquely identifiable by the 143 authorization server 145 In order for an authorization server to do proper user-delegated 146 authorization and prevent unauthorized access it must be able to 147 identify clients uniquely. As is done today in OAuth, the client 148 identifier (and optional secret) should thus be issued by the 149 authorization server and not simply accepted as proposed by the 150 client. 152 1.3.2. The authorization server must collect metadata about a client 153 for later user interaction 155 In order for the authorization server to describe a client to an end- 156 user in an authorization step it needs information about the client. 157 This can be the client name at a minimum, but today servers usually 158 request at least a description, a homepage URL, and an icon when 159 doing manual registration. 161 1.3.3. The authorization server should have the option of strongly 162 authenticating the client and its metadata 164 In order to prevent spoofing of clients and enable dynamic building 165 of strong trust relationships, the authorization server should have 166 the option to verify the provided information. This might be solved 167 using message signature verification. 169 1.3.4. Dynamic client registration must be possible from both web- 170 server applications and applications with other capabilities and 171 limitations, such as native applications 173 Each instance of a native application (that is, the specific instance 174 running on each device) that is installed and run by the same user 175 may need the option of getting a unique client identifier. In this 176 case, there are implications around gathering and displaying enough 177 information to ensure that the end-user is delegating authorization 178 to the intended application. The registration protocol should be 179 simple and flexible enough to allow for multiple types of 180 applications. 182 1.3.5. Transaction integrity must be ensured 184 When a client sends information to a server endpoint, it might take 185 time for this data to propagate through big server installations that 186 spread across various data centers. Care needs to be taken that 187 subsequent interactions with the user after the registration process, 188 such as an authorization request, show the correct data. 190 2. Client Metadata 192 Clients generally have an array of metadata associated with their 193 unique Client Identifier at the Authorization Server. These can 194 range from human-facing display strings, such as a client name, to 195 items that impact the security of the protocol, such as the list of 196 valid redirect URIs. 198 Extensions and profiles of this specification MAY expand this list, 199 but MUST at least accept all parameters on this list. The 200 Authorization Server MUST ignore any additional parameters sent by 201 the Client that it does not understand. 203 redirect_uris 204 REQUIRED A space-delimited list of redirect URIs. 206 client_name 207 RECOMMENDED. Human-readable name of the Client to be presented to 208 the user. 210 client_url 211 RECOMMENDED. URL of the homepage of the client. If present, the 212 server SHOULD display this URL to the end user. 214 logo_url 215 OPTIONAL. URL that references a logo for the Client application. 216 If present, the server SHOULD display this image to the end user 217 during approval. 219 contacts 220 OPTIONAL. Space delimited list of email addresses for people 221 responsible for this client. The Authorization Server MAY may 222 these addresses available to end users for support queries. An 223 Authorization Server MAY use these email addresses as identifiers 224 for an administrative page for this client. 226 tos_url 227 OPTIONAL. URL that points to a human-readable Terms of Service 228 for the Client. The Authorization Server SHOULD display this URL 229 to the End-User if it is given. 231 token_endpoint_auth_method 232 OPTIONAL. The requested authentication type for the Token 233 Endpoint. Valid values are: 235 * "none" this is a public client as defined in OAuth 2.0 and does 236 not have a client secret 238 * "client_secret_post" the client uses the HTTP POST parameters 239 defined in OAuth2.0 section 2.3.1 241 * "client_secret_basic" the client uses HTTP Basic defined in 242 OAuth 2.0 section 2.3.1 244 * "client_secret_jwt" the client uses the JWT Assertion profile 245 with a semetric secret issued by the server 247 * _private_key_jwt_ the client uses the JWT Assertion profile 248 with its own private key 250 Other Authentication methods may be defined by extension. If 251 unspecified or omitted, the default is "client_secret_basic" HTTP 252 Basic Authentication Scheme as specified in Section 2.3.1 of OAuth 253 2.0 [RFC6749]. 255 policy_url 256 OPTIONAL. A URL location that the Client provides to the End-User 257 to read about the how the profile data will be used. The 258 Authorization Server SHOULD display this URL to the End-User if it 259 is given. 261 jwk_url 262 OPTIONAL. URL for the Client's JSON Web Key [JWK] document that 263 is used for signing Token Endpoint Requests. If 264 jwk_encryption_url is not provided, the key at jwk_url is also 265 used as the key to encrypt responses to the Client. If the Client 266 registers both "x509_url" and "jwk_url", the keys contained in 267 both formats MUST be the same. 269 jwk_encryption_url 270 OPTIONAL. URL for the Client's JSON Web Key [JWK] that is used to 271 encrypt any responses to the Client. If the Client registers both 272 "jwk_encryption_url" and "x509_encryption_url", the keys contained 273 in both formats MUST be the same. 275 x509_url 276 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 277 Certificate chain that is used for signing Token Endpoint 278 Requests. If "x509_encryption_url" is not provided, "x509_url" it 279 is also used to encrypt responses to the Client. If the Client 280 registers both "x509_url" and "jwk_url", the keys contained in 281 both formats MUST be the same. 283 x509_encryption_url 284 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 285 Certificate chain that is used to encrypt the ID Token and User 286 Info Endpoint Responses to the Client. If the Client registers 287 both "jwk_encryption_url" and "x509_encryption_url", the keys 288 contained in both formats SHOULD be the same. 290 default_max_age 291 OPTIONAL. Maximum age of a session in integer seconds. Specifies 292 that the End-User must be actively authenticated if any present 293 authentication is older than the specified number of seconds by 294 default. 296 default_acr 297 OPTIONAL. Default Authentication Context class Reference. String 298 that specifies the default authentication context value that the 299 Authorization server must use for processing requests from this 300 client. 302 3. Client Registration Endpoint 304 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 305 this document that is designed to allow a Client to register itself 306 with the Authorization Server. The Client Registration Endpoint MUST 307 accept HTTP POST messages with request parameters encoded in the 308 entity body using the "application/x-www-form-urlencoded" format. 309 The Client Registration Endpoint MUST be protected by a transport- 310 layer security mechanism when sending requests to the Registration 311 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 312 TLS 1.0 [RFC2246] and MAY support additional transport-layer 313 mechanisms meeting its security requirements. When using TLS, the 314 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 315 [RFC6125]. 317 The Endpoint defines three operations that a client can take on it, 318 switched by the "operation" parameter: 320 o client_register: request that the Authorization Server generate a 321 new Client Identifier (and optionally a Client Secret) and 322 associate it with the set of presented metadata (Section 2) 324 o client_update: update the metadata (Section 2) associated with a 325 Client Identifier 327 o rotate_secret: issue a new Registration Access Token and, if 328 applicable, a Client Secret for a Client 330 In order to facilitate registered clients updating their information, 331 the Client Registration Endpoint issues a request_access_token for 332 clients to securely identify themselves in future connections. As 333 such, the Endpoint MUST accept requests with OAuth 2.0 Bearer Tokens 334 [RFC6750] for these operations. 336 In order to support open registration and facilitate wider 337 interoperability, the Client Registration Endpoint SHOULD allow 338 client_register requests with no further authentication. These 339 requests MAY be rate-limited to prevent a denial-of-service attack on 340 the Client Registration Endpoint. 342 In addition, the Client Registration Endpoint MAY accept an initial 343 authorization credential in the form of an OAuth 2.0 [RFC6749] access 344 token in order to limit registration to only previously authorized 345 parties. The method by which this access token is obtained by the 346 registrant is generally out-of-band and is out of scope of this 347 specification. 349 These two aspects, operation selection and client authentication, are 350 represented by two parameters common to all operations: 352 operation REQUIRED. Values are "client_register" (for new 353 registrations), "rotate_secret" to request rotation of the 354 "client_secret", and "client_update" (for updating parameters of 355 an existing "client_id"). 357 access_token OPTIONAL. An OAuth2 Bearer token used to access the 358 Client Registration Endpoint, as defined in OAuth2 Bearer. This 359 parameter MUST NOT be sent if the Access Token is sent in the HTTP 360 Authorization header as described in Section 7.1 of OAuth 2.0 361 [RFC6749]. Access Tokens sent in the authorization header must be 362 OAuth 2.0 Bearer Tokens [RFC6750]. 364 Each operation takes a different parameter set, and all operations 365 are described below. 367 The Client Registration Endpoint MUST ignore all parameters it does 368 not understand. 370 3.1. Client Registration Request 372 This operation registers a new client to the Authorization Server. 373 The Authorization Server assigns this client a unique Client 374 Identifier, optionally assigns a Client Secret, and associates the 375 metadata given in the request with the issued Client Identifier. The 376 request includes the two parameters described above as well as any 377 parameters described in Client Metadata (Section 2). 379 operation 380 REQUIRED. MUST have the value "client_register" 381 access_token 382 OPTIONAL. used to restrict new client registration. This 383 parameter MUST NOT be sent if the Access Token is sent in the HTTP 384 Authorization header as described in Section 7.1 of OAuth 2.0 385 [RFC6749]. Access Tokens sent in the authorization header must be 386 OAuth 2.0 Bearer Tokens [RFC6750]. 387 redirect_uris REQUIRED 388 client_name RECOMMENDED 389 client_url RECOMMENDED 390 logo_url OPTIONAL 391 contacts OPTIONAL 392 tos_url OPTIONAL 393 token_endpoint_auth_method OPTIONAL 394 policy_url OPTIONAL 395 jwk_url OPTIONAL 396 jwk_encryption_url OPTIONAL 397 x509_url OPTIONAL 398 x509_encryption_url OPTIONAL 399 default_max_age OPTIONAL 400 default_acr OPTIONAL 401 For example, a client could send the following registration request 402 to the Client Registration Endpoint: 404 Following is a non-normative example request (with line wraps for 405 display purposes only): 406 POST /register HTTP/1.1 407 Accept: application/x-www-form-urlencoded 408 Host: server.example.com 410 operation=client_register 411 &redirect_uris=https://client.example.org/callback 412 %20https://client.example.org/callback2 413 &client_name=My%20Example%20Client 414 &logo_url=https://client.example.org/logo.png 415 &token_endpoint_auth_type=client_secret_basic 416 &jwk_url=https://client.example.org/my_rsa_public_key.jwk 418 3.2. Client Registration Response 420 Upon successful registration, the Client Registration Endpoint 421 returns the newly-created Client Identifier and, optionally, a Client 422 Secret. The response also contains a Registration Access Token that 423 is to be used by the client to perform subsequent operations at this 424 endpoint, such as client_update and rotate_secret. These items are 425 returned as a JSON document with the following fields as top-level 426 members of the root JSON object. 428 client_id 429 REQUIRED. The unique Client identifier, MUST NOT be currently 430 valid for any other registered Client. 432 client_secret 433 OPTIONAL. The Client secret. This MUST be unique for each 434 "client_id". This value is used by confidential clients to 435 authenticate to the Token Endpoint as described in OAuth 2.0 436 Section 2.3.1. 438 registration_access_token 439 REQUIRED. The Access token to be used by the client to perform 440 "client_update" and "rotate_secret" requests. 442 issued_at 443 OPTIONAL. Specifies the timestamp when the Client Identifier was 444 issued. The timestamp value MUST be a positive integer. The 445 value is expressed in the number of seconds since January 1, 1970 446 00:00:00 GMT. 448 expires_at 449 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 450 measured in UTC that the "client_secret" will expire or "0" if 451 they do not expire. See RFC 3339 [RFC3339] for details regarding 452 date/times in general and UTC in particular. 454 Following is a non-normative example response: 455 HTTP/1.1 200 OK 456 Content-Type: application/json 457 Cache-Control: no-store 459 { 460 "client_id":"s6BhdRkqt3", 461 "client_secret": 462 "cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d", 463 "registration_access_token": "reg-23410913-abewfq.123483", 464 "expires_at":2893276800 465 } 467 3.3. Client Update Request 469 This operation updates a previously-registered client with new 470 metadata at the Authorization Server. This request MUST be protected 471 by the Registration Authorization Token associated with the Client. 472 This request MAY include any fields described in Client Metadata 473 (Section 2). The values of Client Metadata fields in this request 474 MUST replace (not augment) the values previously associated with this 475 Client. Empty values in Client Metadata MUST be taken as a request 476 to clear any existing value of that field. 478 operation 479 REQUIRED, MUST have the value "client_update" 480 access_token 481 REQUIRED, unless presented in the Authorization Header as in 482 OAuth2 Bearer [RFC6750]. The Registration Access Token that was 483 issued during the client_register step, or previous client_update 484 or rotate_secret calls. 485 redirect_uris REQUIRED 486 client_name RECOMMENDED 487 client_url RECOMMENDED 488 logo_url OPTIONAL 489 contacts OPTIONAL 490 tos_url OPTIONAL 491 token_endpoint_auth_method OPTIONAL 492 policy_url OPTIONAL 493 jwk_url OPTIONAL 494 jwk_encryption_url OPTIONAL 495 x509_url OPTIONAL 496 x509_encryption_url OPTIONAL 497 default_max_age OPTIONAL 498 default_acr OPTIONAL 499 For example, a client could send the following registration request 500 to the Client Registration Endpoint: 502 Following is a non-normative example request (with line wraps for 503 display purposes only): 504 POST /register HTTP/1.1 505 Accept: application/x-www-form-urlencoded 506 Host: server.example.com 507 Authorization: Bearer reg-23410913-abewfq.123483 509 operation=client_update 510 &redirect_uris=https://client.example.org/callback 511 %20https://client.example.org/callback2 512 &client_name=My%20Example%20 513 &logo_url=https://client.example.org/logo.png 514 &token_endpoint_auth_type=client_secret_basic 515 &jwk_url=https://client.example.org/my_rsa_public_key.jwk 517 3.4. Client Update Response 519 Upon successful update, the Client Registration Endpoint returns a 520 JSON document with the following fields as top-level members of the 521 root JSON object. 523 client_id 524 REQUIRED. The unique Client identifier, MUST equal the value of 525 the client_id returned in the original client_register request. 527 Following is a non-normative example response: 528 HTTP/1.1 200 OK 529 Content-Type: application/json 530 Cache-Control: no-store 532 { 533 "client_id":"s6BhdRkqt3", 534 } 536 [[ Editor's note: should this return the entire client data object, 537 for confirmation and review, including any fields that may have been 538 asserted by the AS? ]] 540 3.5. Rotate Secret Request 542 This operation allows the client to rotate its current Registration 543 Access Token as well as its Client Secret, if it has one. 545 operation REQUIRED. MUST have the value rotate_secret 547 access_token REQUIRED. The Registration Access Token that was 548 issued during the client_register step, or previous client_update 549 or rotate_secret calls. This parameter MUST NOT be sent if the 550 Access Token is sent in the HTTP Authorization header as described 551 in Section 7.1 of OAuth 2.0 [RFC6749]. Access Tokens sent in the 552 authorization header must be OAuth 2.0 Bearer Tokens [RFC6750]. 554 Following is a non-normative example request (with line wraps for 555 display purposes only): 556 POST /register HTTP/1.1 557 Accept: application/x-www-form-urlencoded 558 Host: server.example.com 559 Authorization: Bearer reg-23410913-abewfq.123483 561 operation=rotate_secret 563 3.6. Rotate Secret Response 565 Upon successful rotation of the Registration Access Token and 566 optionally the Client Secret, the Client Registration Endpoint 567 returns a JSON document with the following fields as top-level 568 members of the root JSON object. 570 client_id 571 REQUIRED. The unique Client identifier, MUST match the client_id 572 issued in the original client_register request. 574 client_secret 575 REQUIRED if the server initially issued this Client a Client 576 Secret, otherwise the server MUST NOT return a value. The value 577 MUST be unique for each "client_id". 579 registration_access_token 580 REQUIRED The Access token to be used by the client to perform 581 subsequent "client_update" and "rotate_secret" requests. 583 issued_at 584 OPTIONAL. Specifies the timestamp when the identifier was issued. 585 The timestamp value MUST be a positive integer. The value is 586 expressed in the number of seconds since January 1, 1970 00:00:00 587 GMT. 589 expires_at 590 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 591 measured in UTC that the "client_secret" will expire or "0" if 592 they do not expire. See RFC 3339 [RFC3339] for details regarding 593 date/times in general and UTC in particular. 595 Following is a non-normative example response: 596 HTTP/1.1 200 OK 597 Content-Type: application/json 598 Cache-Control: no-store 600 { 601 "client_id":"s6BhdRkqt3", 602 "client_secret": 603 "cf136dc3c1fd9153029bb9c6cc9ecead918bad9887fce6c93f31185e5885805d", 604 "registration_access_token": "this.is.a.access.token.value.ffx83", 605 "expires_at":2893276800 606 } 608 The Authorization Server SHOULD discard and invalidate the Request 609 Access Token and the Client Secret associated with this Client after 610 successful completion of this request. 612 3.7. Client Registration Error Response 614 When an OAuth error condition occurs, the Client Registration 615 Endpoint returns an Error Response as defined in Section 5.2 of the 616 OAuth 2.0 specification. 618 When a registration error condition occurs, the Client Registration 619 Endpoint returns a HTTP 400 status code including a JSON object 620 describing the error in the response body. 622 The JSON object contains two members: 624 error 625 The error code, a single ASCII string. 627 error_description 628 The additional text description of the error for debugging. 630 This specification defines the following error codes: 632 invalid_operation 633 The value of "operation" is invalid or not supported. 635 invalid_redirect_uri 636 The value of one or more "redirect_uris" is invalid. 638 invalid_client_metadata 639 The value of one of the client metadata (Section 2) fields is 640 invalid. 642 Following is a non-normative example of an error response (with line 643 wraps for display purposes only): 644 HTTP/1.1 400 Bad Request 645 Content-Type: application/json 646 Cache-Control: no-store 648 { 649 "error":"invalid_operation", 650 "error_description":"The value of the operation parameter must 651 be one of client_register, rotate_secret or client_update." 652 } 654 4. IANA Considerations 656 This document makes no requests of IANA. 658 5. Security Considerations 660 [[ Editor's note: Following are some security considerations taken 661 whole from the UMA and OpenID Connect source drafts. ]] 663 Since requests to the Client Registration Endpoint result in the 664 transmission of clear-text credentials (in the HTTP request and 665 response), the server MUST require the use of a transport-layer 666 security mechanism when sending requests to the Registration 667 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 668 TLS 1.0 [RFC2246] and MAY support additional transport-layer 669 mechanisms meeting its security requirements. When using TLS, the 670 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 671 [RFC6125]. 673 As this endpoint is an OAuth2 Protected Resource, requests to the 674 Registration Endpoint SHOULD have some rate limiting on failures to 675 prevent the Registration Access Token from being disclosed though 676 repeated access attempts. 678 The authorization server MUST treat all client metadata as self- 679 asserted. A rogue Client might use the name and logo for the 680 legitimate Client, which it is trying to impersonate. An 681 Authorization Server needs to take steps to mitigate this phishing 682 risk, since the logo could confuse users into thinking they're 683 logging in to the legitimate Client. For instance, an Authorization 684 Server could warn if the domain/site of the logo doesn't match the 685 domain/site of redirect URIs. An Authorization Server can also make 686 warnings against untrusted Clients in all cases, especially if 687 they're dynamically registered, have not been trusted by any users at 688 the Authorization Server before. 690 In a situation where the Authorization Server is supporting open 691 Client registration, it must be extremely careful with any URL 692 provided by the Client that will be displayed to the user (e.g. 693 "logo_url" and "policy_url"). A rogue Client could specify a 694 registration request with a reference to a drive-by download in the 695 "policy_url". The Authorization Server should check to see if the 696 "logo_url" and "policy_url" have the same host as the hosts defined 697 in the array of "redirect_uris". 699 While the Client Secret can expire, the Registration Access Token 700 should not expire while a client is still actively registered. If 701 this token were to expire, a Client could be left in a situation 702 where it has no means of updating itself and must register itself 703 anew. As the Registration Access Tokens are long-term credentials, 704 they MUST be protected by the Client as a secret. [[ Editor's note: 705 with the right error codes returned from client_update, the AS could 706 force the Client to call rotate_secret before going forward, 707 lessening the window for abuse of a leaked registration token. ]] 709 6. Acknowledgments 711 The authors thank the OAuth Working Group, the User-Managed Access 712 Working Group, and the OpenID Connect Working Group participants for 713 their input to this document. In particular, the following 714 individuals have been instrumental in their review and contribution 715 to various versions of this document: Torsten Lodderstedt, Eve Maler, 716 Thomas Hardjono, Christian Scholz, Nat Sakimura, George Fletcher, 717 Amanda Anganes, and Domenico Catalano. 719 7. Document History 721 [[ to be removed by RFC editor before publication as an RFC ]] 723 - 02 725 o Reorganized contributors and references 727 o Moved OAuth references to RFC 728 o Reorganized model/protocol sections for clarity 730 o Changed terminology to "client register" instead of "client 731 associate" 733 o Specified that client_id must match across all subsequent requests 735 o Fixed RFC2XML formatting, especially on lists 737 - 01 739 o Merged UMA and OpenID Connect registrations into a single document 741 o Changed to form-paramter inputs to endpoint 743 o Removed pull-based registration 745 - 00 747 o Imported original UMA draft specification 749 8. Normative References 751 [JWA] Jones, M., "JSON Web Algorithms", May 2012. 753 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 754 Encryption (JWE)", May 2012. 756 [JWK] Jones, M., "JSON Web Key (JWK)", May 2012. 758 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 759 Signature", May 2012. 761 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token", 762 May 2012. 764 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 765 Requirement Levels", BCP 14, RFC 2119, March 1997. 767 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 768 RFC 2246, January 1999. 770 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 771 Leach, P., Luotonen, A., and L. Stewart, "HTTP 772 Authentication: Basic and Digest Access Authentication", 773 RFC 2617, June 1999. 775 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 776 Internet: Timestamps", RFC 3339, July 2002. 778 [RFC4627] Crockford, D., "The application/json Media Type for 779 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 781 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 782 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 784 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 785 Uniform Resource Identifiers (URIs)", RFC 5785, 786 April 2010. 788 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 789 Verification of Domain-Based Application Service Identity 790 within Internet Public Key Infrastructure Using X.509 791 (PKIX) Certificates in the Context of Transport Layer 792 Security (TLS)", RFC 6125, March 2011. 794 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 795 RFC 6749, October 2012. 797 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 798 Framework: Bearer Token Usage", RFC 6750, October 2012. 800 Authors' Addresses 802 Justin Richer (editor) 803 The MITRE Corporation 805 Phone: 806 Fax: 807 Email: jricher@mitre.org 808 URI: 810 John Bradley 811 Ping Identity 813 Email: ve7jtb@ve7jtb.com 814 Michael B. Jones 815 Microsoft 817 Email: mbj@microsoft.com 819 Maciej Machulak 820 Newcastle University 822 Email: m.p.machulak@ncl.ac.uk 823 URI: http://ncl.ac.uk/