idnits 2.17.1 draft-ietf-oauth-dyn-reg-04.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 (January 7, 2013) is 4120 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 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: 4 errors (**), 0 flaws (~~), 2 warnings (==), 2 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: July 11, 2013 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 January 7, 2013 12 OAuth Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-04 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth Clients at an Authorization Server. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on July 11, 2013. 37 Copyright Notice 39 Copyright (c) 2013 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . . . . . . . . 13 75 3.5. Rotate Secret Request . . . . . . . . . . . . . . . . . . 13 76 3.6. Rotate Secret Response . . . . . . . . . . . . . . . . . . 14 77 3.7. Client Registration Error Response . . . . . . . . . . . . 15 78 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 79 5. Security Considerations . . . . . . . . . . . . . . . . . . . 16 80 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 81 7. Document History . . . . . . . . . . . . . . . . . . . . . . . 17 82 8. Normative References . . . . . . . . . . . . . . . . . . . . . 18 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 19 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 requiring the two parties to interact before hand. 90 Nevertheless, in order for the authorization server to accurately and 91 securely represent to end-users which client is seeking authorization 92 to 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 [RFC6749]. 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 RECOMMENDED. A space-delimited list of redirect URIs for use in 205 the Authorization Code and Implicit grant types. An Authorization 206 Server SHOULD require registration of valid redirect URIs for all 207 clients to protect against token and credential theft attacks. 209 client_name 210 RECOMMENDED. Human-readable name of the Client to be presented to 211 the user. If omitted, the Authorization Server MAY display to the 212 user the raw client_id value instead. 214 client_url 215 RECOMMENDED. URL of the homepage of the Client. If present, the 216 server SHOULD display this URL to the end user in a clickable 217 fashion. 219 logo_url 220 OPTIONAL. URL that references a logo for the Client application. 221 If present, the server SHOULD display this image to the end user 222 during approval. 224 contacts 225 OPTIONAL. Space delimited list of email addresses for people 226 responsible for this client. The Authorization Server MAY may 227 these addresses available to end users for support queries. An 228 Authorization Server MAY use these email addresses as identifiers 229 for an administrative page for this client. 231 tos_url 232 OPTIONAL. URL that points to a human-readable Terms of Service 233 for the Client. The Authorization Server SHOULD display this URL 234 to the End-User if it is given. 236 token_endpoint_auth_type 237 OPTIONAL. The requested authentication type for the Token 238 Endpoint. Valid values are: 240 * "none": this is a public client as defined in OAuth 2.0 and 241 does not have a client secret 243 * "client_secret_post": the client uses the HTTP POST parameters 244 defined in OAuth2.0 section 2.3.1 246 * "client_secret_basic": the client uses HTTP Basic defined in 247 OAuth 2.0 section 2.3.1 249 * "client_secret_jwt": the client uses the JWT Assertion profile 250 with a symmetric secret issued by the server 252 * "private_key_jwt": the client uses the JWT Assertion profile 253 with its own private key 255 Other Authentication methods may be defined by extension. If 256 unspecified or omitted, the default is "client_secret_basic", 257 denoting HTTP Basic Authentication Scheme as specified in Section 258 2.3.1 of OAuth 2.0. 260 scope 261 OPTIONAL. Space separated list of scopes that the client will be 262 allowed to request tokens for. If omitted, an Authorization 263 Server MAY register a Client with a default set of allowed scopes. 265 grant_type 266 OPTIONAL. Space separated list of grant types that a client may 267 use. These grant types are defined as follows: 269 * "authorization_code": The Authorization Code Grant described in 270 OAuth2 Section 4.1. 272 * "implicit": The Implicit Grant described in OAuth2 Section 4.2. 274 * "password": The Resource Owner Password Credentials Grant 275 described in OAuth2 Section 4.3 277 * "client_credentials": The Client Credentials Grant described in 278 OAuth2 Section 4.4 280 * "refresh_token": The Refresh Token Grant described in OAuth2 281 Section 6. 283 Authorization Servers MAY allow for other values as defined in 284 grant type extensions to OAuth2. The extension process is 285 described in OAuth2 Section 2.5, and the value of this parameter 286 MUST be the same as the value of the grant_type parameter defined 287 in the extension. 289 policy_url 290 OPTIONAL. A URL location that the Client provides to the End-User 291 to read about the how the profile data will be used. The 292 Authorization Server SHOULD display this URL to the End-User if it 293 is given. 295 jwk_url 296 OPTIONAL. URL for the Client's JSON Web Key [JWK] document that 297 is used for signing requests, such as requests to the Token 298 Endpoint using the "private_key_jwt" assertion client credential. 299 If the Client registers both "x509_url" and "jwk_url", the keys 300 contained in both formats MUST be the same. 302 jwk_encryption_url 303 OPTIONAL. URL for the Client's JSON Web Key [JWK] that the server 304 can use to encrypt responses to the Client. If the Client 305 registers both "jwk_encryption_url" and "x509_encryption_url", the 306 keys contained in both formats MUST be the same. 308 x509_url 309 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 310 Certificate chain that is used for signing requests, such as 311 requests to the Token Endpoint using the "private_key_jwt" 312 assertion client credential. If the Client registers both 313 "x509_url" and "jwk_url", the keys contained in both formats MUST 314 be the same. 316 x509_encryption_url 317 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 318 Certificate chain that the server can use to encrypt responses to 319 the Client. If the Client registers both "jwk_encryption_url" and 320 "x509_encryption_url", the keys contained in both formats SHOULD 321 be the same. 323 3. Client Registration Endpoint 325 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 326 this document that is designed to allow a Client to register itself 327 with the Authorization Server. The Client Registration Endpoint MUST 328 accept HTTP POST messages with request parameters encoded in the 329 entity body using the "application/x-www-form-urlencoded" format. 330 The Client Registration Endpoint MUST be protected by a transport- 331 layer security mechanism, and the server MUST support TLS 1.2 RFC 332 5246 [RFC5246] and/or TLS 1.0 [RFC2246] and MAY support additional 333 transport-layer mechanisms meeting its security requirements. When 334 using TLS, the Client MUST perform a TLS/SSL server certificate 335 check, per RFC 6125 [RFC6125]. 337 The Endpoint defines three operations that a client can take on it, 338 switched by the "operation" parameter: 340 o "client_register": request that the Authorization Server generate 341 a new Client Identifier (and optionally a Client Secret) and 342 associate it with the set of presented metadata (Section 2) 344 o "client_update": update the metadata (Section 2) associated with a 345 Client Identifier 347 o "rotate_secret": requst a new Registration Access Token and, if 348 applicable, a Client Secret for a Client 350 The Client Registration Endpoint MAY accept an initial authorization 351 credential in the form of an OAuth 2.0 [RFC6749] access token in 352 order to limit registration to only previously authorized parties. 353 The method by which this access token is obtained by the registrant 354 is generally out-of-band and is out of scope of this specification. 356 In order to support open registration and facilitate wider 357 interoperability, the Client Registration Endpoint SHOULD allow 358 initial "client_register" requests with no authentication. These 359 requests MAY be rate-limited or otherwise limited to prevent a 360 denial-of-service attack on the Client Registration Endpoint. 362 In order to facilitate registered clients updating their information, 363 the Client Registration Endpoint issues a Request Access Token for 364 clients to securely identify themselves in future connections. As 365 such, the Endpoint MUST accept requests with OAuth 2.0 Bearer Tokens 366 [RFC6750] for these operations, whether or not the initial 367 "client_register" call requires authentication of some form. 369 These two aspects, operation selection and client authentication, are 370 represented by two parameters common to all operations: 372 operation 373 REQUIRED. Valid values are "client_register", "rotate_secret", 374 and "client_update", as described above. 376 access_token 377 OPTIONAL. An OAuth2 Bearer token used to access the Client 378 Registration Endpoint, as defined in OAuth2 Bearer [RFC6750]. 379 This parameter MUST NOT be sent if the Access Token is sent in the 380 HTTP Authorization header as described in Section 7.1 of OAuth 2.0 381 [RFC6749]. Access Tokens sent in the authorization header must be 382 OAuth 2.0 Bearer Tokens [RFC6750]. 384 Each operation takes a different parameter set, and all operations 385 are described below. 387 The Client Registration Endpoint MUST ignore all parameters it does 388 not understand. 390 3.1. Client Registration Request 392 This operation registers a new client to the Authorization Server. 393 The Authorization Server assigns this client a unique Client 394 Identifier, optionally assigns a Client Secret, and associates the 395 metadata given in the request with the issued Client Identifier. The 396 request includes the two parameters described above as well as any 397 parameters described in Client Metadata (Section 2). The 398 Authorization Server MAY provision default values for any items 399 omitted in the Client Metadata. 401 operation 402 REQUIRED. MUST have the value "client_register" 403 access_token 404 OPTIONAL. OAuth2 Access token used to restrict new client 405 registration. This parameter MUST NOT be sent if the Access Token 406 is sent in the HTTP Authorization header as described in Section 407 7.1 of OAuth 2.0 [RFC6749]. Access Tokens sent in the 408 authorization header must be OAuth 2.0 Bearer Tokens [RFC6750]. 409 redirect_uris RECOMMENDED 410 client_name RECOMMENDED 411 client_url RECOMMENDED 412 logo_url OPTIONAL 413 contacts OPTIONAL 414 tos_url OPTIONAL 415 token_endpoint_auth_type OPTIONAL 416 policy_url OPTIONAL 417 scope OPTIONAL 418 grant_type OPTIONAL 419 jwk_url OPTIONAL 420 jwk_encryption_url OPTIONAL 421 x509_url OPTIONAL 422 x509_encryption_url OPTIONAL 423 For example, a client could send the following registration request 424 to the Client Registration Endpoint: 426 Following is a non-normative example request (with line wraps for 427 display purposes only): 428 POST /register HTTP/1.1 429 Accept: application/x-www-form-urlencoded 430 Host: server.example.com 432 operation=client_register 433 &redirect_uris=https://client.example.org/callback 434 %20https://client.example.org/callback2 435 &client_name=My%20Example%20Client 436 &token_endpoint_auth_type=client_secret_basic%20client_secret_post 437 &scope=read%20write%20dolphin 438 &logo_url=https://client.example.org/logo.png 439 &jwk_url=https://client.example.org/my_rsa_public_key.jwk 441 3.2. Client Registration Response 443 Upon successful registration, the Client Registration Endpoint 444 returns the newly-created Client Identifier and, if applicable, a 445 Client Secret, along with all registered metadata (Section 2) about 446 this client, including any fields provisioned by the Authorization 447 Server itself. The Authorization Server MAY reject or replace any of 448 the client's requested field values and substitute them with suitable 449 values. If this happens, the Authorization Server MUST include these 450 fields in the response to the client. 452 The response also contains a Registration Access Token that is to be 453 used by the client to perform subsequent operations at this endpoint, 454 such as "client_update" and "rotate_secret". 456 All of the response items are returned as a JSON document [RFC4627] 457 with the following fields as top-level members of the root JSON 458 object. 460 client_id 461 REQUIRED. The unique Client identifier, MUST NOT be currently 462 valid for any other registered Client. 464 client_secret 465 OPTIONAL. The Client secret. This MUST be unique for each 466 "client_id". This value is used by confidential clients to 467 authenticate to the Token Endpoint as described in OAuth 2.0 468 Section 2.3.1. 470 registration_access_token 471 REQUIRED. The Access token to be used by the client to perform 472 "client_update" and "rotate_secret" requests. 474 issued_at 475 OPTIONAL. Specifies the timestamp when the Client Identifier was 476 issued. The timestamp value MUST be a positive integer. The 477 value is expressed in the number of seconds since January 1, 1970 478 00:00:00 GMT. 480 expires_at 481 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 482 measured in UTC that the "client_secret" will expire or "0" if 483 they do not expire. See RFC 3339 [RFC3339] for details regarding 484 date/times in general and UTC in particular. 486 Following is a non-normative example response: 487 HTTP/1.1 200 OK 488 Content-Type: application/json 489 Cache-Control: no-store 491 { 492 "client_id":"s6BhdRkqt3", 493 "client_secret": "cf136dc3c1fc93f31185e5885805d", 494 "scope": "read write dolphin", 495 "grant_type": "authorization_code refresh_token", 496 "token_endpoint_auth_type": "client_secret_basic client_secret_post", 497 "logo_url": "https://client.example.org/logo.png", 498 "jwk_url": "https://client.example.org/my_rsa_public_key.jwk", 499 "registration_access_token": "reg-23410913-abewfq.123483", 500 "expires_at":2893276800 501 } 503 3.3. Client Update Request 505 This operation updates a previously-registered client with new 506 metadata at the Authorization Server. This request MUST be protected 507 by the Registration Authorization Token associated with the Client. 509 This request MAY include any fields described in Client Metadata 510 (Section 2). If included in the request, valid values of Client 511 Metadata fields in this request MUST replace, not augment, the values 512 previously associated with this Client. Empty values in Client 513 Metadata MUST be taken as a request to clear any existing value of 514 that field. Omitted values in the Client Metadata MUST remain 515 unchanged by the Authorization Server. The Authorization Server MAY 516 replace any invalid values with suitable values. 518 operation 519 REQUIRED, MUST have the value "client_update" 520 access_token 521 REQUIRED, unless presented in the Authorization Header as in 522 OAuth2 Bearer [RFC6750]. The Registration Access Token that was 523 issued during the "client_register" step, or previous 524 "client_update" or "rotate_secret" calls. 525 redirect_uris RECOMMENDED 526 client_name RECOMMENDED 527 client_url RECOMMENDED 528 logo_url OPTIONAL 529 contacts OPTIONAL 530 tos_url OPTIONAL 531 token_endpoint_auth_type OPTIONAL 532 policy_url OPTIONAL 533 jwk_url OPTIONAL 534 jwk_encryption_url OPTIONAL 535 x509_url OPTIONAL 536 x509_encryption_url OPTIONAL 537 For example, a client could send the following request to the Client 538 Registration Endpoint to update the client registration in the above 539 example: 541 Following is a non-normative example request (with line wraps for 542 display purposes only): 543 POST /register HTTP/1.1 544 Accept: application/x-www-form-urlencoded 545 Host: server.example.com 546 Authorization: Bearer reg-23410913-abewfq.123483 548 operation=client_update 549 &redirect_uri=https://client.example.org/callback 550 %20https://client.example.org/alt 551 &client_name=My%20New%20Example%20 552 &logo_url=https://client.example.org/newlogo.png 554 3.4. Client Update Response 556 Upon successful update, the Client Registration Endpoint returns the 557 Client ID, along with all current registered metadata (Section 2) 558 about this client, including any fields provisioned by the 559 Authorization Server itself. The Authorization Server MAY reject or 560 replace any of the client's requested field values and substitute 561 them suitable values. If this happens, the Authorization Server MUST 562 include these fields in the response to the client. 564 The Authorization Server MUST NOT include the Client Secret or 565 Request Access Token in this response. 567 These fields are returned in a JSON Document [RFC4627] as top-level 568 members of the root JSON object. 570 client_id 571 REQUIRED. The unique Client identifier, MUST equal the value of 572 the client_id returned in the original client_register request. 574 Following is a non-normative example response: 575 HTTP/1.1 200 OK 576 Content-Type: application/json 577 Cache-Control: no-store 579 { 580 "client_id": "s6BhdRkqt3", 581 "client_name": "My New Example", 582 "redirect_uri": 583 "https://client.example.org/callback https://client.example.org/alt" 584 "scope": "read write dolphin", 585 "grant_type": "authorization_code refresh_token", 586 "token_endpoint_auth_type": "client_secret_basic client_secret_post", 587 "logo_url": "https://client.example.org/newlogo.png", 588 "jwk_url": "https://client.example.org/my_rsa_public_key.jwk", 589 } 591 3.5. Rotate Secret Request 593 This operation allows the client to rotate its current Registration 594 Access Token as well as its Client Secret, if it has one. 596 operation 597 REQUIRED. MUST have the value rotate_secret 599 access_token 600 REQUIRED, unless presented in the Authorization Header as in 601 OAuth2 Bearer [RFC6750]. The Registration Access Token that was 602 issued during the "client_register" step, or previous 603 "client_update" or "rotate_secret" calls. 605 Following is a non-normative example request (with line wraps for 606 display purposes only): 607 POST /register HTTP/1.1 608 Accept: application/x-www-form-urlencoded 609 Host: server.example.com 610 Authorization: Bearer reg-23410913-abewfq.123483 612 operation=rotate_secret 614 3.6. Rotate Secret Response 616 Upon successful rotation of the Registration Access Token, and 617 optionally the Client Secret, the Client Registration Endpoint 618 returns a JSON document [RFC4627] with the following fields as top- 619 level members of the root JSON object. This response MUST NOT 620 include any other client metadata. 622 client_id 623 REQUIRED. The unique Client identifier, MUST match the client_id 624 issued in the original client_register request. 626 client_secret 627 REQUIRED if the server initially issued this Client a Client 628 Secret, otherwise the server MUST NOT return a value. The value 629 MUST be unique for each "client_id". 631 registration_access_token 632 REQUIRED The Access token to be used by the client to perform 633 subsequent "client_update" and "rotate_secret" requests. 635 issued_at 636 OPTIONAL. Specifies the timestamp when the identifier was issued. 637 The timestamp value MUST be a positive integer. The value is 638 expressed in the number of seconds since January 1, 1970 00:00:00 639 GMT. 641 expires_at 642 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 643 measured in UTC that the "client_secret" will expire or "0" if 644 they do not expire. See RFC 3339 [RFC3339] for details regarding 645 date/times in general and UTC in particular. 647 Following is a non-normative example response: 648 HTTP/1.1 200 OK 649 Content-Type: application/json 650 Cache-Control: no-store 652 { 653 "client_id":"s6BhdRkqt3", 654 "client_secret": "7fce6c93f31185e5885805d", 655 "registration_access_token": "reg-02348913-oieqer.983421", 656 "expires_at":2893276800 657 } 659 The Authorization Server SHOULD discard and invalidate the Request 660 Access Token and the Client Secret associated with this Client after 661 successful completion of this request. 663 3.7. Client Registration Error Response 665 When an OAuth error condition occurs, the Client Registration 666 Endpoint returns an Error Response as defined in Section 5.2 of the 667 OAuth 2.0 specification. 669 When a registration error condition occurs, the Client Registration 670 Endpoint returns a HTTP 400 status code including a JSON object 671 [RFC4627] describing the error in the response body. 673 The JSON object contains two members: 675 error 676 The error code, a single ASCII string. 678 error_description 679 The additional text description of the error for debugging. 681 This specification defines the following error codes: 683 invalid_operation 684 The value of "operation" is invalid or not supported. 686 invalid_redirect_uri 687 The value of one or more "redirect_uris" is invalid. 689 invalid_client_metadata 690 The value of one of the client metadata (Section 2) fields is 691 invalid and the server has rejected this request. Note that an 692 Authorization server MAY choose to substitute a valid value for 693 any requested parameter of a client's metadata. 695 Following is a non-normative example of an error response (with line 696 wraps for display purposes only): 697 HTTP/1.1 400 Bad Request 698 Content-Type: application/json 699 Cache-Control: no-store 701 { 702 "error":"invalid_operation", 703 "error_description":"The value of the operation parameter must 704 be one of client_register, rotate_secret or client_update." 705 } 707 4. IANA Considerations 709 This document makes no requests of IANA. 711 5. Security Considerations 713 [[ Editor's note: Following are some security considerations taken 714 from the UMA and OpenID Connect source drafts. These need to be 715 massaged into a properly generic set of considerations. ]] 717 Since requests to the Client Registration Endpoint result in the 718 transmission of clear-text credentials (in the HTTP request and 719 response), the server MUST require the use of a transport-layer 720 security mechanism when sending requests to the Registration 721 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 722 TLS 1.0 [RFC2246] and MAY support additional transport-layer 723 mechanisms meeting its security requirements. When using TLS, the 724 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 725 [RFC6125]. 727 As this endpoint is an OAuth2 Protected Resource, requests to the 728 Registration Endpoint SHOULD have some rate limiting on failures to 729 prevent the Registration Access Token from being disclosed though 730 repeated access attempts. 732 The authorization server MUST treat all client metadata as self- 733 asserted. A rogue Client might use the name and logo for the 734 legitimate Client, which it is trying to impersonate. An 735 Authorization Server needs to take steps to mitigate this phishing 736 risk, since the logo could confuse users into thinking they're 737 logging in to the legitimate Client. For instance, an Authorization 738 Server could warn if the domain/site of the logo doesn't match the 739 domain/site of redirect URIs. An Authorization Server can also 740 present warning messages to end users about untrusted Clients in all 741 cases, especially if such clients have been dynamically registered 742 and have not been trusted by any users at the Authorization Server 743 before. 745 In a situation where the Authorization Server is supporting open 746 Client registration, it must be extremely careful with any URL 747 provided by the Client that will be displayed to the user (e.g. 748 "logo_url" and "policy_url"). A rogue Client could specify a 749 registration request with a reference to a drive-by download in the 750 "policy_url". The Authorization Server should check to see if the 751 "logo_url" and "policy_url" have the same host as the hosts defined 752 in the array of "redirect_uris". 754 While the Client Secret can expire, the Registration Access Token 755 should not expire while a client is still actively registered. If 756 this token were to expire, a Client could be left in a situation 757 where it has no means of updating itself and must register itself 758 anew. As the Registration Access Tokens are long-term credentials, 759 they MUST be protected by the Client as a secret. [[ Editor's note: 760 with the right error codes returned from client_update, the AS could 761 force the Client to call rotate_secret before going forward, 762 lessening the window for abuse of a leaked registration token. ]] 764 6. Acknowledgments 766 The authors thank the OAuth Working Group, the User-Managed Access 767 Working Group, and the OpenID Connect Working Group participants for 768 their input to this document. In particular, the following 769 individuals have been instrumental in their review and contribution 770 to various versions of this document: Torsten Lodderstedt, Eve Maler, 771 Thomas Hardjono, Christian Scholz, Nat Sakimura, George Fletcher, 772 Amanda Anganes, and Domenico Catalano. 774 7. Document History 776 [[ to be removed by RFC editor before publication as an RFC ]] 778 - 04 780 o removed default_acr, too undefined in the general OAuth2 case 782 o removed default_max_auth_age, since there's no mechanism for 783 supplying a non-default max_auth_age in OAuth2 785 o clarified signing and encryption URLs 786 o changed token_endpoint_auth_method to token_endpoint_auth_type to 787 match OIDC 789 - 03 791 o added scope and grant_type claims 793 o fixed various typos and changed wording for better clarity 795 o endpoint now returns the full set of client information 797 o operations on client_update allow for three actions on metadata: 798 leave existing value, clear existing value, replace existing value 799 with new value 801 - 02 803 o Reorganized contributors and references 805 o Moved OAuth references to RFC 807 o Reorganized model/protocol sections for clarity 809 o Changed terminology to "client register" instead of "client 810 associate" 812 o Specified that client_id must match across all subsequent requests 814 o Fixed RFC2XML formatting, especially on lists 816 - 01 818 o Merged UMA and OpenID Connect registrations into a single document 820 o Changed to form-paramter inputs to endpoint 822 o Removed pull-based registration 824 - 00 826 o Imported original UMA draft specification 828 8. Normative References 830 [JWK] Jones, M., "JSON Web Key (JWK)", May 2012. 832 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 833 Requirement Levels", BCP 14, RFC 2119, March 1997. 835 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 836 RFC 2246, January 1999. 838 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 839 Internet: Timestamps", RFC 3339, July 2002. 841 [RFC4627] Crockford, D., "The application/json Media Type for 842 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 844 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 845 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 847 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 848 Verification of Domain-Based Application Service Identity 849 within Internet Public Key Infrastructure Using X.509 850 (PKIX) Certificates in the Context of Transport Layer 851 Security (TLS)", RFC 6125, March 2011. 853 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 854 RFC 6749, October 2012. 856 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 857 Framework: Bearer Token Usage", RFC 6750, October 2012. 859 Authors' Addresses 861 Justin Richer (editor) 862 The MITRE Corporation 864 Phone: 865 Fax: 866 Email: jricher@mitre.org 867 URI: 869 John Bradley 870 Ping Identity 872 Email: ve7jtb@ve7jtb.com 873 Michael B. Jones 874 Microsoft 876 Email: mbj@microsoft.com 878 Maciej Machulak 879 Newcastle University 881 Email: m.p.machulak@ncl.ac.uk 882 URI: http://ncl.ac.uk/