idnits 2.17.1 draft-ietf-oauth-dyn-reg-03.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 (December 11, 2012) is 4144 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 830, but no explicit reference was found in the text == Unused Reference: 'JWE' is defined on line 832, but no explicit reference was found in the text == Unused Reference: 'JWS' is defined on line 837, but no explicit reference was found in the text == Unused Reference: 'JWT' is defined on line 840, but no explicit reference was found in the text == Unused Reference: 'RFC2617' is defined on line 849, but no explicit reference was found in the text == Unused Reference: 'RFC4627' is defined on line 857, but no explicit reference was found in the text == Unused Reference: 'RFC5785' is defined on line 863, 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: June 14, 2013 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 December 11, 2012 12 OAuth Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-03 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 June 14, 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 . . . . . . . . . . . . . . . . . 8 71 3.1. Client Registration Request . . . . . . . . . . . . . . . 9 72 3.2. Client Registration Response . . . . . . . . . . . . . . . 11 73 3.3. Client Update Request . . . . . . . . . . . . . . . . . . 12 74 3.4. Client Update Response . . . . . . . . . . . . . . . . . . 13 75 3.5. Rotate Secret Request . . . . . . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . . . . . . 18 81 7. Document History . . . . . . . . . . . . . . . . . . . . . . . 18 82 8. Normative References . . . . . . . . . . . . . . . . . . . . . 18 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 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_method 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" HTTP 257 Basic Authentication Scheme as specified in Section 2.3.1 of OAuth 258 2.0 [RFC6749]. 260 scope 261 OPTIONAL. Space separated list of scopes that the client is 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 Token Endpoint Requests. If 298 jwk_encryption_url is not provided, the key at jwk_url is also 299 used as the key to encrypt responses to the Client. If the Client 300 registers both "x509_url" and "jwk_url", the keys contained in 301 both formats MUST be the same. 303 jwk_encryption_url 304 OPTIONAL. URL for the Client's JSON Web Key [JWK] that is used to 305 encrypt any responses to the Client. If the Client registers both 306 "jwk_encryption_url" and "x509_encryption_url", the keys contained 307 in both formats MUST be the same. 309 x509_url 310 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 311 Certificate chain that is used for signing Token Endpoint 312 Requests. If "x509_encryption_url" is not provided, "x509_url" it 313 is also used to encrypt responses to the Client. If the Client 314 registers both "x509_url" and "jwk_url", the keys contained in 315 both formats MUST be the same. 317 x509_encryption_url 318 OPTIONAL. URL for the Client's PEM encoded X.509 Certificate or 319 Certificate chain that is used to encrypt the ID Token and User 320 Info Endpoint Responses to the Client. If the Client registers 321 both "jwk_encryption_url" and "x509_encryption_url", the keys 322 contained in both formats SHOULD be the same. 324 default_max_age 325 OPTIONAL. Maximum age of a session in integer seconds. Specifies 326 that the End-User must be actively authenticated if any present 327 authentication is older than the specified number of seconds by 328 default. 330 default_acr 331 OPTIONAL. Default Authentication Context class Reference. String 332 that specifies the default authentication context value that the 333 Authorization server must use for processing requests from this 334 client. 336 3. Client Registration Endpoint 338 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 339 this document that is designed to allow a Client to register itself 340 with the Authorization Server. The Client Registration Endpoint MUST 341 accept HTTP POST messages with request parameters encoded in the 342 entity body using the "application/x-www-form-urlencoded" format. 343 The Client Registration Endpoint MUST be protected by a transport- 344 layer security mechanism when sending requests to the Registration 345 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 346 TLS 1.0 [RFC2246] and MAY support additional transport-layer 347 mechanisms meeting its security requirements. When using TLS, the 348 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 349 [RFC6125]. 351 The Endpoint defines three operations that a client can take on it, 352 switched by the "operation" parameter: 354 o "client_register": request that the Authorization Server generate 355 a new Client Identifier (and optionally a Client Secret) and 356 associate it with the set of presented metadata (Section 2) 358 o "client_update": update the metadata (Section 2) associated with a 359 Client Identifier 361 o "rotate_secret": issue a new Registration Access Token and, if 362 applicable, a Client Secret for a Client 364 The Client Registration Endpoint MAY accept an initial authorization 365 credential in the form of an OAuth 2.0 [RFC6749] access token in 366 order to limit registration to only previously authorized parties. 367 The method by which this access token is obtained by the registrant 368 is generally out-of-band and is out of scope of this specification. 370 In order to support open registration and facilitate wider 371 interoperability, the Client Registration Endpoint SHOULD allow 372 initial "client_register" requests with no authentication. These 373 requests MAY be rate-limited or otherwise limited to prevent a 374 denial-of-service attack on the Client Registration Endpoint. 376 In order to facilitate registered clients updating their information, 377 the Client Registration Endpoint issues a Request Access Token for 378 clients to securely identify themselves in future connections. As 379 such, the Endpoint MUST accept requests with OAuth 2.0 Bearer Tokens 380 [RFC6750] for these operations, whether or not the initial 381 "client_register" call requires authentication of some form. 383 These two aspects, operation selection and client authentication, are 384 represented by two parameters common to all operations: 386 operation 387 REQUIRED. Values are: 389 * "client_register": Register a new client, receive a Client 390 Identifier, and associate metadata with it. 392 * "rotate_secret": Request rotation of the Registration Access 393 Token and, if applicable, the Client Secret 395 * "client_update": Update the metadata associated with a given 396 Client Identifier. 398 access_token 399 OPTIONAL. An OAuth2 Bearer token used to access the Client 400 Registration Endpoint, as defined in OAuth2 Bearer. This 401 parameter MUST NOT be sent if the Access Token is sent in the HTTP 402 Authorization header as described in Section 7.1 of OAuth 2.0 403 [RFC6749]. Access Tokens sent in the authorization header must be 404 OAuth 2.0 Bearer Tokens [RFC6750]. 406 Each operation takes a different parameter set, and all operations 407 are described below. 409 The Client Registration Endpoint MUST ignore all parameters it does 410 not understand. 412 3.1. Client Registration Request 414 This operation registers a new client to the Authorization Server. 415 The Authorization Server assigns this client a unique Client 416 Identifier, optionally assigns a Client Secret, and associates the 417 metadata given in the request with the issued Client Identifier. The 418 request includes the two parameters described above as well as any 419 parameters described in Client Metadata (Section 2). The 420 Authorization Server MAY provision default values for any items 421 omitted in the Client Metadata. 423 operation 424 REQUIRED. MUST have the value "client_register" 425 access_token 426 OPTIONAL. Used to restrict new client registration. This 427 parameter MUST NOT be sent if the Access Token is sent in the HTTP 428 Authorization header as described in Section 7.1 of OAuth 2.0 429 [RFC6749]. Access Tokens sent in the authorization header must be 430 OAuth 2.0 Bearer Tokens [RFC6750]. 431 redirect_uris RECOMMENDED 432 client_name RECOMMENDED 433 client_url RECOMMENDED 434 logo_url OPTIONAL 435 contacts OPTIONAL 436 tos_url OPTIONAL 437 token_endpoint_auth_method OPTIONAL 438 policy_url OPTIONAL 439 scope OPTIONAL 440 grant_type OPTIONAL 441 jwk_url OPTIONAL 442 jwk_encryption_url OPTIONAL 443 x509_url OPTIONAL 444 x509_encryption_url OPTIONAL 445 default_max_age OPTIONAL 446 default_acr OPTIONAL 447 For example, a client could send the following registration request 448 to the Client Registration Endpoint: 450 Following is a non-normative example request (with line wraps for 451 display purposes only): 452 POST /register HTTP/1.1 453 Accept: application/x-www-form-urlencoded 454 Host: server.example.com 456 operation=client_register 457 &redirect_uris=https://client.example.org/callback 458 %20https://client.example.org/callback2 459 &client_name=My%20Example%20Client 460 &token_endpoint_auth_method=client_secret_basic%20client_secret_post 461 &scope=read%20write%20dolphin 462 &logo_url=https://client.example.org/logo.png 463 &jwk_url=https://client.example.org/my_rsa_public_key.jwk 465 3.2. Client Registration Response 467 Upon successful registration, the Client Registration Endpoint 468 returns the newly-created Client Identifier and, if applicable, a 469 Client Secret, along with all registered metadata (Section 2) about 470 this client, including any fields provisioned by the Authorization 471 Server itself. The Authorization Server MAY reject or replace any of 472 the client's requested field values and substitute them with suitable 473 values. If this happens, the Authorization Server MUST include these 474 fields in the response to the client. 476 The response also contains a Registration Access Token that is to be 477 used by the client to perform subsequent operations at this endpoint, 478 such as "client_update" and "rotate_secret". 480 All of the response items are returned as a JSON document with the 481 following fields as top-level members of the root JSON object. 483 client_id 484 REQUIRED. The unique Client identifier, MUST NOT be currently 485 valid for any other registered Client. 487 client_secret 488 OPTIONAL. The Client secret. This MUST be unique for each 489 "client_id". This value is used by confidential clients to 490 authenticate to the Token Endpoint as described in OAuth 2.0 491 Section 2.3.1. 493 registration_access_token 494 REQUIRED. The Access token to be used by the client to perform 495 "client_update" and "rotate_secret" requests. 497 issued_at 498 OPTIONAL. Specifies the timestamp when the Client Identifier was 499 issued. The timestamp value MUST be a positive integer. The 500 value is expressed in the number of seconds since January 1, 1970 501 00:00:00 GMT. 503 expires_at 504 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 505 measured in UTC that the "client_secret" will expire or "0" if 506 they do not expire. See RFC 3339 [RFC3339] for details regarding 507 date/times in general and UTC in particular. 509 Following is a non-normative example response: 510 HTTP/1.1 200 OK 511 Content-Type: application/json 512 Cache-Control: no-store 514 { 515 "client_id":"s6BhdRkqt3", 516 "client_secret": "cf136dc3c1fc93f31185e5885805d", 517 "scope": "read write dolphin", 518 "grant_type": "authorization_code refresh_token", 519 "token_endpoint_auth_method": "client_secret_basic client_secret_post", 520 "logo_url": "https://client.example.org/logo.png", 521 "jwk_url": "https://client.example.org/my_rsa_public_key.jwk", 522 "registration_access_token": "reg-23410913-abewfq.123483", 523 "expires_at":2893276800 524 } 526 3.3. Client Update Request 528 This operation updates a previously-registered client with new 529 metadata at the Authorization Server. This request MUST be protected 530 by the Registration Authorization Token associated with the Client. 531 This request MAY include any fields described in Client Metadata 532 (Section 2). If included in the request, valid values of Client 533 Metadata fields in this request MUST replace, not augment, the values 534 previously associated with this Client. Empty values in Client 535 Metadata MUST be taken as a request to clear any existing value of 536 that field. Omitted values in the Client Metadata MUST remain 537 unchanged by the Authorization Server. The Authorization Server MAY 538 replace any invalid values with suitable values. 540 operation 541 REQUIRED, MUST have the value "client_update" 542 access_token 543 REQUIRED, unless presented in the Authorization Header as in 544 OAuth2 Bearer [RFC6750]. The Registration Access Token that was 545 issued during the "client_register" step, or previous 546 "client_update" or "rotate_secret" calls. 547 redirect_uris RECOMMENDED 548 client_name RECOMMENDED 549 client_url RECOMMENDED 550 logo_url OPTIONAL 551 contacts OPTIONAL 552 tos_url OPTIONAL 553 token_endpoint_auth_method OPTIONAL 554 policy_url OPTIONAL 555 jwk_url OPTIONAL 556 jwk_encryption_url OPTIONAL 557 x509_url OPTIONAL 558 x509_encryption_url OPTIONAL 559 default_max_age OPTIONAL 560 default_acr OPTIONAL 561 For example, a client could send the following request to the Client 562 Registration Endpoint to update the client registration in the above 563 example: 565 Following is a non-normative example request (with line wraps for 566 display purposes only): 567 POST /register HTTP/1.1 568 Accept: application/x-www-form-urlencoded 569 Host: server.example.com 570 Authorization: Bearer reg-23410913-abewfq.123483 572 operation=client_update 573 &redirect_uri=https://client.example.org/callback 574 %20https://client.example.org/alt 575 &client_name=My%20New%20Example%20 576 &logo_url=https://client.example.org/newlogo.png 578 3.4. Client Update Response 580 Upon successful update, the Client Registration Endpoint returns the 581 Client ID, along with all current registered metadata (Section 2) 582 about this client, including any fields provisioned by the 583 Authorization Server itself. The Authorization Server MAY reject or 584 replace any of the client's requested field values and substitute 585 them suitable values. If this happens, the Authorization Server MUST 586 include these fields in the response to the client. 588 The Authorization Server MUST NOT include the Client Secret or 589 Request Access Token in this response. 591 These fields are returned as top-level members of the root JSON 592 object. 594 client_id 595 REQUIRED. The unique Client identifier, MUST equal the value of 596 the client_id returned in the original client_register request. 598 Following is a non-normative example response: 599 HTTP/1.1 200 OK 600 Content-Type: application/json 601 Cache-Control: no-store 603 { 604 "client_id": "s6BhdRkqt3", 605 "client_name": "My New Example", 606 "redirect_uri": 607 "https://client.example.org/callback https://client.example.org/alt" 608 "scope": "read write dolphin", 609 "grant_type": "authorization_code refresh_token", 610 "token_endpoint_auth_method": "client_secret_basic client_secret_post", 611 "logo_url": "https://client.example.org/newlogo.png", 612 "jwk_url": "https://client.example.org/my_rsa_public_key.jwk", 613 } 615 3.5. Rotate Secret Request 617 This operation allows the client to rotate its current Registration 618 Access Token as well as its Client Secret, if it has one. 620 operation 621 REQUIRED. MUST have the value rotate_secret 623 access_token 624 REQUIRED, unless presented in the Authorization Header as in 625 OAuth2 Bearer [RFC6750]. The Registration Access Token that was 626 issued during the "client_register" step, or previous 627 "client_update" or "rotate_secret" calls. 629 Following is a non-normative example request (with line wraps for 630 display purposes only): 631 POST /register HTTP/1.1 632 Accept: application/x-www-form-urlencoded 633 Host: server.example.com 634 Authorization: Bearer reg-23410913-abewfq.123483 636 operation=rotate_secret 638 3.6. Rotate Secret Response 640 Upon successful rotation of the Registration Access Token, and 641 optionally the Client Secret, the Client Registration Endpoint 642 returns a JSON document with the following fields as top-level 643 members of the root JSON object. This response MUST NOT include any 644 other client metadata. 646 client_id 647 REQUIRED. The unique Client identifier, MUST match the client_id 648 issued in the original client_register request. 650 client_secret 651 REQUIRED if the server initially issued this Client a Client 652 Secret, otherwise the server MUST NOT return a value. The value 653 MUST be unique for each "client_id". 655 registration_access_token 656 REQUIRED The Access token to be used by the client to perform 657 subsequent "client_update" and "rotate_secret" requests. 659 issued_at 660 OPTIONAL. Specifies the timestamp when the identifier was issued. 661 The timestamp value MUST be a positive integer. The value is 662 expressed in the number of seconds since January 1, 1970 00:00:00 663 GMT. 665 expires_at 666 OPTIONAL. The number of seconds from 1970-01-01T0:0:0Z as 667 measured in UTC that the "client_secret" will expire or "0" if 668 they do not expire. See RFC 3339 [RFC3339] for details regarding 669 date/times in general and UTC in particular. 671 Following is a non-normative example response: 672 HTTP/1.1 200 OK 673 Content-Type: application/json 674 Cache-Control: no-store 676 { 677 "client_id":"s6BhdRkqt3", 678 "client_secret": "7fce6c93f31185e5885805d", 679 "registration_access_token": "reg-02348913-oieqer.983421", 680 "expires_at":2893276800 681 } 683 The Authorization Server SHOULD discard and invalidate the Request 684 Access Token and the Client Secret associated with this Client after 685 successful completion of this request. 687 3.7. Client Registration Error Response 689 When an OAuth error condition occurs, the Client Registration 690 Endpoint returns an Error Response as defined in Section 5.2 of the 691 OAuth 2.0 specification. 693 When a registration error condition occurs, the Client Registration 694 Endpoint returns a HTTP 400 status code including a JSON object 695 describing the error in the response body. 697 The JSON object contains two members: 699 error 700 The error code, a single ASCII string. 702 error_description 703 The additional text description of the error for debugging. 705 This specification defines the following error codes: 707 invalid_operation 708 The value of "operation" is invalid or not supported. 710 invalid_redirect_uri 711 The value of one or more "redirect_uris" is invalid. 713 invalid_client_metadata 714 The value of one of the client metadata (Section 2) fields is 715 invalid and the server has rejected this request. Note that an 716 Authorization server MAY choose to substitute a valid value for 717 any requested parameter of a client's metadata. 719 Following is a non-normative example of an error response (with line 720 wraps for display purposes only): 721 HTTP/1.1 400 Bad Request 722 Content-Type: application/json 723 Cache-Control: no-store 725 { 726 "error":"invalid_operation", 727 "error_description":"The value of the operation parameter must 728 be one of client_register, rotate_secret or client_update." 729 } 731 4. IANA Considerations 733 This document makes no requests of IANA. 735 5. Security Considerations 737 [[ Editor's note: Following are some security considerations taken 738 from the UMA and OpenID Connect source drafts. These need to be 739 massaged into a properly generic set of considerations. ]] 740 Since requests to the Client Registration Endpoint result in the 741 transmission of clear-text credentials (in the HTTP request and 742 response), the server MUST require the use of a transport-layer 743 security mechanism when sending requests to the Registration 744 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 745 TLS 1.0 [RFC2246] and MAY support additional transport-layer 746 mechanisms meeting its security requirements. When using TLS, the 747 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 748 [RFC6125]. 750 As this endpoint is an OAuth2 Protected Resource, requests to the 751 Registration Endpoint SHOULD have some rate limiting on failures to 752 prevent the Registration Access Token from being disclosed though 753 repeated access attempts. 755 The authorization server MUST treat all client metadata as self- 756 asserted. A rogue Client might use the name and logo for the 757 legitimate Client, which it is trying to impersonate. An 758 Authorization Server needs to take steps to mitigate this phishing 759 risk, since the logo could confuse users into thinking they're 760 logging in to the legitimate Client. For instance, an Authorization 761 Server could warn if the domain/site of the logo doesn't match the 762 domain/site of redirect URIs. An Authorization Server can also 763 present warning messages to end users about untrusted Clients in all 764 cases, especially if such clients have been dynamically registered 765 and have not been trusted by any users at the Authorization Server 766 before. 768 In a situation where the Authorization Server is supporting open 769 Client registration, it must be extremely careful with any URL 770 provided by the Client that will be displayed to the user (e.g. 771 "logo_url" and "policy_url"). A rogue Client could specify a 772 registration request with a reference to a drive-by download in the 773 "policy_url". The Authorization Server should check to see if the 774 "logo_url" and "policy_url" have the same host as the hosts defined 775 in the array of "redirect_uris". 777 While the Client Secret can expire, the Registration Access Token 778 should not expire while a client is still actively registered. If 779 this token were to expire, a Client could be left in a situation 780 where it has no means of updating itself and must register itself 781 anew. As the Registration Access Tokens are long-term credentials, 782 they MUST be protected by the Client as a secret. [[ Editor's note: 783 with the right error codes returned from client_update, the AS could 784 force the Client to call rotate_secret before going forward, 785 lessening the window for abuse of a leaked registration token. ]] 787 6. Acknowledgments 789 The authors thank the OAuth Working Group, the User-Managed Access 790 Working Group, and the OpenID Connect Working Group participants for 791 their input to this document. In particular, the following 792 individuals have been instrumental in their review and contribution 793 to various versions of this document: Torsten Lodderstedt, Eve Maler, 794 Thomas Hardjono, Christian Scholz, Nat Sakimura, George Fletcher, 795 Amanda Anganes, and Domenico Catalano. 797 7. Document History 799 [[ to be removed by RFC editor before publication as an RFC ]] 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 [JWA] Jones, M., "JSON Web Algorithms", May 2012. 832 [JWE] Jones, M., Rescorla, E., and J. Hildebrand, "JSON Web 833 Encryption (JWE)", May 2012. 835 [JWK] Jones, M., "JSON Web Key (JWK)", May 2012. 837 [JWS] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 838 Signature", May 2012. 840 [JWT] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token", 841 May 2012. 843 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 844 Requirement Levels", BCP 14, RFC 2119, March 1997. 846 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 847 RFC 2246, January 1999. 849 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 850 Leach, P., Luotonen, A., and L. Stewart, "HTTP 851 Authentication: Basic and Digest Access Authentication", 852 RFC 2617, June 1999. 854 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 855 Internet: Timestamps", RFC 3339, July 2002. 857 [RFC4627] Crockford, D., "The application/json Media Type for 858 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 860 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 861 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 863 [RFC5785] Nottingham, M. and E. Hammer-Lahav, "Defining Well-Known 864 Uniform Resource Identifiers (URIs)", RFC 5785, 865 April 2010. 867 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 868 Verification of Domain-Based Application Service Identity 869 within Internet Public Key Infrastructure Using X.509 870 (PKIX) Certificates in the Context of Transport Layer 871 Security (TLS)", RFC 6125, March 2011. 873 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 874 RFC 6749, October 2012. 876 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 877 Framework: Bearer Token Usage", RFC 6750, October 2012. 879 Authors' Addresses 881 Justin Richer (editor) 882 The MITRE Corporation 884 Phone: 885 Fax: 886 Email: jricher@mitre.org 887 URI: 889 John Bradley 890 Ping Identity 892 Email: ve7jtb@ve7jtb.com 894 Michael B. Jones 895 Microsoft 897 Email: mbj@microsoft.com 899 Maciej Machulak 900 Newcastle University 902 Email: m.p.machulak@ncl.ac.uk 903 URI: http://ncl.ac.uk/