idnits 2.17.00 (12 Aug 2021) /tmp/idnits36174/draft-ietf-oauth-v2-21.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 : ---------------------------------------------------------------------------- -- The draft header indicates that this document obsoletes RFC5849, but the abstract doesn't seem to mention this, which it should. 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 (September 5, 2011) is 3910 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 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Downref: Normative reference to an Informational RFC: RFC 2818 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Downref: Normative reference to an Informational RFC: RFC 4949 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: draft-ietf-oauth-saml2-bearer has been published as RFC 7522 == Outdated reference: draft-ietf-oauth-v2-bearer has been published as RFC 6750 == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-00 == Outdated reference: draft-ietf-oauth-v2-threatmodel has been published as RFC 6819 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 8 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer-Lahav, Ed. 3 Internet-Draft Yahoo! 4 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: March 8, 2012 D. Hardt 7 Microsoft 8 September 5, 2011 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-21 13 Abstract 15 The OAuth 2.0 authorization protocol enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and the HTTP service, or by allowing the 19 third-party application to obtain access on its own behalf. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 8, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 57 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 6 58 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 59 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 7 60 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.3.3. Resource Owner Password Credentials . . . . . . . . . 8 62 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 63 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 64 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 65 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 11 66 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 11 67 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 12 68 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 13 69 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 13 70 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 14 71 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 15 72 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 15 73 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 15 74 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 15 75 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 16 76 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 16 77 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 18 78 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 19 79 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 20 80 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 20 81 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 20 82 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 22 83 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 23 84 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 25 85 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 26 86 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 27 87 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 29 88 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 30 89 4.3. Resource Owner Password Credentials . . . . . . . . . . . 32 90 4.3.1. Authorization Request and Response . . . . . . . . . . 33 91 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 33 92 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 34 93 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 35 94 4.4.1. Authorization Request and Response . . . . . . . . . . 36 95 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 36 96 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 36 97 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 37 98 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 37 99 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 38 100 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 39 101 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40 102 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 42 103 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 42 104 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 43 105 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 43 106 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 44 107 8.3. Defining New Authorization Grant Types . . . . . . . . . 44 108 8.4. Defining New Authorization Endpoint Response Types . . . 44 109 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 45 110 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 45 111 10. Security Considerations . . . . . . . . . . . . . . . . . . . 46 112 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 47 113 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 47 114 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 48 115 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 48 116 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 49 117 10.6. Authorization Code Redirection URI Manipulation . . . . . 49 118 10.7. Resource Owner Password Credentials . . . . . . . . . . . 50 119 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 51 120 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 51 121 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 51 122 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 51 123 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 52 124 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 53 125 10.14. Code Injection and Input Validation . . . . . . . . . . . 53 126 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 53 127 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 54 128 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 54 129 11.1.1. Registration Template . . . . . . . . . . . . . . . . 54 130 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 55 131 11.2.1. Registration Template . . . . . . . . . . . . . . . . 56 132 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 56 133 11.3. The OAuth Authorization Endpoint Response Type 134 Registry . . . . . . . . . . . . . . . . . . . . . . . . 58 135 11.3.1. Registration Template . . . . . . . . . . . . . . . . 59 136 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 59 137 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 59 138 11.4.1. Registration Template . . . . . . . . . . . . . . . . 60 139 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 61 140 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 61 141 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 62 142 13.1. Normative References . . . . . . . . . . . . . . . . . . 62 143 13.2. Informative References . . . . . . . . . . . . . . . . . 63 145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 64 147 1. Introduction 149 In the traditional client-server authentication model, the client 150 accesses a protected resource on the server by authenticating with 151 the server using the resource owner's credentials. In order to 152 provide third-party applications access to protected resources, the 153 resource owner shares its credentials with the third-party. This 154 creates several problems and limitations: 156 o Third-party applications are required to store the resource 157 owner's credentials for future use, typically a password in clear- 158 text. 159 o Servers are required to support password authentication, despite 160 the security weaknesses created by passwords. 161 o Third-party applications gain overly broad access to the resource 162 owner's protected resources, leaving resource owners without any 163 ability to restrict duration or access to a limited subset of 164 resources. 165 o Resource owners cannot revoke access to an individual third-party 166 without revoking access to all third-parties, and must do so by 167 changing their password. 168 o Compromise of any third-party application results in compromise of 169 the end-user's password and all of the data protected by that 170 password. 172 OAuth addresses these issues by introducing an authorization layer 173 and separating the role of the client from that of the resource 174 owner. In OAuth, the client requests access to resources controlled 175 by the resource owner and hosted by the resource server, and is 176 issued a different set of credentials than those of the resource 177 owner. 179 Instead of using the resource owner's credentials to access protected 180 resources, the client obtains an access token - a string denoting a 181 specific scope, lifetime, and other access attributes. Access tokens 182 are issued to third-party clients by an authorization server with the 183 approval of the resource owner. The client uses the access token to 184 access the protected resources hosted by the resource server. 186 For example, an end-user (resource owner) can grant a printing 187 service (client) access to her protected photos stored at a photo 188 sharing service (resource server), without sharing her username and 189 password with the printing service. Instead, she authenticates 190 directly with a server trusted by the photo sharing service 191 (authorization server) which issues the printing service delegation- 192 specific credentials (access token). 194 This specification is designed for use with HTTP [RFC2616]. The use 195 of OAuth with any transport protocol other than HTTP is undefined. 197 1.1. Roles 199 OAuth includes four roles working together to grant and provide 200 access to protected resources - access restricted resources requiring 201 authentication: 203 resource owner 204 An entity capable of granting access to a protected resource (e.g. 205 end-user). 206 resource server 207 The server hosting the protected resources, capable of accepting 208 and responding to protected resource requests using access tokens. 209 client 210 An application making protected resource requests on behalf of the 211 resource owner and with its authorization. 212 authorization server 213 The server issuing access tokens to the client after successfully 214 authenticating the resource owner and obtaining authorization. 216 The interaction between the authorization server and resource server 217 is beyond the scope of this specification. The authorization server 218 may be the same server as the resource server or a separate entity. 219 A single authorization server may issue access tokens accepted by 220 multiple resource servers. 222 1.2. Protocol Flow 224 +--------+ +---------------+ 225 | |--(A)- Authorization Request ->| Resource | 226 | | | Owner | 227 | |<-(B)-- Authorization Grant ---| | 228 | | +---------------+ 229 | | 230 | | +---------------+ 231 | |--(C)-- Authorization Grant -->| Authorization | 232 | Client | | Server | 233 | |<-(D)----- Access Token -------| | 234 | | +---------------+ 235 | | 236 | | +---------------+ 237 | |--(E)----- Access Token ------>| Resource | 238 | | | Server | 239 | |<-(F)--- Protected Resource ---| | 240 +--------+ +---------------+ 241 Figure 1: Abstract Protocol Flow 243 The abstract flow illustrated in Figure 1 describes the interaction 244 between the four roles and includes the following steps: 246 (A) The client requests authorization from the resource owner. The 247 authorization request can be made directly to the resource owner 248 (as shown), or preferably indirectly via an intermediary such as 249 an authorization server. 250 (B) The client receives an authorization grant which is a credential 251 representing the resource owner's authorization, expressed using 252 one of four grant types defined in this specification or using 253 an extension grant type. The authorization grant type depends 254 on the method used by the client to request authorization and 255 the types supported by the authorization server. 256 (C) The client requests an access token by authenticating with the 257 authorization server and presenting the authorization grant. 258 (D) The authorization server authenticates the client and validates 259 the authorization grant, and if valid issues an access token. 260 (E) The client requests the protected resource from the resource 261 server and authenticates by presenting the access token. 262 (F) The resource server validates the access token, and if valid, 263 serves the request. 265 1.3. Authorization Grant 267 An authorization grant is a credential representing the resource 268 owner's authorization (to access its protected resources) used by the 269 client to obtain an access token. This specification defines four 270 grant types: authorization code, implicit, resource owner password 271 credentials, and client credentials, as well as an extensibility 272 mechanism for defining additional types. 274 1.3.1. Authorization Code 276 The authorization code is obtained by using an authorization server 277 as an intermediary between the client and resource owner. Instead of 278 requesting authorization directly from the resource owner, the client 279 directs the resource owner to an authorization server (via its user- 280 agent as defined in [RFC2616]), which in turn directs the resource 281 owner back to the client with the authorization code. 283 Before directing the resource owner back to the client with the 284 authorization code, the authorization server authenticates the 285 resource owner and obtains authorization. Because the resource owner 286 only authenticates with the authorization server, the resource 287 owner's credentials are never shared with the client. 289 The authorization code provides a few important security benefits 290 such as the ability to authenticate the client, and the transmission 291 of the the access token directly to the client without passing it 292 through the resource owner's user-agnet, potentially exposing it to 293 others, including the resource owner. 295 1.3.2. Implicit 297 The implicit grant is a simplified authorization code flow optimized 298 for clients implemented in a browser using a scripting language such 299 as JavaScript. In the implicit flow, instead of issuing the client 300 an authorization code, the client is issued an access token directly 301 (as the result of the resource owner authorization). The grant type 302 is implicit as no intermediate credentials (such as an authorization 303 code) are issued (and later used to obtain an access token). 305 When issuing an implicit grant, the authorization server does not 306 authenticate the client and in some cases, the client identity can be 307 verified via the redirection URI used to deliver the access token to 308 the client. The access token may be exposed to the resource owner or 309 other applications with access to the resource owner's user-agent. 311 Implicit grants improve the responsiveness and efficiency of some 312 clients (such as a client implemented as an in-browser application) 313 since it reduces the number of round trips required to obtain an 314 access token. However, this convenience should be weighed against 315 the security implications of using implicit grants, especially when 316 the authorization code grant type is available. 318 1.3.3. Resource Owner Password Credentials 320 The resource owner password credentials (e.g. a username and 321 password) can be used directly as an authorization grant to obtain an 322 access token. The credentials should only be used when there is a 323 high degree of trust between the resource owner and the client (e.g. 324 its device operating system or a highly privileged application), and 325 when other authorization grant types are not available (such as an 326 authorization code). 328 Even though this grant type requires direct client access to the 329 resource owner credentials, the resource owner credentials are used 330 for a single request and are exchanged for an access token. This 331 grant type can eliminate the need for the client to store the 332 resource owner credentials for future use, by exchanging the 333 credentials with a long-lived access token or refresh token. 335 1.3.4. Client Credentials 337 The client credentials (or other forms of client authentication) can 338 be used as an authorization grant when the authorization scope is 339 limited to the protected resources under the control of the client, 340 or to protected resources previously arranged with the authorization 341 server. Client credentials are used as an authorization grant 342 typically when the client is acting on its own behalf (the client is 343 also the resource owner), or is requesting access to protected 344 resources based on an authorization previously arranged with the 345 authorization server. 347 1.4. Access Token 349 Access tokens are credentials used to access protected resources. An 350 access token is a string representing an authorization issued to the 351 client. The string is usually opaque to the client. Tokens 352 represent specific scopes and durations of access, granted by the 353 resource owner, and enforced by the resource server and authorization 354 server. 356 The token may denote an identifier used to retrieve the authorization 357 information, or self-contain the authorization information in a 358 verifiable manner (i.e. a token string consisting of some data and a 359 signature). Additional authentication credentials, which are beyond 360 the scope of this specification, may be required in order for the 361 client to use a token. 363 The access token provides an abstraction layer, replacing different 364 authorization constructs (e.g. username and password) with a single 365 token understood by the resource server. This abstraction enables 366 issuing access tokens more restrictive than the authorization grant 367 used to obtain them, as well as removing the resource server's need 368 to understand a wide range of authentication methods. 370 Access tokens can have different formats, structures, and methods of 371 utilization (e.g. cryptographic properties) based on the resource 372 server security requirements. Access token attributes and the 373 methods used to access protected resources are beyond the scope of 374 this specification and are defined by companion specifications. 376 1.5. Refresh Token 378 Refresh tokens are credentials used to obtain access tokens. Refresh 379 tokens are issued to the client by the authorization server and are 380 used to obtain a new access token when the current access token 381 becomes invalid or expires, or to obtain additional access tokens 382 with identical or narrower scope (access tokens may have a shorter 383 lifetime and fewer permissions than authorized by the resource 384 owner). Issuing a refresh token is optional and is included when 385 issuing an access token. 387 A refresh token is a string representing the authorization granted to 388 the client by the resource owner. The string is usually opaque to 389 the client. The token denotes an identifier used to retrieve the 390 authorization information. Unlike access tokens, refresh tokens are 391 intended for use only with authorization servers and are never sent 392 to resource servers. 394 +--------+ +---------------+ 395 | |--(A)------- Authorization Grant --------->| | 396 | | | | 397 | |<-(B)----------- Access Token -------------| | 398 | | & Refresh Token | | 399 | | | | 400 | | +----------+ | | 401 | |--(C)---- Access Token ---->| | | | 402 | | | | | | 403 | |<-(D)- Protected Resource --| Resource | | Authorization | 404 | Client | | Server | | Server | 405 | |--(E)---- Access Token ---->| | | | 406 | | | | | | 407 | |<-(F)- Invalid Token Error -| | | | 408 | | +----------+ | | 409 | | | | 410 | |--(G)----------- Refresh Token ----------->| | 411 | | | | 412 | |<-(H)----------- Access Token -------------| | 413 +--------+ & Optional Refresh Token +---------------+ 415 Figure 2: Refreshing an Expired Access Token 417 The flow illustrated in Figure 2 includes the following steps: 419 (A) The client requests an access token by authenticating with the 420 authorization server, and presenting an authorization grant. 421 (B) The authorization server authenticates the client and validates 422 the authorization grant, and if valid issues an access token and 423 a refresh token. 424 (C) The client makes a protected resource request to the resource 425 server by presenting the access token. 427 (D) The resource server validates the access token, and if valid, 428 serves the request. 429 (E) Steps (C) and (D) repeat until the access token expires. If the 430 client knows the access token expired, it skips to step (G), 431 otherwise it makes another protected resource request. 432 (F) Since the access token is invalid, the resource server returns 433 an invalid token error. 434 (G) The client requests a new access token by authenticating with 435 the authorization server and presenting the refresh token. The 436 client authentication requirements are based on the client type 437 and on the authorization server policies. 438 (H) The authorization server authenticates the client and validates 439 the refresh token, and if valid issues a new access token (and 440 optionally, a new refresh token). 442 1.6. Notational Conventions 444 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 445 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 446 specification are to be interpreted as described in [RFC2119]. 448 This specification uses the Augmented Backus-Naur Form (ABNF) 449 notation of [RFC5234]. 451 Certain security-related terms are to be understood in the sense 452 defined in [RFC4949]. These terms include, but are not limited to, 453 'attack', 'authentication', 'authorization', 'certificate', 454 'confidentiality', 'credential', 'encryption', 'identity', 'sign', 455 'signature', 'trust', 'validate', and 'verify'. 457 Unless otherwise noted, all the protocol parameter names and values 458 are case sensitive. 460 2. Client Registration 462 Before initiating the protocol, the client registers with the 463 authorization server. The means through which the client registers 464 with the authorization server are beyond the scope of this 465 specification, but typically involve end-user interaction with an 466 HTML registration form. 468 Client registration does not require a direct interaction between the 469 client and the authorization server. When supported by the 470 authorization server, registration can rely on other means for 471 establishing trust and obtaining the required client properties (e.g. 472 redirection URI, client type). For example, registration can be 473 accomplished using a self-issued or third-party-issued assertion, or 474 by the authorization server performing client discovery using a 475 trusted channel. 477 When registering a client, the client developer: 479 o specifies the client type as described in Section 2.1, 480 o provides its client redirection URIs as described in 481 Section 3.1.2, and 482 o includes any other information required by the authorization 483 server (e.g. application name, website, description, logo image, 484 the acceptance of legal terms). 486 2.1. Client Types 488 OAuth defines two client types, based on their ability to 489 authenticate securely with the authorization server (i.e. ability to 490 maintain the confidentiality of their client credentials): 492 confidential 493 Clients capable of maintaining the confidentiality of their 494 credentials (e.g. client implemented on a secure server with 495 restricted access to the client credentials), or capable of secure 496 client authentication using other means. 497 public 498 Clients incapable of maintaining the confidentiality of their 499 credentials (e.g. clients executing on the resource owner's device 500 such as an installed native application or a web browser-based 501 application), and incapable of secure client authentication via 502 any other mean. 504 The client type designation is based on the authorization server's 505 definition of secure authentication and its acceptable exposure 506 levels of client credentials. 508 This specification has been designed around the following client 509 profiles: 511 web application 512 A web application is a confidential client running on a web 513 server. Resource owners access the client via an HTML user 514 interface rendered in a user-agent on the resource owner's device. 515 The client credentials as well as any access token issued to the 516 client are stored on the web server and are not exposed to or 517 accessible by the resource owner. 519 user-agent-based application 520 A user-agent-based application is a public client in which the 521 client code is downloaded from a web server and executes within a 522 user-agent (e.g. web browser) on the resource owner's device. 523 Protocol data and credentials are easily accessible (and often 524 visible) to the resource owner. Since such applications reside 525 within the user-agent, they can make seamless use of the user- 526 agent capabilities when requesting authorization. 527 native application 528 A native application is a public client installed and executed on 529 the resource owner's device. Protocol data and credentials are 530 accessible to the resource owner. It is assumed that any client 531 authentication credentials included in the application can be 532 extracted. On the other hand, dynamically issued credentials such 533 access tokens or refresh tokens, can receive an acceptable level 534 of protection. At a minimum, these credentials are protected from 535 hostile servers which the application may interact with. On some 536 platform these credentials might be protected from other 537 applications residing on the same device. 539 2.2. Client Identifier 541 The authorization server issues the registered client a client 542 identifier - a unique string representing the registration 543 information provided by the client. The client identifier is not a 544 secret, it is exposed to the resource owner, and MUST NOT be used 545 alone for client authentication. 547 2.3. Client Authentication 549 If the client type is confidential, the client and authorization 550 server establish a client authentication method suitable for the 551 security requirements of the authorization server. The authorization 552 server MAY accept any form of client authentication meeting its 553 security requirements. 555 Confidential clients are typically issued (or establish) a set of 556 client credentials used for authenticating with the authorization 557 server (e.g. password, public/private key pair). 559 The authorization server SHOULD NOT make assumptions about the client 560 type or accept the type information provided without establishing 561 trust with the client or its developer. The authorization server MAY 562 establish a client authentication method with public clients. 563 However, the authorization server MUST NOT rely on public client 564 authentication for the purpose of identifying the client. 566 The client MUST NOT use more than one authentication method in each 567 request. 569 2.3.1. Client Password 571 Clients in possession of a client password MAY use the HTTP Basic 572 authentication scheme as defined in [RFC2617] to authenticate with 573 the authorization server. The client identifier is used as the 574 username, and the client password is used as the password. 576 For example (extra line breaks are for display purposes only): 578 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 580 Alternatively, the authorization server MAY allow including the 581 client credentials in the request body using the following 582 parameters: 584 client_id 585 REQUIRED. The client identifier issued to the client during 586 the registration process described by Section 2.2. 587 client_secret 588 REQUIRED. The client secret. The client MAY omit the 589 parameter if the client secret is an empty string. 591 Including the client credentials in the request body using the two 592 parameters is NOT RECOMMENDED, and should be limited to clients 593 unable to directly utilize the HTTP Basic authentication scheme (or 594 other password-based HTTP authentication schemes). 596 For example, requesting to refresh an access token (Section 6) using 597 the body parameters (extra line breaks are for display purposes 598 only): 600 POST /token HTTP/1.1 601 Host: server.example.com 602 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 604 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 605 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 607 The authorization server MUST require the use of a transport-layer 608 security mechanism when sending requests to the token endpoint, as 609 requests using this authentication method result in the transmission 610 of clear-text credentials. 612 Since this client authentication method involves a password, the 613 authorization server MUST protect any endpoint utilizing it against 614 brute force attacks. 616 2.3.2. Other Authentication Methods 618 The authorization server MAY support any suitable HTTP authentication 619 scheme matching its security requirements. When using other 620 authentication methods, the authorization server MUST define a 621 mapping between the client identifier (registration record) and 622 authentication scheme. 624 2.4. Unregistered Clients 626 This specification does not exclude the use of unregistered clients. 627 However, the use with such clients is beyond the scope of this 628 specification, and requires additional security analysis and review 629 of its interoperability impact. 631 3. Protocol Endpoints 633 The authorization process utilizes two endpoints (HTTP resources): 635 o Authorization endpoint - used to obtain authorization from the 636 resource owner via user-agent redirection. 637 o Token endpoint - used to exchange an authorization grant for an 638 access token, typically with client authentication. 640 Not every authorization grant type utilizes both endpoints. 641 Extension grant types MAY define additional endpoints as needed. 643 3.1. Authorization Endpoint 645 The authorization endpoint is used to interact with the resource 646 owner and obtain an authorization grant. The authorization server 647 MUST first verify the identity of the resource owner. The way in 648 which the authorization server authenticates the resource owner (e.g. 649 username and password login, session cookies) is beyond the scope of 650 this specification. 652 The means through which the client obtains the location of the 653 authorization endpoint are beyond the scope of this specification but 654 the location is typically provided in the service documentation. 656 The endpoint URI MAY include an "application/x-www-form-urlencoded" 657 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 658 section 3.4), which MUST be retained when adding additional query 659 parameters. The endpoint URI MUST NOT include a fragment component. 661 Since requests to the authorization endpoint result in user 662 authentication and the transmission of clear-text credentials (in the 663 HTTP response), the authorization server MUST require the use of a 664 transport-layer security mechanism when sending requests to the 665 authorization endpoint. The authorization server MUST support TLS 666 1.0 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 667 replacements, and MAY support additional transport-layer mechanisms 668 meeting its security requirements. 670 The authorization server MUST support the use of the HTTP "GET" 671 method [RFC2616] for the authorization endpoint, and MAY support the 672 use of the "POST" method as well. 674 Parameters sent without a value MUST be treated as if they were 675 omitted from the request. The authorization server SHOULD ignore 676 unrecognized request parameters. Request and response parameters 677 MUST NOT be included more than once. 679 3.1.1. Response Type 681 The authorization endpoint is used by the authorization code grant 682 type and implicit grant type flows. The client informs the 683 authorization server of the desired grant type using the following 684 parameter: 686 response_type 687 REQUIRED. The value MUST be one of "code" for requesting an 688 authorization code as described by Section 4.1.1, "token" for 689 requesting an access token (implicit grant) as described by 690 Section 4.2.1, or a registered extension value as described by 691 Section 8.4. If the response type contains one or more space 692 characters (%x20), it is interpreted as a space-delimited list 693 of values, where the order of values does not matter (e.g. "a 694 b" is the same as "b a"). 696 If an authorization request is missing the "response_type" parameter, 697 the authorization server SHOULD return an error response as described 698 in Section 4.1.2.1. 700 3.1.2. Redirection Endpoint 702 After completing its interaction with the resource owner, the 703 authorization server directs the resource owner's user-agent back to 704 the client. The authorization server redirects the user-agent to the 705 client's redirection endpoint previously established with the 706 authorization server during the client registration process or when 707 making the authorization request. 709 The redirection endpoint URI MUST be an absolute URI as defined by 710 [RFC3986] section 4.3. The endpoint URI MAY include an 711 "application/x-www-form-urlencoded" formatted 712 ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), 713 which MUST be retained when adding additional query parameters. The 714 endpoint URI MUST NOT include a fragment component. 716 3.1.2.1. Endpoint Request Confidentiality 718 If a redirection request will result in the transmission of an 719 authorization code or access token over an open network (between the 720 resource owner's user-agent and the client), the client SHOULD 721 require the use of a transport-layer security mechanism. 723 Lack of transport-layer security can have a severe impact on the 724 security of the client and the protected resources it is authorized 725 to access. The use of transport-layer security is particularly 726 critical when the authorization process is used as a form of 727 delegated end-user authentication by the client (e.g. third-party 728 sign-in service). 730 3.1.2.2. Registration Requirements 732 The authorization server SHOULD require all clients to register their 733 redirection URI prior to using the authorization endpoint, and MUST 734 require the following clients to register their redirection URI: 736 o Public clients. 737 o Confidential clients utilizing the implicit grant type. 739 The authorization server SHOULD require the client to provide the 740 complete redirection URI (the client MAY use the "state" request 741 parameter to achieve per-request customization). The authorization 742 server MAY allow the client to register multiple redirection URIs. 743 If requiring the registration of the complete redirection URI is not 744 possible, the authorization server SHOULD require the registration of 745 the URI scheme, authority, and path (allowing the client to 746 dynamically change only the query component of the redirection URI 747 when requesting authorization). 749 3.1.2.3. Dynamic Configuration 751 If multiple redirection URIs have been registered, if only part of 752 the redirection URI has been registered, or if no redirection URI has 753 been registered, the client MUST include a redirection URI with the 754 authorization request using the "redirect_uri" request parameter. 756 When a redirection URI is included in an authorization request, the 757 authorization server MUST compare and match the value received 758 against at least one of the registered redirection URIs (or URI 759 components) as defined in [RFC3986] section 6, if any redirection 760 URIs were registered. If the client registration included the full 761 redirection URI, the authorization server MUST compare the two URIs 762 using simple string comparison as defined in [RFC3986] section 6.2.1. 764 If the authorization server allows the client to dynamically change 765 the query component of the redirection URI, the client MUST ensure 766 that manipulation of the query component by an attacker cannot lead 767 to an abuse of the redirection endpoint as described in 768 Section 10.15. 770 3.1.2.4. Invalid Endpoint 772 If an authorization request fails validation due to a missing, 773 invalid, or mismatching redirection URI, the authorization server 774 SHOULD inform the resource owner of the error, and MUST NOT 775 automatically redirect the user-agent to the invalid redirection URI. 777 The authorization server SHOULD NOT redirect the user-agent to 778 unregistered or untrusted URIs to prevent the authorization endpoint 779 from being used as an open redirector. 781 3.1.2.5. Endpoint Content 783 The redirection request to the client's endpoint typically results in 784 an HTML document response, processed by the user-agent. If the HTML 785 response is served directly as the result of the redirection request, 786 any script included in the HTML document will execute with full 787 access to the redirection URI and the credentials it contains. 789 The client MUST NOT include any untrusted third-party scripts in the 790 redirection endpoint response (e.g. third-party analytics, social 791 plug-ins, ad networks) without first ensuring that its own scripts 792 used to extract and remove the credentials from the URI will execute 793 first. 795 The client SHOULD NOT include any third-party scripts in the 796 redirection endpoint response. Instead, it should extract the 797 credentials from the URI and redirect the user-agent again to another 798 endpoint without the credentials in the URI. 800 3.2. Token Endpoint 802 The token endpoint is used by the client to obtain an access token by 803 presenting its authorization grant or refresh token. The token 804 endpoint is used with every authorization grant except for the 805 implicit grant type (since an access token is issued directly). 807 The means through which the client obtains the location of the token 808 endpoint are beyond the scope of this specification but is typically 809 provided in the service documentation. 811 The endpoint URI MAY include an "application/x-www-form-urlencoded" 812 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 813 section 3.4), which MUST be retained when adding additional query 814 parameters. The endpoint URI MUST NOT include a fragment component. 816 Since requests to the token endpoint result in the transmission of 817 clear-text credentials (in the HTTP request and response), the 818 authorization server MUST require the use of a transport-layer 819 security mechanism when sending requests to the token endpoint. The 820 authorization server MUST support TLS 1.0 ([RFC2246]), SHOULD support 821 TLS 1.2 ([RFC5246]) and its future replacements, and MAY support 822 additional transport-layer mechanisms meeting its security 823 requirements. 825 The client MUST use the HTTP "POST" method when making access token 826 requests. 828 Parameters sent without a value MUST be treated as if they were 829 omitted from the request. The authorization server SHOULD ignore 830 unrecognized request parameters. Request and response parameters 831 MUST NOT be included more than once. 833 3.2.1. Client Authentication 835 Confidential clients, clients issued client credentials, or clients 836 assigned other authentication requirements, MUST authenticate with 837 the authorization server as described in Section 2.3 when making 838 requests to the token endpoint. Client authentication is used for: 840 o Enforcing the binding of refresh tokens and authorization codes to 841 the client they are issued. Client authentication is critical 842 when an authorization code is transmitted to the redirection 843 endpoint over an insecure channel, or when the redirection URI has 844 not been registered in full. 845 o Recovering from a compromised client by disabling the client or 846 changing its credentials, thus preventing an attacker from abusing 847 stolen refresh tokens. Changing a single set of client 848 credentials is significantly faster than revoking an entire set of 849 refresh tokens. 851 o Implementing authentication management best practices which 852 require periodic credential rotation. Rotation of an entire set 853 of refresh tokens can be challenging, while rotation of a single 854 set of client credentials is significantly easier. 856 A public client that was not issued a client password MAY use the 857 "client_id" request parameter to identify itself when sending 858 requests to the token endpoint. 860 The security ramifications of allowing unauthenticated access by 861 public clients to the token endpoint, as well as the issuance of 862 refresh tokens to public clients MUST be taken into consideration. 864 3.3. Access Token Scope 866 The authorization and token endpoints allow the client to specify the 867 scope of the access request using the "scope" request parameter. In 868 turn, the authorization server uses the "scope" response parameter to 869 inform the client of the scope of the access token issued. 871 The value of the scope parameter is expressed as a list of space- 872 delimited, case sensitive strings. The strings are defined by the 873 authorization server. If the value contains multiple space-delimited 874 strings, their order does not matter, and each string adds an 875 additional access range to the requested scope. 877 The authorization server MAY fully or partially ignore the scope 878 requested by the client based on the authorization server policy or 879 the resource owner's instructions. If the issued access token scope 880 is different from the one requested by the client, the authorization 881 server SHOULD include the "scope" response parameter to inform the 882 client of the actual scope granted. 884 4. Obtaining Authorization 886 To request an access token, the client obtains authorization from the 887 resource owner. The authorization is expressed in the form of an 888 authorization grant which the client uses to request the access 889 token. OAuth defines four grant types: authorization code, implicit, 890 resource owner password credentials, and client credentials. It also 891 provides an extension mechanism for defining additional grant types. 893 4.1. Authorization Code 895 The authorization code grant type is used to obtain both access 896 tokens and refresh tokens and is optimized for confidential clients. 897 As a redirection-based flow, the client must be capable of 898 interacting with the resource owner's user-agent (typically a web 899 browser) and capable of receiving incoming requests (via redirection) 900 from the authorization server. 902 +----------+ 903 | resource | 904 | owner | 905 | | 906 +----------+ 907 ^ 908 | 909 (B) 910 +----|-----+ Client Identifier +---------------+ 911 | -+----(A)-- & Redirection URI ---->| | 912 | User- | | Authorization | 913 | Agent -+----(B)-- User authenticates --->| Server | 914 | | | | 915 | -+----(C)-- Authorization Code ---<| | 916 +-|----|---+ +---------------+ 917 | | ^ v 918 (A) (C) | | 919 | | | | 920 ^ v | | 921 +---------+ | | 922 | |>---(D)-- Authorization Code ---------' | 923 | Client | & Redirection URI | 924 | | | 925 | |<---(E)----- Access Token -------------------' 926 +---------+ (w/ Optional Refresh Token) 928 Figure 3: Authorization Code Flow 930 The flow illustrated in Figure 3 includes the following steps: 932 (A) The client initiates the flow by directing the resource owner's 933 user-agent to the authorization endpoint. The client includes 934 its client identifier, requested scope, local state, and a 935 redirection URI to which the authorization server will send the 936 user-agent back once access is granted (or denied). 937 (B) The authorization server authenticates the resource owner (via 938 the user-agent) and establishes whether the resource owner 939 grants or denies the client's access request. 941 (C) Assuming the resource owner grants access, the authorization 942 server redirects the user-agent back to the client using the 943 redirection URI provided earlier. The redirection URI includes 944 an authorization code and any local state provided by the client 945 earlier. 946 (D) The client requests an access token from the authorization 947 server's token endpoint by including the authorization code 948 received in the previous step. When making the request, the 949 client authenticates with the authorization server. The client 950 includes the redirection URI used to obtain the authorization 951 code for verification. 952 (E) The authorization server authenticates the client, validates the 953 authorization code, and ensures the redirection URI received 954 matches the URI used to redirect the client in step (C). If 955 valid, responds back with an access token and optional refresh 956 token. 958 4.1.1. Authorization Request 960 The client constructs the request URI by adding the following 961 parameters to the query component of the authorization endpoint URI 962 using the "application/x-www-form-urlencoded" format as defined by 963 [W3C.REC-html401-19991224]: 965 response_type 966 REQUIRED. Value MUST be set to "code". 967 client_id 968 REQUIRED. The client identifier as described in Section 2.2. 969 redirect_uri 970 OPTIONAL, as described in Section 3.1.2. 971 scope 972 OPTIONAL. The scope of the access request as described by 973 Section 3.3. 974 state 975 RECOMMENDED. An opaque value used by the client to maintain 976 state between the request and callback. The authorization 977 server includes this value when redirecting the user-agent back 978 to the client. The parameter SHOULD be used for preventing 979 cross-site request forgery as described in Section 10.12. 981 The client directs the resource owner to the constructed URI using an 982 HTTP redirection response, or by other means available to it via the 983 user-agent. 985 For example, the client directs the user-agent to make the following 986 HTTP request using transport-layer security (extra line breaks are 987 for display purposes only): 989 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 990 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 991 Host: server.example.com 993 The authorization server validates the request to ensure all required 994 parameters are present and valid. If the request is valid, the 995 authorization server authenticates the resource owner and obtains an 996 authorization decision (by asking the resource owner or by 997 establishing approval via other means). 999 When a decision is established, the authorization server directs the 1000 user-agent to the provided client redirection URI using an HTTP 1001 redirection response, or by other means available to it via the user- 1002 agent. 1004 4.1.2. Authorization Response 1006 If the resource owner grants the access request, the authorization 1007 server issues an authorization code and delivers it to the client by 1008 adding the following parameters to the query component of the 1009 redirection URI using the "application/x-www-form-urlencoded" format: 1011 code 1012 REQUIRED. The authorization code generated by the 1013 authorization server. The authorization code MUST expire 1014 shortly after it is issued to mitigate the risk of leaks. A 1015 maximum authorization code lifetime of 10 minutes is 1016 RECOMMENDED. The client MUST NOT reuse the authorization code. 1017 If an authorization code is used more than once, the 1018 authorization server SHOULD attempt to revoke all tokens 1019 previously issued based on that authorization code. The 1020 authorization code is bound to the client identifier and 1021 redirection URI. 1022 state 1023 REQUIRED if the "state" parameter was present in the client 1024 authorization request. Set to the exact value received from 1025 the client. 1027 For example, the authorization server redirects the user-agent by 1028 sending the following HTTP response: 1030 HTTP/1.1 302 Found 1031 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1032 &state=xyz 1034 The client SHOULD ignore unrecognized response parameters. The 1035 authorization code string size is left undefined by this 1036 specification. The client should avoid making assumptions about code 1037 value sizes. The authorization server should document the size of 1038 any value it issues. 1040 4.1.2.1. Error Response 1042 If the request fails due to a missing, invalid, or mismatching 1043 redirection URI, or if the client identifier provided is invalid, the 1044 authorization server SHOULD inform the resource owner of the error, 1045 and MUST NOT automatically redirect the user-agent to the invalid 1046 redirection URI. 1048 If the resource owner denies the access request or if the request 1049 fails for reasons other than a missing or invalid redirection URI, 1050 the authorization server informs the client by adding the following 1051 parameters to the query component of the redirection URI using the 1052 "application/x-www-form-urlencoded" format: 1054 error 1055 REQUIRED. A single error code from the following: 1056 invalid_request 1057 The request is missing a required parameter, includes an 1058 unsupported parameter or parameter value, or is otherwise 1059 malformed. 1060 unauthorized_client 1061 The client is not authorized to request an authorization 1062 code using this method. 1063 access_denied 1064 The resource owner or authorization server denied the 1065 request. 1066 unsupported_response_type 1067 The authorization server does not support obtaining an 1068 authorization code using this method. 1070 invalid_scope 1071 The requested scope is invalid, unknown, or malformed. 1072 server_error 1073 The authorization server encountered an unexpected 1074 condition which prevented it from fulfilling the request. 1075 temporarily_unavailable 1076 The authorization server is currently unable to handle 1077 the request due to a temporary overloading or maintenance 1078 of the server. 1079 error_description 1080 OPTIONAL. A human-readable UTF-8 encoded text providing 1081 additional information, used to assist the client developer in 1082 understanding the error that occurred. 1083 error_uri 1084 OPTIONAL. A URI identifying a human-readable web page with 1085 information about the error, used to provide the client 1086 developer with additional information about the error. 1087 state 1088 REQUIRED if a valid "state" parameter was present in the client 1089 authorization request. Set to the exact value received from 1090 the client. 1092 For example, the authorization server redirects the user-agent by 1093 sending the following HTTP response: 1095 HTTP/1.1 302 Found 1096 Location: https://client.example.com/cb?error=access_denied&state=xyz 1098 4.1.3. Access Token Request 1100 The client makes a request to the token endpoint by adding the 1101 following parameters using the "application/x-www-form-urlencoded" 1102 format in the HTTP request entity-body: 1104 grant_type 1105 REQUIRED. Value MUST be set to "authorization_code". 1106 code 1107 REQUIRED. The authorization code received from the 1108 authorization server. 1109 redirect_uri 1110 REQUIRED, if the "redirect_uri" parameter was included in the 1111 authorization request described in Section 4.1.1, and their 1112 values MUST be identical. 1114 If the client type is confidential or was issued client credentials 1115 (or assigned other authentication requirements), the client MUST 1116 authenticate with the authorization server as described in 1117 Section 3.2.1. 1119 For example, the client makes the following HTTP request using 1120 transport-layer security (extra line breaks are for display purposes 1121 only): 1123 POST /token HTTP/1.1 1124 Host: server.example.com 1125 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1126 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1128 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1129 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1131 The authorization server MUST: 1133 o require client authentication for confidential clients or for any 1134 client issued client credentials (or with other authentication 1135 requirements), 1136 o authenticate the client if client authentication is included and 1137 ensure the authorization code was issued to the authenticated 1138 client, 1139 o verify that the authorization code is valid, and 1140 o ensure that the "redirect_uri" parameter is present if the 1141 "redirect_uri" parameter was included in the initial authorization 1142 request described in Section 4.1.1, and that their values are 1143 identical. 1145 4.1.4. Access Token Response 1147 If the access token request is valid and authorized, the 1148 authorization server issues an access token and optional refresh 1149 token as described in Section 5.1. If the request client 1150 authentication failed or is invalid, the authorization server returns 1151 an error response as described in Section 5.2. 1153 An example successful response: 1155 HTTP/1.1 200 OK 1156 Content-Type: application/json;charset=UTF-8 1157 Cache-Control: no-store 1158 Pragma: no-cache 1160 { 1161 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1162 "token_type":"example", 1163 "expires_in":3600, 1164 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1165 "example_parameter":"example_value" 1166 } 1168 4.2. Implicit Grant 1170 The implicit grant type is used to obtain access tokens (it does not 1171 support the issuance of refresh tokens) and is optimized for public 1172 clients known to operate a particular redirection URI. These clients 1173 are typically implemented in a browser using a scripting language 1174 such as JavaScript. 1176 As a redirection-based flow, the client must be capable of 1177 interacting with the resource owner's user-agent (typically a web 1178 browser) and capable of receiving incoming requests (via redirection) 1179 from the authorization server. 1181 Unlike the authorization code grant type in which the client makes 1182 separate requests for authorization and access token, the client 1183 receives the access token as the result of the authorization request. 1185 The implicit grant type does not include client authentication, and 1186 relies on the presence of the resource owner and the registration of 1187 the redirection URI. Because the access token is encoded into the 1188 redirection URI, it may be exposed to the resource owner and other 1189 applications residing on its device. 1191 +----------+ 1192 | Resource | 1193 | Owner | 1194 | | 1195 +----------+ 1196 ^ 1197 | 1198 (B) 1199 +----|-----+ Client Identifier +---------------+ 1200 | -+----(A)-- & Redirection URI --->| | 1201 | User- | | Authorization | 1202 | Agent -|----(B)-- User authenticates -->| Server | 1203 | | | | 1204 | |<---(C)--- Redirection URI ----<| | 1205 | | with Access Token +---------------+ 1206 | | in Fragment 1207 | | +---------------+ 1208 | |----(D)--- Redirection URI ---->| Web-Hosted | 1209 | | without Fragment | Client | 1210 | | | Resource | 1211 | (F) |<---(E)------- Script ---------<| | 1212 | | +---------------+ 1213 +-|--------+ 1214 | | 1215 (A) (G) Access Token 1216 | | 1217 ^ v 1218 +---------+ 1219 | | 1220 | Client | 1221 | | 1222 +---------+ 1224 Figure 4: Implicit Grant Flow 1226 The flow illustrated in Figure 4 includes the following steps: 1228 (A) The client initiates the flow by directing the resource owner's 1229 user-agent to the authorization endpoint. The client includes 1230 its client identifier, requested scope, local state, and a 1231 redirection URI to which the authorization server will send the 1232 user-agent back once access is granted (or denied). 1233 (B) The authorization server authenticates the resource owner (via 1234 the user-agent) and establishes whether the resource owner 1235 grants or denies the client's access request. 1237 (C) Assuming the resource owner grants access, the authorization 1238 server redirects the user-agent back to the client using the 1239 redirection URI provided earlier. The redirection URI includes 1240 the access token in the URI fragment. 1241 (D) The user-agent follows the redirection instructions by making a 1242 request to the web-hosted client resource (which does not 1243 include the fragment). The user-agent retains the fragment 1244 information locally. 1245 (E) The web-hosted client resource returns a web page (typically an 1246 HTML document with an embedded script) capable of accessing the 1247 full redirection URI including the fragment retained by the 1248 user-agent, and extracting the access token (and other 1249 parameters) contained in the fragment. 1250 (F) The user-agent executes the script provided by the web-hosted 1251 client resource locally, which extracts the access token and 1252 passes it to the client. 1254 4.2.1. Authorization Request 1256 The client constructs the request URI by adding the following 1257 parameters to the query component of the authorization endpoint URI 1258 using the "application/x-www-form-urlencoded" format: 1260 response_type 1261 REQUIRED. Value MUST be set to "token". 1262 client_id 1263 REQUIRED. The client identifier as described in Section 2.2. 1264 redirect_uri 1265 OPTIONAL, as described in Section 3.1.2. 1266 scope 1267 OPTIONAL. The scope of the access request as described by 1268 Section 3.3. 1269 state 1270 RECOMMENDED. An opaque value used by the client to maintain 1271 state between the request and callback. The authorization 1272 server includes this value when redirecting the user-agent back 1273 to the client. The parameter SHOULD be used for preventing 1274 cross-site request forgery as described in Section 10.12. 1276 The client directs the resource owner to the constructed URI using an 1277 HTTP redirection response, or by other means available to it via the 1278 user-agent. 1280 For example, the client directs the user-agent to make the following 1281 HTTP request using transport-layer security (extra line breaks are 1282 for display purposes only): 1284 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1285 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1286 Host: server.example.com 1288 The authorization server validates the request to ensure all required 1289 parameters are present and valid. The authorization server MUST 1290 verify that the redirection URI to which it will redirect the access 1291 token matches a redirection URI registered by the client as described 1292 in Section 3.1.2. 1294 If the request is valid, the authorization server authenticates the 1295 resource owner and obtains an authorization decision (by asking the 1296 resource owner or by establishing approval via other means). 1298 When a decision is established, the authorization server directs the 1299 user-agent to the provided client redirection URI using an HTTP 1300 redirection response, or by other means available to it via the user- 1301 agent. 1303 4.2.2. Access Token Response 1305 If the resource owner grants the access request, the authorization 1306 server issues an access token and delivers it to the client by adding 1307 the following parameters to the fragment component of the redirection 1308 URI using the "application/x-www-form-urlencoded" format: 1310 access_token 1311 REQUIRED. The access token issued by the authorization server. 1312 token_type 1313 REQUIRED. The type of the token issued as described in 1314 Section 7.1. Value is case insensitive. 1315 expires_in 1316 OPTIONAL. The lifetime in seconds of the access token. For 1317 example, the value "3600" denotes that the access token will 1318 expire in one hour from the time the response was generated. 1319 scope 1320 OPTIONAL. The scope of the access request as described by 1321 Section 3.3. 1322 state 1323 REQUIRED if the "state" parameter was present in the client 1324 authorization request. Set to the exact value received from 1325 the client. 1327 For example, the authorization server redirects the user-agent by 1328 sending the following HTTP response (URI extra line breaks are for 1329 display purposes only): 1331 HTTP/1.1 302 Found 1332 Location: http://example.com/rd#access_token=2YotnFZFEjr1zCsicMWpAA 1333 &state=xyz&token_type=example&expires_in=3600 1335 Developers should note that some HTTP client implementations do not 1336 support the inclusion of a fragment component in the HTTP "Location" 1337 response header field. Such client will require using other methods 1338 for redirecting the client than a 3xx redirection response. For 1339 example, returning an HTML page which includes a 'continue' button 1340 with an action linked to the redirection URI. 1342 The client SHOULD ignore unrecognized response parameters. The 1343 access token string size is left undefined by this specification. 1344 The client should avoid making assumptions about value sizes. The 1345 authorization server should document the size of any value it issues. 1347 4.2.2.1. Error Response 1349 If the request fails due to a missing, invalid, or mismatching 1350 redirection URI, or if the client identifier provided is invalid, the 1351 authorization server SHOULD inform the resource owner of the error, 1352 and MUST NOT automatically redirect the user-agent to the invalid 1353 redirection URI. 1355 If the resource owner denies the access request or if the request 1356 fails for reasons other than a missing or invalid redirection URI, 1357 the authorization server informs the client by adding the following 1358 parameters to the fragment component of the redirection URI using the 1359 "application/x-www-form-urlencoded" format: 1361 error 1362 REQUIRED. A single error code from the following: 1363 invalid_request 1364 The request is missing a required parameter, includes an 1365 unsupported parameter or parameter value, or is otherwise 1366 malformed. 1367 unauthorized_client 1368 The client is not authorized to request an access token 1369 using this method. 1371 access_denied 1372 The resource owner or authorization server denied the 1373 request. 1374 unsupported_response_type 1375 The authorization server does not support obtaining an 1376 access token using this method. 1377 invalid_scope 1378 The requested scope is invalid, unknown, or malformed. 1379 server_error 1380 The authorization server encountered an unexpected 1381 condition which prevented it from fulfilling the request. 1382 temporarily_unavailable 1383 The authorization server is currently unable to handle 1384 the request due to a temporary overloading or maintenance 1385 of the server. 1386 error_description 1387 OPTIONAL. A human-readable UTF-8 encoded text providing 1388 additional information, used to assist the client developer in 1389 understanding the error that occurred. 1390 error_uri 1391 OPTIONAL. A URI identifying a human-readable web page with 1392 information about the error, used to provide the client 1393 developer with additional information about the error. 1394 state 1395 REQUIRED if a valid "state" parameter was present in the client 1396 authorization request. Set to the exact value received from 1397 the client. 1399 For example, the authorization server redirects the user-agent by 1400 sending the following HTTP response: 1402 HTTP/1.1 302 Found 1403 Location: https://client.example.com/cb#error=access_denied&state=xyz 1405 4.3. Resource Owner Password Credentials 1407 The resource owner password credentials grant type is suitable in 1408 cases where the resource owner has a trust relationship with the 1409 client, such as its device operating system or a highly privileged 1410 application. The authorization server should take special care when 1411 enabling this grant type, and only allow it when other flows are not 1412 viable. 1414 The grant type is suitable for clients capable of obtaining the 1415 resource owner's credentials (username and password, typically using 1416 an interactive form). It is also used to migrate existing clients 1417 using direct authentication schemes such as HTTP Basic or Digest 1418 authentication to OAuth by converting the stored credentials to an 1419 access token. 1421 +----------+ 1422 | Resource | 1423 | Owner | 1424 | | 1425 +----------+ 1426 v 1427 | Resource Owner 1428 (A) Password Credentials 1429 | 1430 v 1431 +---------+ +---------------+ 1432 | |>--(B)---- Resource Owner ------->| | 1433 | | Password Credentials | Authorization | 1434 | Client | | Server | 1435 | |<--(C)---- Access Token ---------<| | 1436 | | (w/ Optional Refresh Token) | | 1437 +---------+ +---------------+ 1439 Figure 5: Resource Owner Password Credentials Flow 1441 The flow illustrated in Figure 5 includes the following steps: 1443 (A) The resource owner provides the client with its username and 1444 password. 1445 (B) The client requests an access token from the authorization 1446 server's token endpoint by including the credentials received 1447 from the resource owner. When making the request, the client 1448 authenticates with the authorization server. 1449 (C) The authorization server authenticates the client and validates 1450 the resource owner credentials, and if valid issues an access 1451 token. 1453 4.3.1. Authorization Request and Response 1455 The method through which the client obtains the resource owner 1456 credentials is beyond the scope of this specification. The client 1457 MUST discard the credentials once an access token has been obtained. 1459 4.3.2. Access Token Request 1461 The client makes a request to the token endpoint by adding the 1462 following parameters using the "application/x-www-form-urlencoded" 1463 format in the HTTP request entity-body: 1465 grant_type 1466 REQUIRED. Value MUST be set to "password". 1467 username 1468 REQUIRED. The resource owner username, encoded as UTF-8. 1469 password 1470 REQUIRED. The resource owner password, encoded as UTF-8. 1471 scope 1472 OPTIONAL. The scope of the access request as described by 1473 Section 3.3. 1475 If the client type is confidential or was issued client credentials 1476 (or assigned other authentication requirements), the client MUST 1477 authenticate with the authorization server as described in 1478 Section 3.2.1. 1480 For example, the client makes the following HTTP request using 1481 transport-layer security (extra line breaks are for display purposes 1482 only): 1484 POST /token HTTP/1.1 1485 Host: server.example.com 1486 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1487 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1489 grant_type=password&username=johndoe&password=A3ddj3w 1491 The authorization server MUST: 1493 o require client authentication for confidential clients or for any 1494 client issued client credentials (or with other authentication 1495 requirements), 1496 o authenticate the client if client authentication is included, and 1497 o validate the resource owner password credentials. 1499 Since this access token request utilizes the resource owner's 1500 password, the authorization server MUST protect the endpoint against 1501 brute force attacks. 1503 4.3.3. Access Token Response 1505 If the access token request is valid and authorized, the 1506 authorization server issues an access token and optional refresh 1507 token as described in Section 5.1. If the request failed client 1508 authentication or is invalid, the authorization server returns an 1509 error response as described in Section 5.2. 1511 An example successful response: 1513 HTTP/1.1 200 OK 1514 Content-Type: application/json;charset=UTF-8 1515 Cache-Control: no-store 1516 Pragma: no-cache 1518 { 1519 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1520 "token_type":"example", 1521 "expires_in":3600, 1522 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1523 "example_parameter":"example_value" 1524 } 1526 4.4. Client Credentials 1528 The client can request an access token using only its client 1529 credentials (or other supported means of authentication) when the 1530 client is requesting access to the protected resources under its 1531 control, or those of another resource owner which has been previously 1532 arranged with the authorization server (the method of which is beyond 1533 the scope of this specification). 1535 The client credentials grant type MUST only be used by confidential 1536 clients. 1538 +---------+ +---------------+ 1539 | | | | 1540 | |>--(A)- Client Authentication --->| Authorization | 1541 | Client | | Server | 1542 | |<--(B)---- Access Token ---------<| | 1543 | | | | 1544 +---------+ +---------------+ 1546 Figure 6: Client Credentials Flow 1548 The flow illustrated in Figure 6 includes the following steps: 1550 (A) The client authenticates with the authorization server and 1551 requests an access token from the token endpoint. 1552 (B) The authorization server authenticates the client, and if valid 1553 issues an access token. 1555 4.4.1. Authorization Request and Response 1557 Since the client authentication is used as the authorization grant, 1558 no additional authorization request is needed. 1560 4.4.2. Access Token Request 1562 The client makes a request to the token endpoint by adding the 1563 following parameters using the "application/x-www-form-urlencoded" 1564 format in the HTTP request entity-body: 1566 grant_type 1567 REQUIRED. Value MUST be set to "client_credentials". 1568 scope 1569 OPTIONAL. The scope of the access request as described by 1570 Section 3.3. 1572 The client MUST authenticate with the authorization server as 1573 described in Section 3.2.1. 1575 For example, the client makes the following HTTP request using 1576 transport-layer security (extra line breaks are for display purposes 1577 only): 1579 POST /token HTTP/1.1 1580 Host: server.example.com 1581 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1582 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1584 grant_type=client_credentials 1586 The authorization server MUST authenticate the client. 1588 4.4.3. Access Token Response 1590 If the access token request is valid and authorized, the 1591 authorization server issues an access token as described in 1592 Section 5.1. A refresh token SHOULD NOT be included. If the request 1593 failed client authentication or is invalid, the authorization server 1594 returns an error response as described in Section 5.2. 1596 An example successful response: 1598 HTTP/1.1 200 OK 1599 Content-Type: application/json;charset=UTF-8 1600 Cache-Control: no-store 1601 Pragma: no-cache 1603 { 1604 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1605 "token_type":"example", 1606 "expires_in":3600, 1607 "example_parameter":"example_value" 1608 } 1610 4.5. Extensions 1612 The client uses an extension grant type by specifying the grant type 1613 using an absolute URI (defined by the authorization server) as the 1614 value of the "grant_type" parameter of the token endpoint, and by 1615 adding any additional parameters necessary. 1617 For example, to request an access token using a SAML 2.0 assertion 1618 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1619 makes the following HTTP request using transport-layer security (line 1620 breaks are for display purposes only): 1622 POST /token HTTP/1.1 1623 Host: server.example.com 1624 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1626 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F 1627 saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ 1628 [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1630 If the access token request is valid and authorized, the 1631 authorization server issues an access token and optional refresh 1632 token as described in Section 5.1. If the request failed client 1633 authentication or is invalid, the authorization server returns an 1634 error response as described in Section 5.2. 1636 5. Issuing an Access Token 1638 If the access token request is valid and authorized, the 1639 authorization server issues an access token and optional refresh 1640 token as described in Section 5.1. If the request failed client 1641 authentication or is invalid, the authorization server returns an 1642 error response as described in Section 5.2. 1644 5.1. Successful Response 1646 The authorization server issues an access token and optional refresh 1647 token, and constructs the response by adding the following parameters 1648 to the entity body of the HTTP response with a 200 (OK) status code: 1650 access_token 1651 REQUIRED. The access token issued by the authorization server. 1652 token_type 1653 REQUIRED. The type of the token issued as described in 1654 Section 7.1. Value is case insensitive. 1655 expires_in 1656 OPTIONAL. The lifetime in seconds of the access token. For 1657 example, the value "3600" denotes that the access token will 1658 expire in one hour from the time the response was generated. 1659 refresh_token 1660 OPTIONAL. The refresh token which can be used to obtain new 1661 access tokens using the same authorization grant as described 1662 in Section 6. 1663 scope 1664 OPTIONAL. The scope of the access request as described by 1665 Section 3.3. 1667 The parameters are included in the entity body of the HTTP response 1668 using the "application/json" media type as defined by [RFC4627]. The 1669 parameters are serialized into a JSON structure by adding each 1670 parameter at the highest structure level. Parameter names and string 1671 values are included as JSON strings. Numerical values are included 1672 as JSON numbers. The order of parameters does not matter and can 1673 vary. 1675 The authorization server MUST include the HTTP "Cache-Control" 1676 response header field [RFC2616] with a value of "no-store" in any 1677 response containing tokens, credentials, or other sensitive 1678 information, as well as the "Pragma" response header field [RFC2616] 1679 with a value of "no-cache". 1681 For example: 1683 HTTP/1.1 200 OK 1684 Content-Type: application/json;charset=UTF-8 1685 Cache-Control: no-store 1686 Pragma: no-cache 1688 { 1689 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1690 "token_type":"example", 1691 "expires_in":3600, 1692 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1693 "example_parameter":"example_value" 1694 } 1696 The client SHOULD ignore unrecognized response parameters. The sizes 1697 of tokens and other values received from the authorization server are 1698 left undefined. The client should avoid making assumptions about 1699 value sizes. The authorization server should document the size of 1700 any value it issues. 1702 5.2. Error Response 1704 The authorization server responds with an HTTP 400 (Bad Request) 1705 status code and includes the following parameters with the response: 1707 error 1708 REQUIRED. A single error code from the following: 1709 invalid_request 1710 The request is missing a required parameter, includes an 1711 unsupported parameter or parameter value, repeats a 1712 parameter, includes multiple credentials, utilizes more 1713 than one mechanism for authenticating the client, or is 1714 otherwise malformed. 1715 invalid_client 1716 Client authentication failed (e.g. unknown client, no 1717 client authentication included, or unsupported 1718 authentication method). The authorization server MAY 1719 return an HTTP 401 (Unauthorized) status code to indicate 1720 which HTTP authentication schemes are supported. If the 1721 client attempted to authenticate via the "Authorization" 1722 request header field, the authorization server MUST 1723 respond with an HTTP 401 (Unauthorized) status code, and 1724 include the "WWW-Authenticate" response header field 1725 matching the authentication scheme used by the client. 1727 invalid_grant 1728 The provided authorization grant is invalid, expired, 1729 revoked, does not match the redirection URI used in the 1730 authorization request, or was issued to another client. 1731 unauthorized_client 1732 The authenticated client is not authorized to use this 1733 authorization grant type. 1734 unsupported_grant_type 1735 The authorization grant type is not supported by the 1736 authorization server. 1737 invalid_scope 1738 The requested scope is invalid, unknown, malformed, or 1739 exceeds the scope granted by the resource owner. 1740 error_description 1741 OPTIONAL. A human-readable UTF-8 encoded text providing 1742 additional information, used to assist the client developer in 1743 understanding the error that occurred. 1744 error_uri 1745 OPTIONAL. A URI identifying a human-readable web page with 1746 information about the error, used to provide the client 1747 developer with additional information about the error. 1749 The parameters are included in the entity body of the HTTP response 1750 using the "application/json" media type as defined by [RFC4627]. The 1751 parameters are serialized into a JSON structure by adding each 1752 parameter at the highest structure level. Parameter names and string 1753 values are included as JSON strings. Numerical values are included 1754 as JSON numbers. The order of parameters does not matter and can 1755 vary. 1757 For example: 1759 HTTP/1.1 400 Bad Request 1760 Content-Type: application/json;charset=UTF-8 1761 Cache-Control: no-store 1762 Pragma: no-cache 1764 { 1765 "error":"invalid_request" 1766 } 1768 6. Refreshing an Access Token 1770 If the authorization server issued a refresh token to the client, the 1771 client makes a refresh request to the token endpoint by adding the 1772 following parameters using the "application/x-www-form-urlencoded" 1773 format in the HTTP request entity-body: 1775 grant_type 1776 REQUIRED. Value MUST be set to "refresh_token". 1777 refresh_token 1778 REQUIRED. The refresh token issued to the client. 1779 scope 1780 OPTIONAL. The scope of the access request as described by 1781 Section 3.3. The requested scope MUST be equal or lesser than 1782 the scope originally granted by the resource owner, and if 1783 omitted is treated as equal to the scope originally granted by 1784 the resource owner. 1786 Because refresh tokens are typically long-lasting credentials used to 1787 request additional access tokens, the refresh token is bound to the 1788 client it was issued. If the client type is confidential or was 1789 issued client credentials (or assigned other authentication 1790 requirements), the client MUST authenticate with the authorization 1791 server as described in Section 3.2.1. 1793 For example, the client makes the following HTTP request using 1794 transport-layer security (extra line breaks are for display purposes 1795 only): 1797 POST /token HTTP/1.1 1798 Host: server.example.com 1799 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1800 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1802 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1804 The authorization server MUST: 1806 o require client authentication for confidential clients or for any 1807 client issued client credentials (or with other authentication 1808 requirements), 1809 o authenticate the client if client authentication is included and 1810 ensure the refresh token was issued to the authenticated client, 1811 and 1812 o validate the refresh token. 1814 If valid and authorized, the authorization server issues an access 1815 token as described in Section 5.1. If the request failed 1816 verification or is invalid, the authorization server returns an error 1817 response as described in Section 5.2. 1819 The authorization server MAY issue a new refresh token, in which case 1820 the client MUST discard the old refresh token and replace it with the 1821 new refresh token. The authorization server MAY revoke the old 1822 refresh token after issuing a new refresh token to the client. If a 1823 new refresh token is issued, the refresh token scope MUST be 1824 identical to that of the refresh token included by the client in the 1825 request. 1827 7. Accessing Protected Resources 1829 The client accesses protected resources by presenting the access 1830 token to the resource server. The resource server MUST validate the 1831 access token and ensure it has not expired and that its scope covers 1832 the requested resource. The methods used by the resource server to 1833 validate the access token (as well as any error responses) are beyond 1834 the scope of this specification, but generally involve an interaction 1835 or coordination between the resource server and the authorization 1836 server. 1838 The method in which the client utilized the access token to 1839 authenticate with the resource server depends on the type of access 1840 token issued by the authorization server. Typically, it involves 1841 using the HTTP "Authorization" request header field [RFC2617] with an 1842 authentication scheme defined by the access token type specification. 1844 7.1. Access Token Types 1846 The access token type provides the client with the information 1847 required to successfully utilize the access token to make a protected 1848 resource request (along with type-specific attributes). The client 1849 MUST NOT use an access token if it does not understand or does not 1850 trust the token type. 1852 For example, the "bearer" token type defined in 1853 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1854 token string in the request: 1856 GET /resource/1 HTTP/1.1 1857 Host: example.com 1858 Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw 1860 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 1861 utilized by issuing a MAC key together with the access token which is 1862 used to sign certain components of the HTTP requests: 1864 GET /resource/1 HTTP/1.1 1865 Host: example.com 1866 Authorization: MAC id="h480djs93hd8", 1867 nonce="274312:dj83hs9s", 1868 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1870 The above examples are provided for illustration purposes only. 1871 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 1872 [I-D.ietf-oauth-v2-http-mac] specifications before use. 1874 Each access token type definition specifies the additional attributes 1875 (if any) sent to the client together with the "access_token" response 1876 parameter. It also defines the HTTP authentication method used to 1877 include the access token when making a protected resource request. 1879 8. Extensibility 1881 8.1. Defining Access Token Types 1883 Access token types can be defined in one of two ways: registered in 1884 the access token type registry (following the procedures in 1885 Section 11.1), or by using a unique absolute URI as its name. 1887 Types utilizing a URI name SHOULD be limited to vendor-specific 1888 implementations that are not commonly applicable, and are specific to 1889 the implementation details of the resource server where they are 1890 used. 1892 All other types MUST be registered. Type names MUST conform to the 1893 type-name ABNF. If the type definition includes a new HTTP 1894 authentication scheme, the type name SHOULD be identical to the HTTP 1895 authentication scheme name (as defined by [RFC2617]). The token type 1896 "example" is reserved for use in examples. 1898 type-name = 1*name-char 1899 name-char = "-" / "." / "_" / DIGIT / ALPHA 1901 8.2. Defining New Endpoint Parameters 1903 New request or response parameters for use with the authorization 1904 endpoint or the token endpoint are defined and registered in the 1905 parameters registry following the procedure in Section 11.2. 1907 Parameter names MUST conform to the param-name ABNF and parameter 1908 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1909 to the syntax of an existing parameter). 1911 param-name = 1*name-char 1912 name-char = "-" / "." / "_" / DIGIT / ALPHA 1914 Unregistered vendor-specific parameter extensions that are not 1915 commonly applicable, and are specific to the implementation details 1916 of the authorization server where they are used SHOULD utilize a 1917 vendor-specific prefix that is not likely to conflict with other 1918 registered values (e.g. begin with 'companyname_'). 1920 8.3. Defining New Authorization Grant Types 1922 New authorization grant types can be defined by assigning them a 1923 unique absolute URI for use with the "grant_type" parameter. If the 1924 extension grant type requires additional token endpoint parameters, 1925 they MUST be registered in the OAuth parameters registry as described 1926 by Section 11.2. 1928 8.4. Defining New Authorization Endpoint Response Types 1930 New response types for use with the authorization endpoint are 1931 defined and registered in the authorization endpoint response type 1932 registry following the procedure in Section 11.3. Response type 1933 names MUST conform to the response-type ABNF. 1935 response-type = response-name *( SP response-name ) 1936 response-name = 1*response-char 1937 response-char = "_" / DIGIT / ALPHA 1939 If a response type contains one of more space characters (%x20), it 1940 is compared as a space-delimited list of values in which the order of 1941 values does not matter. Only one order of values can be registered, 1942 which covers all other arrangements of the same set of values. 1944 For example, the response type "token code" is left undefined by this 1945 specification. However, an extension can define and register the 1946 "token code" response type. Once registered, the same combination 1947 cannot be registered as "code token", but both values can be used to 1948 denote the same response type. 1950 8.5. Defining Additional Error Codes 1952 In cases where protocol extensions (i.e. access token types, 1953 extension parameters, or extension grant types) require additional 1954 error codes to be used with the authorization code grant error 1955 response (Section 4.1.2.1), the implicit grant error response 1956 (Section 4.2.2.1), or the token error response (Section 5.2), such 1957 error codes MAY be defined. 1959 Extension error codes MUST be registered (following the procedures in 1960 Section 11.4) if the extension they are used in conjunction with is a 1961 registered access token type, a registered endpoint parameter, or an 1962 extension grant type. Error codes used with unregistered extensions 1963 MAY be registered. 1965 Error codes MUST conform to the error-code ABNF, and SHOULD be 1966 prefixed by an identifying name when possible. For example, an error 1967 identifying an invalid value set to the extension parameter "example" 1968 should be named "example_invalid". 1970 error-code = ALPHA *error-char 1971 error-char = "-" / "." / "_" / DIGIT / ALPHA 1973 9. Native Applications 1975 Native applications are clients installed and executed on the 1976 resource owner's device (i.e. desktop application, native mobile 1977 application). Native applications may require special consideration 1978 related to security, platform capabilities, and overall end-user 1979 experience. 1981 The authorization endpoint requires interaction between the client 1982 and the resource owner's user-agent. Native applications can invoke 1983 an external user-agent or embed a user-agent within the application. 1984 For example: 1986 o External user-agent - the native application can capture the 1987 response from the authorization server using a redirection URI 1988 with a scheme registered with the operating system to invoke the 1989 client as the handler, manual copy-and-paste of the credentials, 1990 running a local web server, installing a user-agent extension, or 1991 by providing a redirection URI identifying a server-hosted 1992 resource under the client's control, which in turn makes the 1993 response available to the native application. 1994 o Embedded user-agent - the native application obtains the response 1995 by directly communicating with the embedded user-agent by 1996 monitoring state changes emitted during the resource load, or 1997 accessing the user-agent's cookies storage. 1999 When choosing between an external or embedded user-agent, developers 2000 should consider: 2002 o External user-agents may improve completion rate as the resource 2003 owner may already have an active session with the authorization 2004 server removing the need to re-authenticate. It provides a 2005 familiar end-user experience and functionality. The resource 2006 owner may also rely on user-agent features or extensions to assist 2007 with authentication (e.g. password manager, 2-factor device 2008 reader). 2009 o Embedded user-agents may offer improved usability, as they remove 2010 the need to switch context and open new windows. 2011 o Embedded user-agents pose a security challenge because resource 2012 owners are authenticating in an unidentified window without access 2013 to the visual protections found in most external user-agents. 2014 Embedded user-agents educate end-user to trust unidentified 2015 requests for authentication (making phishing attacks easier to 2016 execute). 2018 When choosing between the implicit grant type and the authorization 2019 code grant type, the following should be considered: 2021 o Native applications that use the authorization code grant type 2022 SHOULD do so without using client credentials, due to the native 2023 application's inability to keep client credentials confidential. 2024 o When using the implicit grant type flow a refresh token is not 2025 returned which requires repeating the authorization process once 2026 the access token expires. 2028 10. Security Considerations 2030 As a flexible and extensible framework, OAuth's security 2031 considerations depend on many factors. The following sections 2032 provide implementers with security guidelines focused on the three 2033 client profiles described in Section 2.1: web application, user- 2034 agent-based application, and native application. 2036 A comprehensive OAuth security model and analysis, as well as 2037 background for the protocol design is provided by 2038 [I-D.ietf-oauth-v2-threatmodel]. 2040 10.1. Client Authentication 2042 The authorization server establishes client credentials with web 2043 application clients for the purpose of client authentication. The 2044 authorization server is encouraged to consider stronger client 2045 authentication means than a client password. Web application clients 2046 MUST ensure confidentiality of client passwords and other client 2047 credentials. 2049 The authorization server MUST NOT issue client passwords or other 2050 client credentials to native application or user-agent-based 2051 application clients for the purpose of client authentication. The 2052 authorization server MAY issue a client password or other credentials 2053 for a specific installation of a native application client on a 2054 specific device. 2056 When client authentication is not possible, the authorization server 2057 SHOULD employ other means to validate the client's identity. For 2058 example, by requiring the registration of the client redirection URI 2059 or enlisting the resource owner to confirm identity. A valid 2060 redirection URI is not sufficient to verify the client's identity 2061 when asking for end-user authorization, but can be used to prevent 2062 delivering credentials to a counterfeit client after obtaining end- 2063 user authorization. 2065 The authorization server must consider the security implications of 2066 interacting with unauthenticated clients and take measures to limit 2067 the potential exposure of other credentials (e.g. refresh tokens) 2068 issued to such clients. 2070 10.2. Client Impersonation 2072 A malicious client can impersonate another client and obtain access 2073 to protected resources, if the impersonated client fails to, or is 2074 unable to, keep its client credentials confidential. 2076 The authorization server MUST authenticate the client whenever 2077 possible. If the authorization server cannot authenticate the client 2078 due to the client's nature, the authorization server MUST require the 2079 registration of any redirection URI used for receiving authorization 2080 responses, and SHOULD utilize other means to protect resource owners 2081 from such malicious clients. For example, engaging the resource 2082 owner to assist in identifying the client and its origin. 2084 The authorization server SHOULD enforce explicit resource owner 2085 authentication and provide the resource owner with information about 2086 the client and the requested authorization scope and lifetime. It is 2087 up to the resource owner to review the information in the context of 2088 the current client, and authorize or deny the request. 2090 The authorization server SHOULD NOT process repeated authorization 2091 requests automatically (without active resource owner interaction) 2092 without authenticating the client or relying on other measures to 2093 ensure the repeated request comes from the original client and not an 2094 impersonator. 2096 10.3. Access Tokens 2098 Access token (as well as any access token type-specific attributes) 2099 MUST be kept confidential in transit and storage, and only shared 2100 among the authorization server, the resource servers the access token 2101 is valid for, and the client to whom the access token is issued. 2103 When using the implicit grant type, the access token is transmitted 2104 in the URI fragment, which can expose it to unauthorized parties. 2106 The authorization server MUST ensure that access tokens cannot be 2107 generated, modified, or guessed to produce valid access tokens by 2108 unauthorized parties. 2110 The client SHOULD request access tokens with the minimal scope and 2111 lifetime necessary. The authorization server SHOULD take the client 2112 identity into account when choosing how to honor the requested scope 2113 and lifetime, and MAY issue an access token with a less rights than 2114 requested. 2116 10.4. Refresh Tokens 2118 Authorization servers MAY issue refresh tokens to web application 2119 clients and native application clients. 2121 Refresh tokens MUST be kept confidential in transit and storage, and 2122 shared only among the authorization server and the client to whom the 2123 refresh tokens were issued. The authorization server MUST maintain 2124 the binding between a refresh token and the client to whom it was 2125 issued. 2127 The authorization server MUST verify the binding between the refresh 2128 token and client identity whenever the client identity can be 2129 authenticated. When client authentication is not possible, the 2130 authorization server SHOULD deploy other means to detect refresh 2131 token abuse. 2133 For example, the authorization server could employ refresh token 2134 rotation in which a new refresh token is issued with every access 2135 token refresh response. The previous refresh token is invalidated 2136 but retained by the authorization server. If a refresh token is 2137 compromised and subsequently used by both the attacker and the 2138 legitimate client, one of them will present an invalidated refresh 2139 token which will inform the authorization server of the breach. 2141 The authorization server MUST ensure that refresh tokens cannot be 2142 generated, modified, or guessed to produce valid refresh tokens by 2143 unauthorized parties. 2145 10.5. Authorization Codes 2147 The transmission of authorization codes SHOULD be made over a secure 2148 channel, and the client SHOULD implement TLS for use with its 2149 redirection URI if the URI identifies a network resource. Effort 2150 should be made to keep authorization codes confidential. Since 2151 authorization codes are transmitted via user-agent redirections, they 2152 could potentially be disclosed through user-agent history and HTTP 2153 referrer headers. 2155 Authorization codes operate as plaintext bearer credentials, used to 2156 verify that the resource owner who granted authorization at the 2157 authorization server, is the same resource owner returning to the 2158 client to complete the process. Therefore, if the client relies on 2159 the authorization code for its own resource owner authentication, the 2160 client redirection endpoint MUST require TLS. 2162 Authorization codes MUST be short lived and single use. If the 2163 authorization server observes multiple attempts to exchange an 2164 authorization code for an access token, the authorization server 2165 SHOULD attempt to revoke all access tokens already granted based on 2166 the compromised authorization code. 2168 If the client can be authenticated, the authorization servers MUST 2169 authenticate the client and ensure that the authorization code was 2170 issued to the same client. 2172 10.6. Authorization Code Redirection URI Manipulation 2174 When requesting authorization using the authorization code grant 2175 type, the client can specify a redirection URI via the "redirect_uri" 2176 parameter. If an attacker can manipulate the value of the 2177 redirection URI, it can cause the authorization server to redirect 2178 the resource owner user-agent to a URI under the control of the 2179 attacker with the authorization code. 2181 An attacker can create an account at a legitimate client and initiate 2182 the authorization flow. When the attacker is sent to the 2183 authorization server to grant access, the attacker grabs the 2184 authorization URI provided by the legitimate client, and replaces the 2185 client's redirection URI with a URI under the control of the 2186 attacker. The attacker then tricks the victim into following the 2187 manipulated link to authorize access to the legitimate client. 2189 Once at the authorization server, the victim is prompted with a 2190 normal, valid request on behalf of a legitimate and familiar client, 2191 and authorizes the request. The victim is then redirected to an 2192 endpoint under the control of the attacker with the authorization 2193 code. The attacker completes the authorization flow by sending the 2194 authorization code to the client using the original redirection URI 2195 provided by the client. The client exchanges the authorization code 2196 with an access token and links it to the attacker's client account 2197 which can now gain access to the protected resources authorized by 2198 the victim (via the client). 2200 In order to prevent such an attack, the authorization server MUST 2201 ensure that the redirection URI used to obtain the authorization 2202 code, is the same as the redirection URI provided when exchanging the 2203 authorization code for an access token. The authorization server 2204 MUST require public clients and SHOULD require confidential clients 2205 to register their redirection URI and if provided in the request, 2206 MUST validate the redirection URI received in the authorization 2207 request against the registered value. 2209 10.7. Resource Owner Password Credentials 2211 The resource owner password credentials grant type is often used for 2212 legacy or migration reasons. It reduces the overall risk of storing 2213 username and password by the client, but does not eliminate the need 2214 to expose highly privileged credentials to the client. 2216 This grant type carries a higher risk than other grant types because 2217 it maintains the password anti-pattern this protocol seeks to avoid. 2218 The client could abuse the password or the password could 2219 unintentionally be disclosed to an attacker (e.g. via log files or 2220 other records kept by the client). 2222 Additionally, because the resource owner does not have control over 2223 the authorization process (the resource owner involvement ends when 2224 it hands over its credentials to the client), the client can obtain 2225 access tokens with a broader scope and longer lifetime than desired 2226 by the resource owner. The authorization server should consider the 2227 scope and lifetime of access tokens issued via this grant type. 2229 The authorization server and client SHOULD minimize use of this grant 2230 type and utilize other grant types whenever possible. 2232 10.8. Request Confidentiality 2234 Access tokens, refresh tokens, resource owner passwords, and client 2235 credentials MUST NOT be transmitted in the clear. Authorization 2236 codes SHOULD NOT be transmitted in the clear. 2238 10.9. Endpoints Authenticity 2240 In order to prevent man-in-the-middle and phishing attacks, the 2241 authorization server MUST implement and require TLS with server 2242 authentication as defined by [RFC2818] for any request sent to the 2243 authorization and token endpoints. The client MUST validate the 2244 authorization server's TLS certificate in accordance with its 2245 requirements for server identity authentication. 2247 10.10. Credentials Guessing Attacks 2249 The authorization server MUST prevent attackers from guessing access 2250 tokens, authorization codes, refresh tokens, resource owner 2251 passwords, and client credentials. 2253 When generating tokens and other credentials not intended for 2254 handling by end-users, the authorization server MUST use a reasonable 2255 level of entropy in order to mitigate the risk of guessing attacks. 2256 The authorization server MUST utilize other means to protect 2257 credentials intended for end-user usage. 2259 10.11. Phishing Attacks 2261 Wide deployment of this and similar protocols may cause end-users to 2262 become inured to the practice of being redirected to websites where 2263 they are asked to enter their passwords. If end-users are not 2264 careful to verify the authenticity of these websites before entering 2265 their credentials, it will be possible for attackers to exploit this 2266 practice to steal resource owners' passwords. 2268 Service providers should attempt to educate end-users about the risks 2269 phishing attacks pose, and should provide mechanisms that make it 2270 easy for end-users to confirm the authenticity of their sites. 2271 Client developers should consider the security implications of how 2272 they interact with the user-agent (e.g., external, embedded), and the 2273 ability of the end-user to verify the authenticity of the 2274 authorization server. 2276 To reduce the risk of phishing attacks, the authorization servers 2277 MUST utilize TLS on every endpoint used for end-user interaction. 2279 10.12. Cross-Site Request Forgery 2281 Cross-site request forgery (CSRF) is an exploit in which an attacker 2282 causes the user-agent of a victim end-user to follow a malicious URI 2283 (e.g. provided to the user-agent as a misleading link, image, or 2284 redirection) to a trusting server (usually established via the 2285 presence of a valid session cookie). 2287 A CSRF attack against the client's redirection URI allows an attacker 2288 to inject their own authorization code or access token, which can 2289 result in the client using an access token associated with the 2290 attacker's protected resources rather than the victim's (e.g. save 2291 the victim's bank account information to a protected resource 2292 controlled by the attacker). 2294 The client MUST implement CSRF protection for its redirection URI. 2295 This is typically accomplished by requiring any request sent to the 2296 redirection URI endpoint to include a value that binds the request to 2297 the user-agent's authenticated state (e.g. a hash of the session 2298 cookie used to authentication the user-agent). The client SHOULD 2299 utilize the "state" request parameter to deliver this value to the 2300 authorization server when making an authorization request. 2302 Once authorization has been obtained from the end-user, the 2303 authorization server redirects the end-user's user-agent back to the 2304 client with the required binding value contained in the "state" 2305 parameter. The binding value enables the client to validate the 2306 validity of the request by matching the binding value to the user- 2307 agent's authenticated state. The binding value used for CSRF 2308 protection MUST contain a non-guessable value, and the user-agent's 2309 authenticated state (e.g. session cookie, HTML5 local storage) MUST 2310 be kept in a location accessible only to the client and the user- 2311 agent (i.e., protected by same-origin policy). 2313 A CSRF attack against the against the authorization server's 2314 authorization endpoint can result in an attacker obtaining end-user 2315 authorization for a malicious client without involving or alerting 2316 the end-user. 2318 The authorization server MUST implement CSRF protection for its 2319 authorization endpoint, and ensure that a malicious client cannot 2320 obtain authorization without the awareness and explicit consent of 2321 the resource owner. 2323 10.13. Clickjacking 2325 In a clickjacking attack, an attacker registers a legitimate client 2326 and then constructs a malicious site in which it loads the 2327 authorization server's authorization endpoint web page in a 2328 transparent iframe overlaid on top of a set of dummy buttons which 2329 are carefully constructed to be placed directly under important 2330 buttons on the authorization page. When an end-user clicks a 2331 misleading visible button, the end-user is actually clicking an 2332 invisible button on the authorization page (such as an "Authorize" 2333 button). This allows an attacker to trick a resource owner into 2334 granting its client access without their knowledge. 2336 To prevent this form of attack, native applications SHOULD use 2337 external browsers instead of embedding browsers in an iframe when 2338 requesting end-user authorization. For most newer browsers, 2339 avoidance of iframes can be enforced by the authorization server 2340 using the (non-standard) "x-frame-options" header. This header can 2341 have two values, "deny" and "sameorigin", which will block any 2342 framing, or framing by sites with a different origin, respectively. 2343 For older browsers, javascript framebusting techniques can be used 2344 but may not be effective in all browsers. 2346 10.14. Code Injection and Input Validation 2348 A code injection attack occurs when an input or otherwise external 2349 variable is used by an application in which that input can cause 2350 modification of the application logic when used unsanitized. This 2351 may allow an attacker to gain access to the application device or its 2352 data, cause denial of service, or a wide range of malicious side- 2353 effects. 2355 The Authorization server and client MUST validate and sanitize any 2356 value received, and in particular, the value of the "state" and 2357 "redirect_uri" parameters. 2359 10.15. Open Redirectors 2361 The authorization server authorization endpoint and the client 2362 redirection endpoint can be improperly configured and operate as open 2363 redirectors. An open redirector is an endpoint using a parameter to 2364 automatically redirect a user-agent to the location specified by the 2365 parameter value without any validation. 2367 Open redirectors can be used in phishing attacks, or by an attacker 2368 to get end-users to visit malicious sites by making the URI's 2369 authority look like a familiar and trusted destination. In addition, 2370 if the authorization server allows the client to register only part 2371 of the redirection URI, an attacker can use an open redirector 2372 operated by the client to construct a redirection URI that will pass 2373 the authorization server validation but will send the authorization 2374 code or access token to an endpoint under the control of the 2375 attacker. 2377 11. IANA Considerations 2379 11.1. The OAuth Access Token Type Registry 2381 This specification establishes the OAuth access token type registry. 2383 Access token types are registered on the advice of one or more 2384 Designated Experts (appointed by the IESG or their delegate), with a 2385 Specification Required (using terminology from [RFC5226]). However, 2386 to allow for the allocation of values prior to publication, the 2387 Designated Expert(s) may approve registration once they are satisfied 2388 that such a specification will be published. 2390 Registration requests should be sent to the [TBD]@ietf.org mailing 2391 list for review and comment, with an appropriate subject (e.g., 2392 "Request for access token type: example"). [[ Note to RFC-EDITOR: The 2393 name of the mailing list should be determined in consultation with 2394 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2396 Within at most 14 days of the request, the Designated Expert(s) will 2397 either approve or deny the registration request, communicating this 2398 decision to the review list and IANA. Denials should include an 2399 explanation and, if applicable, suggestions as to how to make the 2400 request successful. 2402 Decisions (or lack thereof) made by the Designated Expert can be 2403 first appealed to Application Area Directors (contactable using 2404 app-ads@tools.ietf.org email address or directly by looking up their 2405 email addresses on http://www.iesg.org/ website) and, if the 2406 appellant is not satisfied with the response, to the full IESG (using 2407 the iesg@iesg.org mailing list). 2409 IANA should only accept registry updates from the Designated 2410 Expert(s), and should direct all requests for registration to the 2411 review mailing list. 2413 11.1.1. Registration Template 2414 Type name: 2415 The name requested (e.g., "example"). 2416 Additional Token Endpoint Response Parameters: 2417 Additional response parameters returned together with the 2418 "access_token" parameter. New parameters MUST be separately 2419 registered in the OAuth parameters registry as described by 2420 Section 11.2. 2421 HTTP Authentication Scheme(s): 2422 The HTTP authentication scheme name(s), if any, used to 2423 authenticate protected resources requests using access tokens of 2424 this type. 2425 Change controller: 2426 For standards-track RFCs, state "IETF". For others, give the name 2427 of the responsible party. Other details (e.g., postal address, 2428 e-mail address, home page URI) may also be included. 2429 Specification document(s): 2430 Reference to the document that specifies the parameter, preferably 2431 including a URI that can be used to retrieve a copy of the 2432 document. An indication of the relevant sections may also be 2433 included, but is not required. 2435 11.2. The OAuth Parameters Registry 2437 This specification establishes the OAuth parameters registry. 2439 Additional parameters for inclusion in the authorization endpoint 2440 request, the authorization endpoint response, the token endpoint 2441 request, or the token endpoint response, are registered on the advice 2442 of one or more Designated Experts (appointed by the IESG or their 2443 delegate), with a Specification Required (using terminology from 2444 [RFC5226]). However, to allow for the allocation of values prior to 2445 publication, the Designated Expert(s) may approve registration once 2446 they are satisfied that such a specification will be published. 2448 Registration requests should be sent to the [TBD]@ietf.org mailing 2449 list for review and comment, with an appropriate subject (e.g., 2450 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 2451 the mailing list should be determined in consultation with the IESG 2452 and IANA. Suggested name: oauth-ext-review. ]] 2454 Within at most 14 days of the request, the Designated Expert(s) will 2455 either approve or deny the registration request, communicating this 2456 decision to the review list and IANA. Denials should include an 2457 explanation and, if applicable, suggestions as to how to make the 2458 request successful. 2460 Decisions (or lack thereof) made by the Designated Expert can be 2461 first appealed to Application Area Directors (contactable using 2462 app-ads@tools.ietf.org email address or directly by looking up their 2463 email addresses on http://www.iesg.org/ website) and, if the 2464 appellant is not satisfied with the response, to the full IESG (using 2465 the iesg@iesg.org mailing list). 2467 IANA should only accept registry updates from the Designated 2468 Expert(s), and should direct all requests for registration to the 2469 review mailing list. 2471 11.2.1. Registration Template 2473 Parameter name: 2474 The name requested (e.g., "example"). 2475 Parameter usage location: 2476 The location(s) where parameter can be used. The possible 2477 locations are: authorization request, authorization response, 2478 token request, or token response. 2479 Change controller: 2480 For standards-track RFCs, state "IETF". For others, give the name 2481 of the responsible party. Other details (e.g., postal address, 2482 e-mail address, home page URI) may also be included. 2483 Specification document(s): 2484 Reference to the document that specifies the parameter, preferably 2485 including a URI that can be used to retrieve a copy of the 2486 document. An indication of the relevant sections may also be 2487 included, but is not required. 2489 11.2.2. Initial Registry Contents 2491 The OAuth Parameters Registry's initial contents are: 2493 o Parameter name: client_id 2494 o Parameter usage location: authorization request, token request 2495 o Change controller: IETF 2496 o Specification document(s): [[ this document ]] 2498 o Parameter name: client_secret 2499 o Parameter usage location: token request 2500 o Change controller: IETF 2501 o Specification document(s): [[ this document ]] 2503 o Parameter name: response_type 2504 o Parameter usage location: authorization request 2505 o Change controller: IETF 2506 o Specification document(s): [[ this document ]] 2507 o Parameter name: redirect_uri 2508 o Parameter usage location: authorization request, token request 2509 o Change controller: IETF 2510 o Specification document(s): [[ this document ]] 2512 o Parameter name: scope 2513 o Parameter usage location: authorization request, authorization 2514 response, token request, token response 2515 o Change controller: IETF 2516 o Specification document(s): [[ this document ]] 2518 o Parameter name: state 2519 o Parameter usage location: authorization request, authorization 2520 response 2521 o Change controller: IETF 2522 o Specification document(s): [[ this document ]] 2524 o Parameter name: code 2525 o Parameter usage location: authorization response, token request 2526 o Change controller: IETF 2527 o Specification document(s): [[ this document ]] 2529 o Parameter name: error_description 2530 o Parameter usage location: authorization response, token response 2531 o Change controller: IETF 2532 o Specification document(s): [[ this document ]] 2534 o Parameter name: error_uri 2535 o Parameter usage location: authorization response, token response 2536 o Change controller: IETF 2537 o Specification document(s): [[ this document ]] 2539 o Parameter name: grant_type 2540 o Parameter usage location: token request 2541 o Change controller: IETF 2542 o Specification document(s): [[ this document ]] 2544 o Parameter name: access_token 2545 o Parameter usage location: authorization response, token response 2546 o Change controller: IETF 2547 o Specification document(s): [[ this document ]] 2549 o Parameter name: token_type 2550 o Parameter usage location: authorization response, token response 2551 o Change controller: IETF 2552 o Specification document(s): [[ this document ]] 2553 o Parameter name: expires_in 2554 o Parameter usage location: authorization response, token response 2555 o Change controller: IETF 2556 o Specification document(s): [[ this document ]] 2558 o Parameter name: username 2559 o Parameter usage location: token request 2560 o Change controller: IETF 2561 o Specification document(s): [[ this document ]] 2563 o Parameter name: password 2564 o Parameter usage location: token request 2565 o Change controller: IETF 2566 o Specification document(s): [[ this document ]] 2568 o Parameter name: refresh_token 2569 o Parameter usage location: token request, token response 2570 o Change controller: IETF 2571 o Specification document(s): [[ this document ]] 2573 11.3. The OAuth Authorization Endpoint Response Type Registry 2575 This specification establishes the OAuth authorization endpoint 2576 response type registry. 2578 Additional response type for use with the authorization endpoint are 2579 registered on the advice of one or more Designated Experts (appointed 2580 by the IESG or their delegate), with a Specification Required (using 2581 terminology from [RFC5226]). However, to allow for the allocation of 2582 values prior to publication, the Designated Expert(s) may approve 2583 registration once they are satisfied that such a specification will 2584 be published. 2586 Registration requests should be sent to the [TBD]@ietf.org mailing 2587 list for review and comment, with an appropriate subject (e.g., 2588 "Request for response type: example"). [[ Note to RFC-EDITOR: The 2589 name of the mailing list should be determined in consultation with 2590 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2592 Within at most 14 days of the request, the Designated Expert(s) will 2593 either approve or deny the registration request, communicating this 2594 decision to the review list and IANA. Denials should include an 2595 explanation and, if applicable, suggestions as to how to make the 2596 request successful. 2598 Decisions (or lack thereof) made by the Designated Expert can be 2599 first appealed to Application Area Directors (contactable using 2600 app-ads@tools.ietf.org email address or directly by looking up their 2601 email addresses on http://www.iesg.org/ website) and, if the 2602 appellant is not satisfied with the response, to the full IESG (using 2603 the iesg@iesg.org mailing list). 2605 IANA should only accept registry updates from the Designated 2606 Expert(s), and should direct all requests for registration to the 2607 review mailing list. 2609 11.3.1. Registration Template 2611 Response type name: 2612 The name requested (e.g., "example"). 2613 Change controller: 2614 For standards-track RFCs, state "IETF". For others, give the name 2615 of the responsible party. Other details (e.g., postal address, 2616 e-mail address, home page URI) may also be included. 2617 Specification document(s): 2618 Reference to the document that specifies the type, preferably 2619 including a URI that can be used to retrieve a copy of the 2620 document. An indication of the relevant sections may also be 2621 included, but is not required. 2623 11.3.2. Initial Registry Contents 2625 The OAuth Authorization Endpoint Response Type Registry's initial 2626 contents are: 2628 o Response type name: code 2629 o Change controller: IETF 2630 o Specification document(s): [[ this document ]] 2632 o Response type name: token 2633 o Change controller: IETF 2634 o Specification document(s): [[ this document ]] 2636 11.4. The OAuth Extensions Error Registry 2638 This specification establishes the OAuth extensions error registry. 2640 Additional error codes used together with other protocol extensions 2641 (i.e. extension grant types, access token types, or extension 2642 parameters) are registered on the advice of one or more Designated 2643 Experts (appointed by the IESG or their delegate), with a 2644 Specification Required (using terminology from [RFC5226]). However, 2645 to allow for the allocation of values prior to publication, the 2646 Designated Expert(s) may approve registration once they are satisfied 2647 that such a specification will be published. 2649 Registration requests should be sent to the [TBD]@ietf.org mailing 2650 list for review and comment, with an appropriate subject (e.g., 2651 "Request for error code: example"). [[ Note to RFC-EDITOR: The name 2652 of the mailing list should be determined in consultation with the 2653 IESG and IANA. Suggested name: oauth-ext-review. ]] 2655 Within at most 14 days of the request, the Designated Expert(s) will 2656 either approve or deny the registration request, communicating this 2657 decision to the review list and IANA. Denials should include an 2658 explanation and, if applicable, suggestions as to how to make the 2659 request successful. 2661 Decisions (or lack thereof) made by the Designated Expert can be 2662 first appealed to Application Area Directors (contactable using 2663 app-ads@tools.ietf.org email address or directly by looking up their 2664 email addresses on http://www.iesg.org/ website) and, if the 2665 appellant is not satisfied with the response, to the full IESG (using 2666 the iesg@iesg.org mailing list). 2668 IANA should only accept registry updates from the Designated 2669 Expert(s), and should direct all requests for registration to the 2670 review mailing list. 2672 11.4.1. Registration Template 2674 Error name: 2675 The name requested (e.g., "example"). 2676 Error usage location: 2677 The location(s) where the error can be used. The possible 2678 locations are: authorization code grant error response 2679 (Section 4.1.2.1), implicit grant error response 2680 (Section 4.2.2.1), or token error response (Section 5.2). 2681 Related protocol extension: 2682 The name of the extension grant type, access token type, or 2683 extension parameter, the error code is used in conjunction with. 2684 Change controller: 2685 For standards-track RFCs, state "IETF". For others, give the name 2686 of the responsible party. Other details (e.g., postal address, 2687 e-mail address, home page URI) may also be included. 2688 Specification document(s): 2689 Reference to the document that specifies the error code, 2690 preferably including a URI that can be used to retrieve a copy of 2691 the document. An indication of the relevant sections may also be 2692 included, but is not required. 2694 12. Acknowledgements 2696 The initial OAuth 2.0 protocol specification was edited by David 2697 Recordon, based on two previous publications: the OAuth 1.0 community 2698 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 2699 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 2700 Considerations section was drafted by Torsten Lodderstedt, Mark 2701 McGloin, Phil Hunt, and Anthony Nadalin. 2703 The OAuth 1.0 community specification was edited by Eran Hammer-Lahav 2704 and authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 2705 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 2706 Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, 2707 Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran 2708 Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy 2709 Smith. 2711 The OAuth WRAP specification was edited by Dick Hardt and authored by 2712 Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. 2714 This specification is the work of the OAuth Working Group which 2715 includes dozens of active and dedicated participants. In particular, 2716 the following individuals contributed ideas, feedback, and wording 2717 which shaped and formed the final specification: 2719 Michael Adams, Andrew Arnott, Dirk Balfanz, Aiden Bell, Scott Cantor, 2720 Marcos Caceres, Blaine Cook, Brian Campbell, Brian Eaton, Leah 2721 Culver, Bill de hOra, Brian Eaton, Brian Ellin, Igor Faynberg, George 2722 Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, Brent Goldman, 2723 Kristoffer Gronowski, Justin Hart, Dick Hardt, Craig Heath, Phil 2724 Hunt, Michael B. Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen 2725 Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey 2726 Lucas, Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark 2727 McGloin, Laurence Miao, Chuck Mortimore, Anthony Nadalin, Justin 2728 Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius Scurtescu, 2729 Naitik Shah, Luke Shepard, Vlad Skvortsov, Justin Smith, Niv 2730 Steingarten, Christian Stuebner, Jeremy Suriel, Paul Tarjan, Allen 2731 Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar Woodward. 2733 Appendix A. Editor's Notes 2735 While many people contributed to this specification throughout its 2736 long journey, the editor would like to acknowledge and thank a few 2737 individuals for their outstanding and invaluable efforts leading up 2738 to the publication of this specification. It is these individuals 2739 without whom this work would not have existed or reached its 2740 successful conclusion. 2742 David Recordon for continuously being one of OAuth's most valuable 2743 assets, bringing pragmatism and urgency to the work, and helping 2744 shape it from its very beginning, as well as being one of the best 2745 collaborators I had the pleasure of working with. 2747 Mark Nottingham for introducing OAuth to the IETF and setting the 2748 community on this course. Lisa Dusseault for her support and 2749 guidance as the Application area director. Blaine Cook, Peter Saint- 2750 Andre, and Hannes Tschofenig for their work as working group chairs. 2752 James Manger for his creative ideas and always insightful feedback. 2753 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 2754 Marius Scurtescu, and Luke Shepard for their continued participation 2755 and valuable feedback. 2757 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 2758 support of this work for over three years. 2760 13. References 2762 13.1. Normative References 2764 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2765 Requirement Levels", BCP 14, RFC 2119, March 1997. 2767 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2768 RFC 2246, January 1999. 2770 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2771 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2772 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2774 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2775 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2776 Authentication: Basic and Digest Access Authentication", 2777 RFC 2617, June 1999. 2779 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2781 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2782 Resource Identifier (URI): Generic Syntax", STD 66, 2783 RFC 3986, January 2005. 2785 [RFC4627] Crockford, D., "The application/json Media Type for 2786 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2788 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2789 RFC 4949, August 2007. 2791 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2792 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2793 May 2008. 2795 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2796 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2798 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2799 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2801 [W3C.REC-html401-19991224] 2802 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 2803 Specification", World Wide Web Consortium 2804 Recommendation REC-html401-19991224, December 1999, 2805 . 2807 13.2. Informative References 2809 [I-D.draft-hardt-oauth-01] 2810 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2811 Web Resource Authorization Profiles", January 2010. 2813 [I-D.ietf-oauth-saml2-bearer] 2814 Mortimore, C., "SAML 2.0 Bearer Assertion Grant Type 2815 Profile for OAuth 2.0", draft-ietf-oauth-saml2-bearer-04 2816 (work in progress), May 2011. 2818 [I-D.ietf-oauth-v2-bearer] 2819 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2820 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-06 2821 (work in progress), June 2011. 2823 [I-D.ietf-oauth-v2-http-mac] 2824 Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP 2825 Authentication: MAC Access Authentication", 2826 draft-ietf-oauth-v2-http-mac-00 (work in progress), 2827 May 2011. 2829 [I-D.ietf-oauth-v2-threatmodel] 2830 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2831 Threat Model and Security Considerations", 2832 draft-ietf-oauth-v2-threatmodel-00 (work in progress), 2833 July 2011. 2835 [OASIS.saml-core-2.0-os] 2836 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2837 "Assertions and Protocol for the OASIS Security Assertion 2838 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2839 2.0-os, March 2005. 2841 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2842 April 2010. 2844 Authors' Addresses 2846 Eran Hammer-Lahav (editor) 2847 Yahoo! 2849 Email: eran@hueniverse.com 2850 URI: http://hueniverse.com 2852 David Recordon 2853 Facebook 2855 Email: dr@fb.com 2856 URI: http://www.davidrecordon.com/ 2858 Dick Hardt 2859 Microsoft 2861 Email: dick.hardt@gmail.com 2862 URI: http://dickhardt.org/