idnits 2.17.1 draft-ietf-oauth-dyn-reg-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (May 24, 2013) is 3988 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group J. Richer, Ed. 3 Internet-Draft The MITRE Corporation 4 Intended status: Standards Track J. Bradley 5 Expires: November 25, 2013 Ping Identity 6 M. Jones 7 Microsoft 8 M. Machulak 9 Newcastle University 10 May 24, 2013 12 OAuth 2.0 Dynamic Client Registration Protocol 13 draft-ietf-oauth-dyn-reg-11 15 Abstract 17 This specification defines an endpoint and protocol for dynamic 18 registration of OAuth 2.0 Clients at an Authorization Server and 19 methods for the dynamically registered client to manage its 20 registration. 22 Status of this Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on November 25, 2013. 39 Copyright Notice 41 Copyright (c) 2013 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Notational Conventions . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Registration Tokens and Credentials . . . . . . . . . . . 4 60 1.4. Client Lifecycle . . . . . . . . . . . . . . . . . . . . . 5 61 1.4.1. Open Registration . . . . . . . . . . . . . . . . . . 6 62 1.4.2. Protected Registration . . . . . . . . . . . . . . . . 7 63 1.4.3. Developer Automation . . . . . . . . . . . . . . . . . 8 64 2. Client Metadata . . . . . . . . . . . . . . . . . . . . . . . 10 65 2.1. Relationship Between Grant Types and Response Types . . . 13 66 2.2. Human Readable Client Metadata . . . . . . . . . . . . . . 14 67 3. Client Registration Endpoint . . . . . . . . . . . . . . . . . 15 68 3.1. Client Registration Request . . . . . . . . . . . . . . . 16 69 3.2. Client Registration Response . . . . . . . . . . . . . . . 18 70 4. Client Configuration Endpoint . . . . . . . . . . . . . . . . 18 71 4.1. Forming the Client Configuration Endpoint URL . . . . . . 18 72 4.2. Client Read Request . . . . . . . . . . . . . . . . . . . 19 73 4.3. Client Update Request . . . . . . . . . . . . . . . . . . 19 74 4.4. Client Delete Request . . . . . . . . . . . . . . . . . . 22 75 5. Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 22 76 5.1. Client Information Response . . . . . . . . . . . . . . . 23 77 5.2. Client Registration Error Response . . . . . . . . . . . . 24 78 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 79 6.1. OAuth Token Endpoint Authentication Methods Registry . . . 25 80 6.1.1. Registration Template . . . . . . . . . . . . . . . . 26 81 6.1.2. Initial Registry Contents . . . . . . . . . . . . . . 26 82 7. Security Considerations . . . . . . . . . . . . . . . . . . . 27 83 8. Normative References . . . . . . . . . . . . . . . . . . . . . 28 84 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 29 85 Appendix B. Document History . . . . . . . . . . . . . . . . . . 30 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 88 1. Introduction 90 In some use-case scenarios, it is desirable or necessary to allow 91 OAuth 2.0 clients to obtain authorization from an OAuth 2.0 92 authorization server without requiring the two parties to interact 93 beforehand. Nevertheless, for the authorization server to accurately 94 and securely represent to end-users which client is seeking 95 authorization to access the end-user's resources, a method for 96 automatic and unique registration of clients is needed. The OAuth 97 2.0 authorization framework does not define how the relationship 98 between the Client and the Authorization Server is initialized, or 99 how a given client is assigned a unique Client Identifier. 100 Historically, this has happened out-of-band from the OAuth 2.0 101 protocol. This draft provides a mechanism for a client to register 102 itself with the Authorization Server, which can be used to 103 dynamically provision a Client Identifier, and optionally a Client 104 Secret. 106 As part of the registration process, this specification also defines 107 a mechanism for the client to present the Authorization Server with a 108 set of metadata, such as a display name and icon to be presented to 109 the user during the authorization step. This draft also provides a 110 mechanism for the Client to read and update this information after 111 the initial registration action. 113 1.1. Notational Conventions 115 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 116 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 117 document are to be interpreted as described in [RFC2119]. 119 Unless otherwise noted, all the protocol parameter names and values 120 are case sensitive. 122 1.2. Terminology 124 This specification uses the terms "Access Token", "Refresh Token", 125 "Authorization Code", "Authorization Grant", "Authorization Server", 126 "Authorization Endpoint", "Client", "Client Identifier", "Client 127 Secret", "Protected Resource", "Resource Owner", "Resource Server", 128 and "Token Endpoint" defined by OAuth 2.0 [RFC6749]. 130 This specification defines the following additional terms: 132 Client Registration Endpoint OAuth 2.0 Endpoint through which a 133 Client can be registered at an Authorization Server. The means by 134 which the URL for this endpoint are obtained are out of scope for 135 this specification. 137 Client Configuration Endpoint OAuth 2.0 Endpoint through which 138 registration information for a registered Client can be managed. 139 This URL for this endpoint is returned by the Authorization Server 140 in the Client Information Response. 142 Registration Access Token OAuth 2.0 Bearer Token issued by the 143 Authorization Server through the Client Registration Endpoint that 144 is used to authenticate the caller when accessing the Client's 145 registration information at the Client Configuration Endpoint. 146 This Access Token is associated with a particular registered 147 Client. 149 Initial Access Token An OAuth 2.0 Access Token optionally issued by 150 an Authorization Server granting access to its Client Registration 151 Endpoint. 153 1.3. Registration Tokens and Credentials 155 Throughout the course of the Dynamic Registration protocol, there are 156 three different classes of credentials in play, each with different 157 properties and targets. 159 o The Initial Access Token is optionally used by the Client or 160 Developer at the Registration Endpoint. This is an OAuth 2.0 161 Bearer Token that is used to authorize the initial Client 162 Registration Request. The content, structure, generation, and 163 validation of this token are out of scope for this specification. 164 The Authorization Server can use this token to verify that the 165 presenter is allowed to dynamically register new clients. The 166 Authorization Server can also use this token to tie multiple 167 instances of registered clients (each with their own distinct 168 Client Identifier) back to the party to whom the Initial Access 169 Token was issued, usually an application developer. This token 170 may be shared between multiple instances of a Client to allow them 171 to each register separately. This token should be used only at 172 the Client Registration Endpoint. 174 o The Registration Access Token is used by the Client or Developer 175 at the Client Configuration Endpoint and represents the holder's 176 authorization to manage the registration of a Client. This is an 177 OAuth 2.0 Bearer Token that is issued from the Client Registration 178 Endpoint in response to a Client Registration Request and is 179 returned in a Client Information Response. The Registration 180 Access Token is uniquely bound to the Client Identifier and is 181 required to be presented with all calls to the Client 182 Configuration Endpoint. The Registration Access Token should be 183 protected and should not be shared between instances of a client 184 (otherwise, one instance could change or delete registration 185 values for all instances of the client). The Registration Access 186 Token can be rotated through the use of the client read and update 187 methods on the Client Configuration Endpoint. The Registration 188 Access Token should be used only at the Client Configuration 189 Endpoint. 191 o The Client Credentials (such as "client_secret") are optional 192 depending on the type of Client and are used to retrieve OAuth 193 tokens. Client Credentials are usually bound to particular 194 instances of a Client and should not be shared between instances. 195 Since not all types of Clients have Client Credentials, they 196 cannot be used to manage client registrations. The Client 197 Credentials can be rotated through the use of the client read and 198 update methods on the Client Configuration Endpoint. The Client 199 Credentials should not be used for authentication at the Client 200 Registration Endpoint or at the Client Configuration endpoint. 202 1.4. Client Lifecycle 204 In the OAuth 2.0 specification [RFC6749], a Client is identified by 205 its own unique Client Identifier ("client_id") at each Authorization 206 Server that it associates with. Dynamic Registration as defined in 207 this document is one way for a Client to get a Client Identifier and 208 associate a set of metadata with that identifier. Lack of such a 209 Client Identifier is the expected trigger for a client registration 210 operation. 212 In many cases, this Client Identifier is a unique, pairwise 213 association between a particular running instance of a piece of 214 Client software and a particular running instance of an Authorization 215 Server software. In particular: 217 o A single instance of Client software (such as a Web server) 218 talking to multiple Authorization Servers will need to register 219 with each Authorization Server separately, creating a distinct 220 Client Identifier with each Authorization Server. The Client can 221 not make any assumption of correlation on the part of the 222 Authorization Server without further specifications, profiles, and 223 extensions to this specification document. 225 o Multiple instances of Client software (such as a native 226 application installed on multiple devices simultaneously) talking 227 to the same Authorization Server will need to each register with 228 that Authorization Server separately, creating a distinct Client 229 Identifier for each copy of the application. The Authorization 230 Server cannot make any assumption of correlation between these 231 clients without further specifications, profiles, and extensions 232 to this specification document. 234 A Client Identifier (and its associated credentials) could also be 235 shared between multiple instances of a Client. Mechanisms for 236 sharing Client Identifiers between multiple instances of a piece of 237 software (either Client or Authorization Server) are outside the 238 scope of this specification, as it is expected that every successful 239 registration request (Section 3.1) results in the issuance of a new 240 Client Identifier. 242 There are several patterns of OAuth Client registration that this 243 protocol can enable. The following non-normative example lifecycle 244 descriptions are not intended to be an exhaustive list. It is 245 assumed that the Authorization Server supports the Dynamic 246 Registration protocol and that all necessary discovery steps (which 247 are out of scope for this specification) have already been performed. 249 1.4.1. Open Registration 251 Open Registration, with no authentication on the Registration 252 Endpoint, works as follows: 254 a. A Client needs to get OAuth 2.0 tokens from an Authorization 255 Server, but the Client does not have a Client Identifier for that 256 Authorization Server. 258 b. The Client sends an HTTP POST request to the Client Registration 259 Endpoint at the Authorization Server and includes its metadata. 261 c. The Authorization Server issues a Client Identifier and returns 262 it to the Client along with a Registration Access Token and a 263 reference to the Client's Client Configuration Endpoint. 265 d. The Client stores the returned response from the Authorization 266 Server. At a minimum, it should know the values of "client_id", 267 "client_secret" (if present), "registration_access_token", and 268 "registration_client_uri". 270 e. The Client uses the its "client_id" and "client_secret" (if 271 provided) to request OAuth 2.0 tokens using any valid OAuth 2.0 272 flow. 274 f. If the Client's "client_secret" expires or otherwise stops 275 working, the Client sends an HTTP GET request to the 276 "registration_client_uri" with the "registration_access_token" as 277 its authorization. This response will contain the Client's 278 refreshed "client_secret" along with any changed metadata values. 279 Its "client_id" will remain the same. 281 g. If the Client needs to update its configuration on the 282 Authorization Server, it sends an HTTP PUT request to the 283 "registration_client_uri" with the "registration_access_token" as 284 its authorization. This response will contain the Client's 285 changed metadata values. Its "client_id" will remain the same. 287 h. If the Client is uninstalled or otherwise deprovisioned, it can 288 send an HTTP DELETE request to the "registration_client_uri" with 289 the "registration_access_token" as its authorization. This will 290 effectively deprovision the client from the Authorization Server. 292 1.4.2. Protected Registration 294 An Authorization Server may require an Initial Access Token for 295 requests to its Registration Endpoint. While the method by which a 296 Client receives this Initial Access Token and the method by which the 297 Authorization Server validates this Initial Access Token are out of 298 scope for this specification, a common approach is for the Developer 299 to use a manual pre-registration portal at the Authorization Server 300 that issues an Initial Access Token to the Developer. This allows 301 the Developer to package the Initial Access Token with different 302 instances of the application. While each copy of the application 303 would get its own Client Identifier (and Registration Access Token), 304 all instances of the application would be tied back to the Developer 305 by their use of this initial registration token. 307 a. A Developer is creating a Client to use an Authorization Server 308 and knows that instances of the Client will dynamically register 309 at runtime, but that the Authorization Server requires 310 authorization the registration endpoint. 312 b. The Developer visits a manual pre-registration page at the 313 Authorization Server and is issued an Initial Access Token in the 314 form of an OAuth 2.0 Bearer Token [RFC6750]. 316 c. The Developer packages that token with all instances of the 317 Client application. 319 d. The Client needs to get OAuth 2.0 tokens from an Authorization 320 Server, but the Client does not have a Client Identifier for that 321 Authorization Server. 323 e. The Client sends an HTTP POST request to the Client Registration 324 Endpoint at the Authorization Server with its metadata, and the 325 Initial Access Token as its authorization. 327 f. The Authorization Server issues a Client Identifier and returns 328 it to the Client along with a Registration Access Token and a 329 reference to the Client's Client Configuration Endpoint. 331 g. The Client stores the returned response from the Authorization 332 Server. At a minimum, it should know the values of "client_id", 333 "client_secret" (if present), "registration_access_token", and 334 "registration_client_uri". 336 h. The Client uses the its "client_id" and "client_secret" (if 337 provided) to request OAuth 2.0 tokens using any supported OAuth 338 2.0 flow. 340 i. If the Client's "client_secret" expires or otherwise stops 341 working, the Client sends an HTTP GET request to the 342 "registration_client_uri" with the "registration_access_token" as 343 its authorization. This response will contain the Client's 344 refreshed "client_secret" along with any metadata values 345 registered to that client, some of which may have changed. Its 346 "client_id" will remain the same. 348 j. If the Client needs to update its configuration on the 349 Authorization Server, it sends an HTTP PUT request to the 350 "registration_client_uri" with the "registration_access_token" as 351 its authorization. The response will contain the Client's 352 changed metadata values. Its "client_id" will remain the same. 354 k. If the Client is uninstalled or otherwise deprovisioned, it can 355 send an HTTP DELETE request to the "registration_client_uri" with 356 the "registration_access_token" as its authorization. This will 357 effectively deprovision the client from the Authorization Server. 359 1.4.3. Developer Automation 361 The Dynamic Registration protocol can also be used in place of a 362 manual registration portal, for instance as part of an automated 363 build and deployment process. An Authorization Server may require an 364 Initial Access Token for requests to its Registration Endpoint, as 365 described in Protected Registration (Section 1.4.2). However, in 366 this scenario, the Developer manages the Client's registration 367 instead of the Client itself. Therefore, the initial registration 368 token and Registration Access Token all remain with the Developer. 369 The Developer packages the Client Identifier with the Client as part 370 of its build process. 372 a. A Developer is creating a Client to use an Authorization Server 373 and knows that instances of the Client will not dynamically 374 register at runtime. 376 b. If required for registrations at the Authorization Server, the 377 Developer visits a manual pre-registration page at the 378 Authorization Server and is issued an Initial Access Token in the 379 form of an OAuth 2.0 Bearer Token [RFC6750]. 381 c. The Developer configures his build environment to send an HTTP 382 POST request to the Client Registration Endpoint at the 383 Authorization Server with the Client's metadata, using the 384 Initial Access Token obtained the previous step as an OAuth 2.0 385 Bearer Token [RFC6750], if needed. 387 d. The Authorization Server issues a Client Identifier and returns 388 it to the Developer along with a Registration Access Token and a 389 reference to the Client's Client Configuration Endpoint. 391 e. The Developer packages the Client Identifier with the Client and 392 stores the "registration_access_token", and 393 "registration_client_uri" in the deployment system. 395 f. The Client uses the its "client_id" and "client_secret" (if 396 provided) to request OAuth 2.0 tokens using any supported OAuth 397 2.0 flow. 399 g. If the Client's "client_secret" expires or otherwise stops 400 working, the Developer's deployment system sends an HTTP GET 401 request to the "registration_client_uri" with the 402 "registration_access_token" as its authorization. This response 403 will contain the Client's refreshed "client_secret" along with 404 any changed metadata values. Its "client_id" will remain the 405 same. These new values will then be packaged and shipped to or 406 retrieved by instances of the Client, if necessary. 408 h. If the Developer needs to update its configuration on the 409 Authorization Server, the deployment system sends an HTTP PUT 410 request to the "registration_client_uri" with the 411 "registration_access_token" as its authorization. This response 412 will contain the Client's changed metadata values. Its 413 "client_id" will remain the same. These new values will then be 414 packaged and shipped to or retrieved by instances of the Client, 415 if necessary. 417 i. If the Client is deprovisioned, the Developer's deployment system 418 can send an HTTP DELETE request to the "registration_client_uri" 419 with the "registration_access_token" as its authorization. This 420 will effectively deprovision the client from the Authorization 421 Server and prevent any instances of the client from functioning. 423 2. Client Metadata 425 Clients generally have an array of metadata associated with their 426 unique Client Identifier at the Authorization Server. These can 427 range from human-facing display strings, such as a client name, to 428 items that impact the security of the protocol, such as the list of 429 valid redirect URIs. 431 The client metadata values serve two parallel purposes in the overall 432 OAuth 2.0 Dynamic Client Registration protocol: 434 o the Client requesting its desired values for each parameter to the 435 Authorization Server in a register (Section 3.1) or update 436 (Section 4.3) request, and 438 o the Authorization Server informing the Client of the current 439 values of each parameter that the Client has been registered to 440 use through a client information response (Section 5.1). 442 An Authorization Server MAY override any value that a Client requests 443 during the registration process (including any omitted values) and 444 replace the requested value with a default at the server's 445 discretion. The Authorization Server SHOULD provide documentation 446 for any fields that it requires to be filled in by the client or to 447 have particular values or formats. 449 Extensions and profiles of this specification MAY expand this list, 450 but Authorization Servers MUST accept or ignore all parameters on 451 this list. The Authorization Server MUST ignore any additional 452 parameters sent by the Client that it does not understand. 454 redirect_uris 455 Array of redirect URIs for use in redirect-based flows such as the 456 Authorization Code and Implicit grant types. It is RECOMMENDED 457 that clients using these flows register this parameter, and an 458 Authorization Server SHOULD require registration of valid redirect 459 URIs for all clients that use these grant types to protect against 460 token and credential theft attacks. 462 client_name 463 Human-readable name of the Client to be presented to the user. If 464 omitted, the Authorization Server MAY display the raw "client_id" 465 value to the user instead. It is RECOMMENDED that clients always 466 send this field. The value of this field MAY be internationalized 467 as described in Human Readable Client Metadata (Section 2.2). 469 client_uri 470 URL of the homepage of the Client. If present, the server SHOULD 471 display this URL to the end user in a clickable fashion. It is 472 RECOMMENDED that clients always send this field. The value of 473 this field MUST point to a valid Web page. The value of this 474 field MAY be internationalized as described in Human Readable 475 Client Metadata (Section 2.2). 477 logo_uri 478 URL that references a logo for the Client. If present, the server 479 SHOULD display this image to the end user during approval. The 480 value of this field MUST point to a valid image file. The value 481 of this field MAY be internationalized as described in Human 482 Readable Client Metadata (Section 2.2). 484 contacts 485 Array of email addresses for people responsible for this Client. 486 The Authorization Server MAY make these addresses available to end 487 users for support requests for the Client. An Authorization 488 Server MAY use these email addresses as identifiers for an 489 administrative page for this client. 491 tos_uri 492 URL that points to a human-readable Terms of Service document for 493 the Client. The Authorization Server SHOULD display this URL to 494 the End-User if it is given. The Terms of Service usually 495 describe a contractual relationship between the End-User and the 496 Client that the End-User accepts when authorizing the Client. The 497 value of this field MUST point to a valid Web page. The value of 498 this field MAY be internationalized as described in Human Readable 499 Client Metadata (Section 2.2). 501 policy_uri 502 URL that points to a human-readable Policy document for the 503 Client. The Authorization Server SHOULD display this URL to the 504 End-User if it is given. The Policy usually describes how an End- 505 User's data will be used by the Client. The value of this field 506 MUST point to a valid Web page. The value of this field MAY be 507 internationalized as described in Human Readable Client Metadata 508 (Section 2.2). 510 token_endpoint_auth_method 511 The requested authentication method for the Token Endpoint. 512 Values defined by this specification are: 514 * "none": The client is a public client as defined in OAuth 2.0 515 and does not have a client secret. 517 * "client_secret_post": The client uses the HTTP POST parameters 518 defined in OAuth 2.0 section 2.3.1. 520 * "client_secret_basic": the client uses HTTP Basic defined in 521 OAuth 2.0 section 2.3.1 523 Additional values can be defined via the IANA OAuth Token Endpoint 524 Authentication Methods registry Section 6.1. Absolute URIs can 525 also be used as values for this parameter. If unspecified or 526 omitted, the default is "client_secret_basic", denoting HTTP Basic 527 Authentication Scheme as specified in Section 2.3.1 of OAuth 2.0. 529 scope 530 Space separated list of scope values (as described in OAuth 2.0 531 Section 3.3 [RFC6749]) that the client can use when requesting 532 access tokens. The semantics of values in this list is service 533 specific. If omitted, an Authorization Server MAY register a 534 Client with a default set of scopes. 536 grant_types 537 Array of OAuth 2.0 grant types that the Client may use. These 538 grant types are defined as follows: 540 * "authorization_code": The Authorization Code Grant described in 541 OAuth 2.0 Section 4.1 543 * "implicit": The Implicit Grant described in OAuth 2.0 Section 544 4.2 546 * "password": The Resource Owner Password Credentials Grant 547 described in OAuth 2.0 Section 4.3 549 * "client_credentials": The Client Credentials Grant described in 550 OAuth 2.0 Section 4.4 552 * "refresh_token": The Refresh Token Grant described in OAuth 2.0 553 Section 6. 555 * "urn:ietf:params:oauth:grant-type:jwt-bearer": The JWT Bearer 556 grant type defined in OAuth JWT Bearer Token Profiles 557 [OAuth.JWT]. 559 * "urn:ietf:params:oauth:grant-type:saml2-bearer": The SAML 2 560 Bearer grant type defined in OAuth SAML 2 Bearer Token Profiles 561 [OAuth.SAML2]. 563 Authorization Servers MAY allow for other values as defined in 564 grant type extensions to OAuth 2.0. The extension process is 565 described in OAuth 2.0 Section 2.5, and the value of this 566 parameter MUST be the same as the value of the "grant_type" 567 parameter passed to the Token Endpoint defined in the extension. 569 response_types 570 Array of the OAuth 2.0 response types that the Client may use. 571 These response types are defined as follows: 573 * "code": The Authorization Code response described in OAuth 2.0 574 Section 4.1. 576 * "token": The Implicit response described in OAuth 2.0 Section 577 4.2. 579 Authorization Servers MAY allow for other values as defined in 580 response type extensions to OAuth 2.0. The extension process is 581 described in OAuth 2.0 Section 2.5, and the value of this 582 parameter MUST be the same as the value of the "response_type" 583 parameter passed to the Authorization Endpoint defined in the 584 extension. 586 jwks_uri 587 URL for the Client's JSON Web Key Set [JWK] document representing 588 the client's public keys. The value of this field MUST point to a 589 valid JWK Set. These keys MAY also be used for higher level 590 protocols that require signing or encryption. 592 2.1. Relationship Between Grant Types and Response Types 594 The "grant_types" and "response_types" values described above are 595 partially orthogonal, as they refer to arguments passed to different 596 endpoints in the OAuth protocol. However, they are related in that 597 the "grant_types" available to a client influence the 598 "response_types" that the client is allowed to use, and vice versa. 599 For instance, a "grant_types" value that includes 600 "authorization_code" implies a "response_types" value that includes 601 code, as both values are defined as part of the OAuth 2.0 602 Authorization Code Grant. As such, a server supporting these fields 603 SHOULD take steps to ensure that a client cannot register itself into 604 an inconsistent state. 606 The correlation between the two fields is listed in the table below. 608 +-----------------------------------------------+-------------------+ 609 | grant_types value includes: | response_types | 610 | | value includes: | 611 +-----------------------------------------------+-------------------+ 612 | authorization_code | code | 613 | implicit | token | 614 | password | (none) | 615 | client_credentials | (none) | 616 | refresh_token | (none) | 617 | urn:ietf:params:oauth:grant-type:jwt-bearer | (none) | 618 | urn:ietf:params:oauth:grant-type:saml2-bearer | (none) | 619 +-----------------------------------------------+-------------------+ 621 Extensions and profiles of this document that introduce new values to 622 either the "grant_types" or "response_types" parameter MUST document 623 all correspondences between these two parameter types. 625 2.2. Human Readable Client Metadata 627 Human-readable Client Metadata values and Client Metadata values that 628 reference human-readable values MAY be represented in multiple 629 languages and scripts. For example, the values of fields such as 630 "client_name", "tos_uri", "policy_uri", "logo_uri", and "client_uri" 631 might have multiple locale-specific values in some Client 632 registrations. 634 To specify the languages and scripts, BCP47 [RFC5646] language tags 635 are added to Client Metadata member names, delimited by a # 636 character. Since JSON member names are case sensitive, it is 637 RECOMMENDED that language tag values used in Claim Names be spelled 638 using the character case with which they are registered in the IANA 639 Language Subtag Registry [IANA.Language]. In particular, normally 640 language names are spelled with lowercase characters, region names 641 are spelled with uppercase characters, and languages are spelled with 642 mixed case characters. However, since BCP47 language tag values are 643 case insensitive, implementations SHOULD interpret the language tag 644 values supplied in a case insensitive manner. Per the 645 recommendations in BCP47, language tag values used in Metadata member 646 names should only be as specific as necessary. For instance, using 647 "fr" might be sufficient in many contexts, rather than "fr-CA" or 648 "fr-FR". 650 For example, a Client could represent its name in English as 651 ""client_name#en": "My Client"" and its name in Japanese as 652 ""client_name#ja-Jpan-JP": 653 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same 654 registration request. The Authorization Server MAY display any or 655 all of these names to the Resource Owner during the authorization 656 step, choosing which name to display based on system configuration, 657 user preferences or other factors. 659 If any human-readable field is sent without a language tag, parties 660 using it MUST NOT make any assumptions about the language, character 661 set, or script of the string value, and the string value MUST be used 662 as-is wherever it is presented in a user interface. To facilitate 663 interoperability, it is RECOMMENDED that clients and servers use a 664 human-readable field without any language tags in addition to any 665 language-specific fields, and it is RECOMMENDED that any human- 666 readable fields sent without language tags contain values suitable 667 for display on a wide variety of systems. 669 Implementer's Note: Many JSON libraries make it possible to reference 670 members of a JSON object as members of an Object construct in the 671 native programming environment of the library. However, while the 672 "#" character is a valid character inside of a JSON object's member 673 names, it is not a valid character for use in an object member name 674 in many programming environments. Therefore, implementations will 675 need to use alternative access forms for these claims. For instance, 676 in JavaScript, if one parses the JSON as follows, "var j = 677 JSON.parse(json);", then the member "client_name#en-us" can be 678 accessed using the JavaScript syntax "j["client_name#en-us"]". 680 3. Client Registration Endpoint 682 The Client Registration Endpoint is an OAuth 2.0 Endpoint defined in 683 this document that is designed to allow a Client to register itself 684 with the Authorization Server. The Client Registration Endpoint MUST 685 accept HTTP POST messages with request parameters encoded in the 686 entity body using the "application/json" format. The Client 687 Registration Endpoint MUST be protected by a transport-layer security 688 mechanism, and the server MUST support TLS 1.2 RFC 5246 [RFC5246] 689 and/or TLS 1.0 [RFC2246] and MAY support additional transport-layer 690 mechanisms meeting its security requirements. When using TLS, the 691 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 692 [RFC6125]. 694 The Client Registration Endpoint MAY accept an Initial Access Token 695 in the form of an OAuth 2.0 [RFC6749] access token to limit 696 registration to only previously authorized parties. The method by 697 which the Initial Access Token is obtained by the registrant is 698 generally out-of-band and is out of scope of this specification. 700 To support open registration and facilitate wider interoperability, 701 the Client Registration Endpoint SHOULD allow initial registration 702 requests with no authentication. These requests MAY be rate-limited 703 or otherwise limited to prevent a denial-of-service attack on the 704 Client Registration Endpoint. 706 To facilitate registered clients updating their information, the 707 Client Registration Endpoint issues a Request Access Token for 708 clients to securely identify themselves in future connections to the 709 Client Configuration Endpoint (Section 4). As such, the Client 710 Configuration Endpoint MUST accept requests with OAuth 2.0 Bearer 711 Tokens [RFC6750] for these operations, whether or not the initial 712 registration call requires authentication of some form. 714 The Client Registration Endpoint MUST ignore all parameters it does 715 not understand. 717 3.1. Client Registration Request 719 This operation registers a new Client to the Authorization Server. 720 The Authorization Server assigns this client a unique Client 721 Identifier, optionally assigns a Client Secret, and associates the 722 metadata given in the request with the issued Client Identifier. The 723 request includes any parameters described in Client Metadata 724 (Section 2) that the client wishes to specify for itself during the 725 registration. The Authorization Server MAY provision default values 726 for any items omitted in the Client Metadata. 728 The Client sends an HTTP POST to the Client Registration Endpoint 729 with a content type of "application/json". The HTTP Entity Payload 730 is a JSON [RFC4627] document consisting of a JSON object and all 731 parameters as top-level members of that JSON object. 733 For example, a client could send the following open registration 734 request to the Client Registration Endpoint: 736 Following is a non-normative example request (with line wraps for 737 display purposes only): 739 POST /register HTTP/1.1 740 Content-Type: application/json 741 Accept: application/json 742 Host: server.example.com 744 { 745 "redirect_uris":["https://client.example.org/callback", 746 "https://client.example.org/callback2"] 747 "client_name":"My Example Client", 748 "client_name#ja-Jpan-JP": 749 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 750 "token_endpoint_auth_method":"client_secret_basic", 751 "scope":"read write dolphin", 752 "logo_uri":"https://client.example.org/logo.png", 753 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 754 } 756 Alternatively, if the developer or the client has been provisioned 757 with an Initial Access Token, he or it sends the following 758 registration request to the Client Registration Endpoint. The method 759 by which the Initial Access Token is obtained is out of scope for 760 this specification. 762 Following is a non-normative example request (with line wraps for 763 display purposes only): 765 POST /register HTTP/1.1 766 Content-Type: application/json 767 Accept: application/json 768 Authorization: Bearer ey23f2.adfj230.af32-developer321 769 Host: server.example.com 771 { 772 "redirect_uris":["https://client.example.org/callback", 773 "https://client.example.org/callback2"] 774 "client_name":"My Example Client", 775 "client_name#ja-Jpan-JP": 776 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 777 "token_endpoint_auth_method":"client_secret_basic", 778 "scope":"read write dolphin", 779 "logo_uri":"https://client.example.org/logo.png", 780 "jwks_uri":"https://client.example.org/my_public_keys.jwks" 781 } 783 3.2. Client Registration Response 785 Upon successful registration, the Authorization Server generates a 786 new Client Identifier for the client. This Client Identifier MUST be 787 unique at the server and MUST NOT be in use by any other client. The 788 server responds with an HTTP 201 Created code and a body of type 789 "application/json" with content described in Client Information 790 Response (Section 5.1). 792 Upon an unsuccessful registration, the Authorization Server responds 793 with an error as described in Client Registration Error 794 (Section 5.2). 796 4. Client Configuration Endpoint 798 The Client Configuration Endpoint is an OAuth 2.0 protected resource 799 that is provisioned by the server for a specific client to be able to 800 view and update its registered information. The location of this 801 endpoint is communicated to the Client through the 802 "registration_client_uri" member of the Client Information Response 803 (Section 5.1). The Client MUST use its Registration Access Token in 804 all calls to this endpoint as an OAuth 2.0 Bearer Token [RFC6750]. 806 Operations on this endpoint are switched through the use of different 807 HTTP methods [RFC2616]. 809 4.1. Forming the Client Configuration Endpoint URL 811 The Authorization Server MUST provide the client with the fully 812 qualified URL in the "registration_client_uri" element of the Client 813 Information Response (Section 5.1). The Authorization Server MUST 814 NOT expect the client to construct or discover this URL on its own. 815 The Client MUST use the URL as given by the server and MUST NOT 816 construct this URL from component pieces. 818 Depending on deployment characteristics, the Client Configuration 819 Endpoint URL may take any number of forms. It is RECOMMENDED that 820 this endpoint URL be formed through the use of a server-constructed 821 URL string which combines the Client Registration Endpoint's URL and 822 the issued "client_id" for this Client, with the latter as either a 823 path parameter or a query parameter. For example, a Client with the 824 Client ID "s6BhdRkqt3" could be given a Client Configuration Endpoint 825 URL of "https://server.example.com/register/s6BhdRkqt3" (path 826 parameter) or of 827 "https://server.example.com/register?client_id=s6BhdRkqt3" (query 828 parameter). In both of these cases, the client simply uses the URL 829 as given. 831 These common patterns can help the Server to more easily determine 832 the client to which the request pertains, which MUST be matched 833 against the client to which the Registration Access Token was issued. 834 If desired, the server MAY simply return the Client Registration 835 Endpoint URL as the Client Configuration Endpoint URL and change 836 behavior based on the authentication context provided by the 837 Registration Access Token. 839 4.2. Client Read Request 841 To read the current configuration of the Client on the Authorization 842 Server, the Client makes an HTTP GET request to the Client 843 Configuration Endpoint, authenticating with its Registration Access 844 Token. 846 Following is a non-normative example request (with line wraps for 847 display purposes only): 848 GET /register/s6BhdRkqt3 HTTP/1.1 849 Accept: application/json 850 Host: server.example.com 851 Authorization: Bearer reg-23410913-abewfq.123483 853 Upon successful read of the information for a currently active 854 Client, the Authorization Server responds with an HTTP 200 OK with 855 content type of "application/json" and a payload as described in 856 Client Information Response (Section 5.1). Some values in the 857 response, including the "client_secret" and 858 "registration_access_token", MAY be different from those in the 859 initial registration response. If the Authorization Server includes 860 a new Client Secret and/or Registration Access Token in its response, 861 the Client MUST immediately discard its previous Client Secret and/or 862 Registration Access Token. The value of the "client_id" MUST NOT 863 change from the initial registration response. 865 If the client does not exist on this server, the server MUST respond 866 with HTTP 401 Unauthorized and the Registration Access Token used to 867 make this request SHOULD be immediately revoked. 869 If the Client does not have permission to read its record, the server 870 MUST return an HTTP 403 Forbidden. 872 4.3. Client Update Request 874 This operation updates a previously-registered client with new 875 metadata at the Authorization Server. This request is authenticated 876 by the Registration Access Token issued to the client. 878 The Client sends an HTTP PUT to the Client Configuration Endpoint 879 with a content type of "application/json". The HTTP Entity Payload 880 is a JSON [RFC4627] document consisting of a JSON object and all 881 parameters as top- level members of that JSON object. 883 This request MUST include all fields described in Client Metadata 884 (Section 2) as returned to the Client from a previous register, read, 885 or update operation. The Client MUST NOT include the 886 "registration_access_token", "registration_client_uri", 887 "client_secret_expires_at", or "client_id_issued_at" fields described 888 in Client Information Response (Section 5.1). 890 Valid values of Client Metadata fields in this request MUST replace, 891 not augment, the values previously associated with this Client. 892 Omitted fields MUST be treated as null or empty values by the server. 894 The Client MUST include its "client_id" field in the request, and it 895 MUST be the same as its currently-issued Client Identifier. If the 896 client includes the "client_secret" field in the request, the value 897 of this field MUST match the currently-issued Client Secret for that 898 Client. The Client MUST NOT be allowed to overwrite its existing 899 Client Secret with its own chosen value. 901 For all metadata fields, the Authorization Server MAY replace any 902 invalid values with suitable default values, and it MUST return any 903 such fields to the Client in the response. 905 For example, a client could send the following request to the Client 906 Registration Endpoint to update the client registration in the above 907 example with new information: 909 Following is a non-normative example request (with line wraps for 910 display purposes only): 911 PUT /register/s6BhdRkqt3 HTTP/1.1 912 Accept: application/json 913 Host: server.example.com 914 Authorization: Bearer reg-23410913-abewfq.123483 916 { 917 "client_id":"s6BhdRkqt3", 918 "client_secret": "cf136dc3c1fc93f31185e5885805d", 919 "redirect_uris":["https://client.example.org/callback", 920 "https://client.example.org/alt"], 921 "scope": "read write dolphin", 922 "grant_types": ["authorization_code", "refresh_token"] 923 "token_endpoint_auth_method": "client_secret_basic", 924 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 925 "client_name":"My New Example", 926 "client_name#fr":"Mon Nouvel Exemple", 927 "logo_uri":"https://client.example.org/newlogo.png" 928 "logo_uri#fr":"https://client.example.org/fr/newlogo.png" 929 } 931 Upon successful update, the Authorization Server responds with an 932 HTTP 200 OK Message with content type "application/json" and a 933 payload as described in Client Information Response (Section 5.1). 934 Some values in the response, including the "client_secret" and 935 r"egistration_access_token", MAY be different from those in the 936 initial registration response. If the Authorization Server includes 937 a new Client Secret and/or Registration Access Token in its response, 938 the Client MUST immediately discard its previous Client Secret and/or 939 Registration Access Token. The value of the "client_id" MUST NOT 940 change from the initial registration response. 942 If the client does not exist on this server, the server MUST respond 943 with HTTP 401 Unauthorized, and the Registration Access Token used to 944 make this request SHOULD be immediately revoked. 946 If the Client is not allowed to update its records, the server MUST 947 respond with HTTP 403 Forbidden. 949 If the Client attempts to set an invalid metadata field and the 950 Authorization Server does not set a default value, the Authorization 951 Server responds with an error as described in Client Registration 952 Error Response (Section 5.2). 954 4.4. Client Delete Request 956 To deprovision itself on the Authorization Server, the Client makes 957 an HTTP DELETE request to the Client Configuration Endpoint. This 958 request is authenticated by the Registration Access Token issued to 959 the client. 961 Following is a non-normative example request (with line wraps for 962 display purposes only): 963 DELETE /register/s6BhdRkqt3 HTTP/1.1 964 Accept: application/json 965 Host: server.example.com 966 Authorization: Bearer reg-23410913-abewfq.123483 968 A successful delete action will invalidate the "client_id", 969 "client_secret", and "registration_access_token" for this client, 970 thereby preventing the "client_id" from being used at either the 971 Authorization Endpoint or Token Endpoint of the Authorization Server. 972 The Authorization Server SHOULD immediately invalidate all existing 973 authorization grants and currently-active tokens associated with this 974 Client. 976 If a Client has been successfully deprovisioned, the Authorization 977 Server responds with an HTTP 204 No Content message. 979 If the server does not support the delete method, the server MUST 980 respond with an HTTP 405 Not Supported. 982 If the client does not exist on this server, the server MUST respond 983 with HTTP 401 Unauthorized and the Registration Access Token used to 984 make this request SHOULD be immediately revoked. 986 If the client is not allowed to delete itself, the server MUST 987 respond with HTTP 403 Forbidden. 989 Following is a non-normative example response: 990 HTTP/1.1 204 No Content 991 Cache-Control: no-store 992 Pragma: no-cache 994 5. Responses 996 In response to certain requests from the Client to either the Client 997 Registration Endpoint or the Client Configuration Endpoint as 998 described in this specification, the Authorization Server sends the 999 following response bodies. 1001 5.1. Client Information Response 1003 The response contains the Client Identifier as well as the Client 1004 Secret, if the Client is a confidential Client. The response also 1005 contains the fully qualified URL to the Client Configuration Endpoint 1006 for this specific client that the client may use to obtain and update 1007 information about itself. The response also contains a Registration 1008 Access Token that is to be used by the client to perform subsequent 1009 operations at the Client Configuration Endpoint. 1011 client_id 1012 REQUIRED. The unique Client identifier, MUST NOT be currently 1013 valid for any other registered Client. 1015 client_secret 1016 OPTIONAL. The Client secret. If issued, this MUST be unique for 1017 each "client_id". This value is used by confidential clients to 1018 authenticate to the Token Endpoint as described in OAuth 2.0 1019 Section 2.3.1. 1021 client_id_issued_at 1022 OPTIONAL. Time at which the Client Identifier was issued. The 1023 time is represented as the number of seconds from 1970-01- 1024 01T0:0:0Z as measured in UTC until the date/time. 1026 client_secret_expires_at 1027 REQUIRED if "client_secret" is issued. Time at which the 1028 "client_secret" will expire or 0 if it will not expire. The time 1029 is represented as the number of seconds from 1970-01-01T0:0:0Z as 1030 measured in UTC until the date/time. 1032 registration_access_token 1033 REQUIRED. Access Token that is used at the Client Configuration 1034 Endpoint to perform subsequent operations upon the Client 1035 registration. 1037 registration_client_uri 1038 REQUIRED. The fully qualified URL of the Client Configuration 1039 Endpoint for this client. The Client MUST use this URL as given 1040 when communicating with the Client Configuration Endpoint. 1042 Additionally, the Authorization Server MUST return all registered 1043 metadata (Section 2) about this client, including any fields 1044 provisioned by the Authorization Server itself. The Authorization 1045 Server MAY reject or replace any of the client's requested metadata 1046 values submitted during the registration or update requests and 1047 substitute them with suitable values. 1049 The response is an "application/json" document with all parameters as 1050 top-level members of a JSON object [RFC4627]. 1052 Following is a non-normative example response: 1053 HTTP/1.1 200 OK 1054 Content-Type: application/json 1055 Cache-Control: no-store 1056 Pragma: no-cache 1058 { 1059 "registration_access_token": "reg-23410913-abewfq.123483", 1060 "registration_client_uri": 1061 "https://server.example.com/register/s6BhdRkqt3", 1062 "client_id":"s6BhdRkqt3", 1063 "client_secret": "cf136dc3c1fc93f31185e5885805d", 1064 "client_id_issued_at":2893256800 1065 "client_secret_expires_at":2893276800 1066 "client_name":"My Example Client", 1067 "client_name#ja-Jpan-JP": 1068 "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D", 1069 "redirect_uris":["https://client.example.org/callback", 1070 "https://client.example.org/callback2"] 1071 "scope": "read write dolphin", 1072 "grant_types": ["authorization_code", "refresh_token"] 1073 "token_endpoint_auth_method": "client_secret_basic", 1074 "logo_uri": "https://client.example.org/logo.png", 1075 "jwks_uri": "https://client.example.org/my_public_keys.jwks" 1076 } 1078 5.2. Client Registration Error Response 1080 When an OAuth 2.0 error condition occurs, such as the client 1081 presenting an invalid Registration Access Token, the Authorization 1082 Server returns an Error Response as defined in Section 5.2 of the 1083 OAuth 2.0 specification. 1085 When a registration error condition occurs, the Authorization Server 1086 returns an HTTP 400 status code with content type "application/json" 1087 consisting of a JSON object [RFC4627] describing the error in the 1088 response body. 1090 The JSON object contains two members: 1092 error 1093 The error code, a single ASCII string. 1095 error_description 1096 A human-readable text description of the error for debugging. 1098 This specification defines the following error codes: 1100 invalid_redirect_uri 1101 The value of one or more "redirect_uris" is invalid. 1103 invalid_client_metadata 1104 The value of one of the client metadata (Section 2) fields is 1105 invalid and the server has rejected this request. Note that an 1106 Authorization server MAY choose to substitute a valid value for 1107 any requested parameter of a client's metadata. 1109 invalid_client_id 1110 Value of "client_id" is invalid. 1112 Following is a non-normative example of an error response (with line 1113 wraps for display purposes only): 1114 HTTP/1.1 400 Bad Request 1115 Content-Type: application/json 1116 Cache-Control: no-store 1117 Pragma: no-cache 1119 { 1120 "error":"invalid_redirect_uri", 1121 "error_description":"The redirect URI of http://sketchy.example.com 1122 is not allowed for this server." 1123 } 1125 6. IANA Considerations 1127 6.1. OAuth Token Endpoint Authentication Methods Registry 1129 This specification establishes the OAuth Token Endpoint 1130 Authentication Methods registry. 1132 Additional values for use as "token_endpoint_auth_method" metadata 1133 values are registered with a Specification Required ([RFC5226]) after 1134 a two-week review period on the oauth-ext-review@ietf.org mailing 1135 list, on the advice of one or more Designated Experts. However, to 1136 allow for the allocation of values prior to publication, the 1137 Designated Expert(s) may approve registration once they are satisfied 1138 that such a specification will be published. 1140 Registration requests must be sent to the oauth-ext-review@ietf.org 1141 mailing list for review and comment, with an appropriate subject 1142 (e.g., "Request to register token_endpoint_auth_method value: 1143 example"). 1145 Within the review period, the Designated Expert(s) will either 1146 approve or deny the registration request, communicating this decision 1147 to the review list and IANA. Denials should include an explanation 1148 and, if applicable, suggestions as to how to make the request 1149 successful. 1151 IANA must only accept registry updates from the Designated Expert(s) 1152 and should direct all requests for registration to the review mailing 1153 list. 1155 6.1.1. Registration Template 1157 Token Endpoint Authorization Method name: 1158 The name requested (e.g., "example"). This name is case 1159 sensitive. Names that match other registered names in a case 1160 insensitive manner SHOULD NOT be accepted. 1162 Change controller: 1163 For Standards Track RFCs, state "IETF". For others, give the name 1164 of the responsible party. Other details (e.g., postal address, 1165 email address, home page URI) may also be included. 1167 Specification document(s): 1168 Reference to the document(s) that specify the token endpoint 1169 authorization method, preferably including a URI that can be used 1170 to retrieve a copy of the document(s). An indication of the 1171 relevant sections may also be included but is not required. 1173 6.1.2. Initial Registry Contents 1175 The OAuth Token Endpoint Authentication Methods registry's initial 1176 contents are: 1178 o Token Endpoint Authorization Method name: "none" 1179 o Change controller: IETF 1180 o Specification document(s): [[ this document ]] 1182 o Token Endpoint Authorization Method name: "client_secret_post" 1183 o Change controller: IETF 1184 o Specification document(s): [[ this document ]] 1185 o Token Endpoint Authorization Method name: "client_secret_basic" 1186 o Change controller: IETF 1187 o Specification document(s): [[ this document ]] 1189 7. Security Considerations 1191 Since requests to the Client Registration Endpoint result in the 1192 transmission of clear-text credentials (in the HTTP request and 1193 response), the server MUST require the use of a transport-layer 1194 security mechanism when sending requests to the Registration 1195 Endpoint. The server MUST support TLS 1.2 RFC 5246 [RFC5246] and/or 1196 TLS 1.0 [RFC2246] and MAY support additional transport-layer 1197 mechanisms meeting its security requirements. When using TLS, the 1198 Client MUST perform a TLS/SSL server certificate check, per RFC 6125 1199 [RFC6125]. 1201 As this endpoint is an OAuth 2.0 Protected Resource, requests to the 1202 Registration Endpoint SHOULD have some rate limiting on failures to 1203 prevent the Registration Access Token from being disclosed though 1204 repeated access attempts. 1206 For clients that use redirect-based grant types such as Authorization 1207 Code and Implicit, Authorization Servers SHOULD require clients to 1208 register their "redirect_uris". Requiring Clients to do so can help 1209 mitigate attacks where rogue actors inject and impersonate a validly 1210 registered client and intercept its authorization code or tokens 1211 through an invalid redirect URI. 1213 The authorization server MUST treat all client metadata as self- 1214 asserted. A rogue Client might use the name and logo for the 1215 legitimate Client, which it is trying to impersonate. An 1216 Authorization Server needs to take steps to mitigate this phishing 1217 risk, since the logo could confuse users into thinking they're 1218 logging in to the legitimate Client. For instance, an Authorization 1219 Server could warn if the domain/site of the logo doesn't match the 1220 domain/site of redirect URIs. An Authorization Server can also 1221 present warning messages to end users about untrusted Clients in all 1222 cases, especially if such clients have been dynamically registered 1223 and have not been trusted by any users at the Authorization Server 1224 before. 1226 In a situation where the Authorization Server is supporting open 1227 Client registration, it must be extremely careful with any URL 1228 provided by the Client that will be displayed to the user (e.g. 1229 "logo_uri" and "policy_uri"). A rogue Client could specify a 1230 registration request with a reference to a drive-by download in the 1231 "policy_uri". The Authorization Server SHOULD check to see if the 1232 "logo_uri" and "policy_uri" have the same host as the hosts defined 1233 in the array of "redirect_uris" and that all of these resolve to 1234 valid Web pages. 1236 While the Client Secret can expire, the Registration Access Token 1237 should not expire while a client is still actively registered. If 1238 this token were to expire, a developer or Client could be left in a 1239 situation where they have no means of retrieving the Client's 1240 registration information or updating it. Were that the case, a new 1241 registration would be required, thereby getting a new Client 1242 Identifier. However, Registration Access Tokens MAY be rotated when 1243 the developer or client does a read or update operation on its Client 1244 Configuration Endpoint, and the developer or Client MUST use this new 1245 Registration Access Token. As the Registration Access Tokens are 1246 long-term credentials, and since the Registration Access Token is a 1247 Bearer token and acts as the sole authentication for use at the 1248 Client Configuration Endpoint, it MUST be protected by the developer 1249 or Client as described in OAuth 2.0 Bearer [RFC6750]. 1251 If a Client is deprovisioned from a server, any outstanding 1252 Registration Access Tokens for that client MUST be invalidated at the 1253 same time. Otherwise, this can lead to an inconsistent state wherein 1254 a Client could make requests to the Client Configuration Endpoint 1255 where the authentication would succeed but the action would fail 1256 because the Client is no longer valid. 1258 8. Normative References 1260 [IANA.Language] 1261 Internet Assigned Numbers Authority (IANA), "Language 1262 Subtag Registry", 2005. 1264 [JWK] Jones, M., "JSON Web Key (JWK)", 1265 draft-ietf-jose-json-web-key (work in progress), May 2013. 1267 [OAuth.JWT] 1268 Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 1269 (JWT) Bearer Token Profiles for OAuth 2.0", 1270 draft-ietf-oauth-jwt-bearer (work in progress), 1271 March 2013. 1273 [OAuth.SAML2] 1274 Campbell, B., Mortimore, C., and M. Jones, "SAML 2.0 1275 Bearer Assertion Profiles for OAuth 2.0", 1276 draft-ietf-oauth-saml2-bearer (work in progress), 1277 March 2013. 1279 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1280 Requirement Levels", BCP 14, RFC 2119, March 1997. 1282 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 1283 RFC 2246, January 1999. 1285 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1286 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1287 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1289 [RFC4627] Crockford, D., "The application/json Media Type for 1290 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1292 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1293 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1294 May 2008. 1296 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1297 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1299 [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying 1300 Languages", BCP 47, RFC 5646, September 2009. 1302 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 1303 Verification of Domain-Based Application Service Identity 1304 within Internet Public Key Infrastructure Using X.509 1305 (PKIX) Certificates in the Context of Transport Layer 1306 Security (TLS)", RFC 6125, March 2011. 1308 [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", 1309 RFC 6749, October 2012. 1311 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1312 Framework: Bearer Token Usage", RFC 6750, October 2012. 1314 Appendix A. Acknowledgments 1316 The authors thank the OAuth Working Group, the User-Managed Access 1317 Working Group, and the OpenID Connect Working Group participants for 1318 their input to this document. In particular, the following 1319 individuals have been instrumental in their review and contribution 1320 to various versions of this document: Amanda Anganes, Tim Bray, 1321 Domenico Catalano, George Fletcher, Thomas Hardjono, Phil Hunt, 1322 Torsten Lodderstedt, Eve Maler, Nov Matake, Nat Sakimura, and 1323 Christian Scholz. 1325 Appendix B. Document History 1327 [[ to be removed by the RFC editor before publication as an RFC ]] 1329 -11 1331 o Added localized text to registration request and response 1332 examples. 1334 o Removed "client_secret_jwt" and "private_key_jwt". 1336 o Clarified "tos_uri" and "policy_uri" definitions. 1338 o Added the OAuth Token Endpoint Authentication Methods registry for 1339 registering "token_endpoint_auth_method" metadata values. 1341 o Removed uses of non-ASCII characters, per RFC formatting rules. 1343 o Changed "expires_at" to "client_secret_expires_at" and "issued_at" 1344 to "client_id_issued_at" for greater clarity. 1346 o Added explanatory text for different credentials (Initial Access 1347 Token, Registration Access Token, Client Credentials) and what 1348 they're used for. 1350 o Added Client Lifecycle discussion and examples. 1352 o Defined Initial Access Token in Terminology section. 1354 -10 1356 o Added language to point out that scope values are service-specific 1358 o Clarified normative language around client metadata 1360 o Added extensibility to token_endpoint_auth_method using absolute 1361 URIs 1363 o Added security consideration about registering redirect URIs 1365 o Changed erroneous 403 responses to 401's with notes about token 1366 handling 1368 o Added example for initial registration credential 1370 -09 1371 o Added method of internationalization for Client Metadata values 1373 o Fixed SAML reference 1375 -08 1377 o Collapsed jwk_uri, jwk_encryption_uri, x509_uri, and 1378 x509_encryption_uri into a single jwks_uri parameter 1380 o Renamed grant_type to grant_types since it's a plural value 1382 o Formalized name of "OAuth 2.0" throughout document 1384 o Added JWT Bearer Assertion and SAML 2 Bearer Assertion to example 1385 grant types 1387 o Added response_types parameter and explanatory text on its use 1388 with and relationship to grant_types 1390 -07 1392 o Changed registration_access_url to registration_client_uri 1394 o Fixed missing text in 5.1 1396 o Added Pragma: no-cache to examples 1398 o Changed "no such client" error to 403 1400 o Renamed Client Registration Access Endpoint to Client 1401 Configuration Endpoint 1403 o Changed all the parameter names containing "_url" to instead use 1404 "_uri" 1406 o Updated example text for forming Client Configuration Endpoint URL 1408 -06 1410 o Removed secret_rotation as a client-initiated action, including 1411 removing client secret rotation endpoint and parameters. 1413 o Changed _links structure to single value registration_access_url. 1415 o Collapsed create/update/read responses into client info response. 1417 o Changed return code of create action to 201. 1419 o Added section to describe suggested generation and composition of 1420 Client Registration Access URL. 1422 o Added clarifying text to PUT and POST requests to specify JSON in 1423 the body. 1425 o Added Editor's Note to DELETE operation about its inclusion. 1427 o Added Editor's Note to registration_access_url about alternate 1428 syntax proposals. 1430 -05 1432 o changed redirect_uri and contact to lists instead of space 1433 delimited strings 1435 o removed operation parameter 1437 o added _links structure 1439 o made client update management more RESTful 1441 o split endpoint into three parts 1443 o changed input to JSON from form-encoded 1445 o added READ and DELETE operations 1447 o removed Requirements section 1449 o changed token_endpoint_auth_type back to 1450 token_endpoint_auth_method to match OIDC who changed to match us 1452 -04 1454 o removed default_acr, too undefined in the general OAuth2 case 1456 o removed default_max_auth_age, since there's no mechanism for 1457 supplying a non-default max_auth_age in OAuth2 1459 o clarified signing and encryption URLs 1461 o changed token_endpoint_auth_method to token_endpoint_auth_type to 1462 match OIDC 1464 -03 1465 o added scope and grant_type claims 1467 o fixed various typos and changed wording for better clarity 1469 o endpoint now returns the full set of client information 1471 o operations on client_update allow for three actions on metadata: 1472 leave existing value, clear existing value, replace existing value 1473 with new value 1475 -02 1477 o Reorganized contributors and references 1479 o Moved OAuth references to RFC 1481 o Reorganized model/protocol sections for clarity 1483 o Changed terminology to "client register" instead of "client 1484 associate" 1486 o Specified that client_id must match across all subsequent requests 1488 o Fixed RFC2XML formatting, especially on lists 1490 -01 1492 o Merged UMA and OpenID Connect registrations into a single document 1494 o Changed to form-paramter inputs to endpoint 1496 o Removed pull-based registration 1498 -00 1500 o Imported original UMA draft specification 1502 Authors' Addresses 1504 Justin Richer (editor) 1505 The MITRE Corporation 1507 Phone: 1508 Fax: 1509 Email: jricher@mitre.org 1510 URI: 1512 John Bradley 1513 Ping Identity 1515 Email: ve7jtb@ve7jtb.com 1517 Michael B. Jones 1518 Microsoft 1520 Email: mbj@microsoft.com 1521 URI: http://self-issued.info/ 1523 Maciej Machulak 1524 Newcastle University 1526 Email: m.p.machulak@ncl.ac.uk 1527 URI: http://ncl.ac.uk/