idnits 2.17.1 draft-ietf-oauth-v2-29.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 directly say this. It does mention RFC5849 though, so this could be OK. 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 12, 2012) is 4296 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) == Missing Reference: 'TBD' is mentioned on line 2648, but not defined ** 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) ** Obsolete normative reference: RFC 2818 (Obsoleted by RFC 9110) ** 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) ** Obsolete normative reference: RFC 6125 (Obsoleted by RFC 9525) -- Possible downref: Non-RFC (?) normative reference: ref. 'USASCII' == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-13 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-v2-bearer-21 == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-01 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-v2-threatmodel-06 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 9 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group D. Hardt, Ed. 3 Internet-Draft Microsoft 4 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: January 13, 2013 July 12, 2012 8 The OAuth 2.0 Authorization Framework 9 draft-ietf-oauth-v2-29 11 Abstract 13 The OAuth 2.0 authorization framework enables a third-party 14 application to obtain limited access to an HTTP service, either on 15 behalf of a resource owner by orchestrating an approval interaction 16 between the resource owner and the HTTP service, or by allowing the 17 third-party application to obtain access on its own behalf. This 18 specification replaces and obsoletes the OAuth 1.0 protocol described 19 in RFC 5849. 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 January 13, 2013. 38 Copyright Notice 40 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . 7 58 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 59 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 8 60 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 61 1.3.3. Resource Owner Password Credentials . . . . . . . . . 9 62 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 63 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 64 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 65 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 66 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 67 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 68 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 12 69 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 13 70 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 71 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 15 72 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15 73 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 74 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 17 75 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17 76 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 17 77 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 78 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 79 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 18 80 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 21 81 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 82 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 22 83 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 84 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 85 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24 86 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 25 87 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 27 88 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 28 89 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 29 90 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 31 91 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 32 92 4.3. Resource Owner Password Credentials Grant . . . . . . . . 35 93 4.3.1. Authorization Request and Response . . . . . . . . . . 36 94 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 36 95 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 37 97 4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 37 98 4.4.1. Authorization Request and Response . . . . . . . . . . 38 99 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 38 100 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 39 101 4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 39 102 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 40 103 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 40 104 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 41 105 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 43 106 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 44 107 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 44 108 7.2. Error Response . . . . . . . . . . . . . . . . . . . . . 45 109 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46 110 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 46 111 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 46 112 8.3. Defining New Authorization Grant Types . . . . . . . . . 47 113 8.4. Defining New Authorization Endpoint Response Types . . . 47 114 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 47 115 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 48 116 10. Security Considerations . . . . . . . . . . . . . . . . . . . 49 117 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 49 118 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 50 119 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 50 120 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 51 121 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 51 122 10.6. Authorization Code Redirection URI Manipulation . . . . . 52 123 10.7. Resource Owner Password Credentials . . . . . . . . . . . 53 124 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 53 125 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 53 126 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 54 127 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 54 128 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 54 129 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 55 130 10.14. Code Injection and Input Validation . . . . . . . . . . . 56 131 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 56 132 10.16. Misuse of Access Token to Impersonate Resource Owner 133 in Implicit Flow . . . . . . . . . . . . . . . . . . . . 56 134 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 135 11.1. OAuth Access Token Type Registry . . . . . . . . . . . . 57 136 11.1.1. Registration Template . . . . . . . . . . . . . . . . 58 137 11.2. OAuth Parameters Registry . . . . . . . . . . . . . . . . 58 138 11.2.1. Registration Template . . . . . . . . . . . . . . . . 59 139 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 59 140 11.3. OAuth Authorization Endpoint Response Type Registry . . . 61 141 11.3.1. Registration Template . . . . . . . . . . . . . . . . 62 142 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 62 143 11.4. OAuth Extensions Error Registry . . . . . . . . . . . . . 62 144 11.4.1. Registration Template . . . . . . . . . . . . . . . . 63 146 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 147 12.1. Normative References . . . . . . . . . . . . . . . . . . 64 148 12.2. Informative References . . . . . . . . . . . . . . . . . 65 149 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 66 150 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 66 151 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 66 152 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 66 153 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 67 154 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 67 155 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 67 156 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 67 157 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 67 158 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 67 159 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 68 160 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 68 161 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 68 162 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 68 163 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 68 164 A.15. "username" Syntax . . . . . . . . . . . . . . . . . . . . 68 165 A.16. "password" Syntax . . . . . . . . . . . . . . . . . . . . 69 166 A.17. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 69 167 A.18. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 69 168 Appendix B. Use of application/x-www-form-urlencoded Media 169 Type . . . . . . . . . . . . . . . . . . . . . . . . 69 170 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 70 171 Appendix D. Document History . . . . . . . . . . . . . . . . . . 71 172 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 72 174 1. Introduction 176 In the traditional client-server authentication model, the client 177 requests an access restricted resource (protected resource) on the 178 server by authenticating with the server using the resource owner's 179 credentials. In order to provide third-party applications access to 180 restricted resources, the resource owner shares its credentials with 181 the third-party. This creates several problems and limitations: 183 o Third-party applications are required to store the resource 184 owner's credentials for future use, typically a password in clear- 185 text. 186 o Servers are required to support password authentication, despite 187 the security weaknesses inherent in passwords. 188 o Third-party applications gain overly broad access to the resource 189 owner's protected resources, leaving resource owners without any 190 ability to restrict duration or access to a limited subset of 191 resources. 192 o Resource owners cannot revoke access to an individual third-party 193 without revoking access to all third-parties, and must do so by 194 changing their password. 195 o Compromise of any third-party application results in compromise of 196 the end-user's password and all of the data protected by that 197 password. 199 OAuth addresses these issues by introducing an authorization layer 200 and separating the role of the client from that of the resource 201 owner. In OAuth, the client requests access to resources controlled 202 by the resource owner and hosted by the resource server, and is 203 issued a different set of credentials than those of the resource 204 owner. 206 Instead of using the resource owner's credentials to access protected 207 resources, the client obtains an access token - a string denoting a 208 specific scope, lifetime, and other access attributes. Access tokens 209 are issued to third-party clients by an authorization server with the 210 approval of the resource owner. The client uses the access token to 211 access the protected resources hosted by the resource server. 213 For example, an end-user (resource owner) can grant a printing 214 service (client) access to her protected photos stored at a photo 215 sharing service (resource server), without sharing her username and 216 password with the printing service. Instead, she authenticates 217 directly with a server trusted by the photo sharing service 218 (authorization server), which issues the printing service delegation- 219 specific credentials (access token). 221 This specification is designed for use with HTTP ([RFC2616]). The 222 use of OAuth over any other protocol than HTTP is out of scope. 224 The OAuth 1.0 protocol ([RFC5849]), published as an informational 225 document, was the result of a small ad-hoc community effort. This 226 standards-track specification builds on the OAuth 1.0 deployment 227 experience, as well as additional use cases and extensibility 228 requirements gathered from the wider IETF community. The OAuth 2.0 229 protocol is not backward compatible with OAuth 1.0. The two versions 230 may co-exist on the network and implementations may choose to support 231 both. However, it is the intention of this specification that new 232 implementation support OAuth 2.0 as specified in this document, and 233 that OAuth 1.0 is used only to support existing deployments. The 234 OAuth 2.0 protocol shares very few implementation details with the 235 OAuth 1.0 protocol. Implementers familiar with OAuth 1.0 should 236 approach this document without any assumptions as to its structure 237 and details. 239 1.1. Roles 241 OAuth defines four roles: 243 resource owner 244 An entity capable of granting access to a protected resource. 245 When the resource owner is a person, it is referred to as an end- 246 user. 247 resource server 248 The server hosting the protected resources, capable of accepting 249 and responding to protected resource requests using access tokens. 250 client 251 An application making protected resource requests on behalf of the 252 resource owner and with its authorization. The term client does 253 not imply any particular implementation characteristics (e.g. 254 whether the application executes on a server, a desktop, or other 255 devices). 256 authorization server 257 The server issuing access tokens to the client after successfully 258 authenticating the resource owner and obtaining authorization. 260 The interaction between the authorization server and resource server 261 is beyond the scope of this specification. The authorization server 262 may be the same server as the resource server or a separate entity. 263 A single authorization server may issue access tokens accepted by 264 multiple resource servers. 266 1.2. Protocol Flow 268 +--------+ +---------------+ 269 | |--(A)- Authorization Request ->| Resource | 270 | | | Owner | 271 | |<-(B)-- Authorization Grant ---| | 272 | | +---------------+ 273 | | 274 | | +---------------+ 275 | |--(C)-- Authorization Grant -->| Authorization | 276 | Client | | Server | 277 | |<-(D)----- Access Token -------| | 278 | | +---------------+ 279 | | 280 | | +---------------+ 281 | |--(E)----- Access Token ------>| Resource | 282 | | | Server | 283 | |<-(F)--- Protected Resource ---| | 284 +--------+ +---------------+ 286 Figure 1: Abstract Protocol Flow 288 The abstract OAuth 2.0 flow illustrated in Figure 1 describes the 289 interaction between the four roles and includes the following steps: 291 (A) The client requests authorization from the resource owner. The 292 authorization request can be made directly to the resource owner 293 (as shown), or preferably indirectly via the authorization 294 server as an intermediary. 295 (B) The client receives an authorization grant, which is a 296 credential representing the resource owner's authorization, 297 expressed using one of four grant types defined in this 298 specification or using an extension grant type. The 299 authorization grant type depends on the method used by the 300 client to request authorization and the types supported by the 301 authorization server. 302 (C) The client requests an access token by authenticating with the 303 authorization server and presenting the authorization grant. 304 (D) The authorization server authenticates the client and validates 305 the authorization grant, and if valid issues an access token. 306 (E) The client requests the protected resource from the resource 307 server and authenticates by presenting the access token. 308 (F) The resource server validates the access token, and if valid, 309 serves the request. 311 The preferred method for the client to obtain an authorization grant 312 from the resource owner (depicted in steps (A) and (B)) is to use the 313 authorization server as an intermediary, which is illustrated in 314 Figure 3. 316 1.3. Authorization Grant 318 An authorization grant is a credential representing the resource 319 owner's authorization (to access its protected resources) used by the 320 client to obtain an access token. This specification defines four 321 grant types: authorization code, implicit, resource owner password 322 credentials, and client credentials, as well as an extensibility 323 mechanism for defining additional types. 325 1.3.1. Authorization Code 327 The authorization code is obtained by using an authorization server 328 as an intermediary between the client and resource owner. Instead of 329 requesting authorization directly from the resource owner, the client 330 directs the resource owner to an authorization server (via its user- 331 agent as defined in [RFC2616]), which in turn directs the resource 332 owner back to the client with the authorization code. 334 Before directing the resource owner back to the client with the 335 authorization code, the authorization server authenticates the 336 resource owner and obtains authorization. Because the resource owner 337 only authenticates with the authorization server, the resource 338 owner's credentials are never shared with the client. 340 The authorization code provides a few important security benefits 341 such as the ability to authenticate the client, and the transmission 342 of the access token directly to the client without passing it through 343 the resource owner's user-agent, potentially exposing it to others, 344 including the resource owner. 346 1.3.2. Implicit 348 The implicit grant is a simplified authorization code flow optimized 349 for clients implemented in a browser using a scripting language such 350 as JavaScript. In the implicit flow, instead of issuing the client 351 an authorization code, the client is issued an access token directly 352 (as the result of the resource owner authorization). The grant type 353 is implicit as no intermediate credentials (such as an authorization 354 code) are issued (and later used to obtain an access token). 356 When issuing an access token during the implicit grant flow, the 357 authorization server does not authenticate the client. In some 358 cases, the client identity can be verified via the redirection URI 359 used to deliver the access token to the client. The access token may 360 be exposed to the resource owner or other applications with access to 361 the resource owner's user-agent. 363 Implicit grants improve the responsiveness and efficiency of some 364 clients (such as a client implemented as an in-browser application) 365 since it reduces the number of round trips required to obtain an 366 access token. However, this convenience should be weighed against 367 the security implications of using implicit grants, such as those 368 described in Section 10.3 and Section 10.16, especially when the 369 authorization code grant type is available. 371 1.3.3. Resource Owner Password Credentials 373 The resource owner password credentials (i.e. username and password) 374 can be used directly as an authorization grant to obtain an access 375 token. The credentials should only be used when there is a high 376 degree of trust between the resource owner and the client (e.g. the 377 client is part of the device operating system or a highly privileged 378 application), and when other authorization grant types are not 379 available (such as an authorization code). 381 Even though this grant type requires direct client access to the 382 resource owner credentials, the resource owner credentials are used 383 for a single request and are exchanged for an access token. This 384 grant type can eliminate the need for the client to store the 385 resource owner credentials for future use, by exchanging the 386 credentials with a long-lived access token or refresh token. 388 1.3.4. Client Credentials 390 The client credentials (or other forms of client authentication) can 391 be used as an authorization grant when the authorization scope is 392 limited to the protected resources under the control of the client, 393 or to protected resources previously arranged with the authorization 394 server. Client credentials are used as an authorization grant 395 typically when the client is acting on its own behalf (the client is 396 also the resource owner), or is requesting access to protected 397 resources based on an authorization previously arranged with the 398 authorization server. 400 1.4. Access Token 402 Access tokens are credentials used to access protected resources. An 403 access token is a string representing an authorization issued to the 404 client. The string is usually opaque to the client. Tokens 405 represent specific scopes and durations of access, granted by the 406 resource owner, and enforced by the resource server and authorization 407 server. 409 The token may denote an identifier used to retrieve the authorization 410 information, or self-contain the authorization information in a 411 verifiable manner (i.e. a token string consisting of some data and a 412 signature). Additional authentication credentials, which are beyond 413 the scope of this specification, may be required in order for the 414 client to use a token. 416 The access token provides an abstraction layer, replacing different 417 authorization constructs (e.g. username and password) with a single 418 token understood by the resource server. This abstraction enables 419 issuing access tokens more restrictive than the authorization grant 420 used to obtain them, as well as removing the resource server's need 421 to understand a wide range of authentication methods. 423 Access tokens can have different formats, structures, and methods of 424 utilization (e.g. cryptographic properties) based on the resource 425 server security requirements. Access token attributes and the 426 methods used to access protected resources are beyond the scope of 427 this specification and are defined by companion specifications. 429 1.5. Refresh Token 431 Refresh tokens are credentials used to obtain access tokens. Refresh 432 tokens are issued to the client by the authorization server and are 433 used to obtain a new access token when the current access token 434 becomes invalid or expires, or to obtain additional access tokens 435 with identical or narrower scope (access tokens may have a shorter 436 lifetime and fewer permissions than authorized by the resource 437 owner). Issuing a refresh token is optional at the discretion of the 438 authorization server. If the authorization server issues a refresh 439 token, it is included when issuing an access token (i.e. step (D) in 440 Figure 1). 442 A refresh token is a string representing the authorization granted to 443 the client by the resource owner. The string is usually opaque to 444 the client. The token denotes an identifier used to retrieve the 445 authorization information. Unlike access tokens, refresh tokens are 446 intended for use only with authorization servers and are never sent 447 to resource servers. 449 +--------+ +---------------+ 450 | |--(A)------- Authorization Grant --------->| | 451 | | | | 452 | |<-(B)----------- Access Token -------------| | 453 | | & Refresh Token | | 454 | | | | 455 | | +----------+ | | 456 | |--(C)---- Access Token ---->| | | | 457 | | | | | | 458 | |<-(D)- Protected Resource --| Resource | | Authorization | 459 | Client | | Server | | Server | 460 | |--(E)---- Access Token ---->| | | | 461 | | | | | | 462 | |<-(F)- Invalid Token Error -| | | | 463 | | +----------+ | | 464 | | | | 465 | |--(G)----------- Refresh Token ----------->| | 466 | | | | 467 | |<-(H)----------- Access Token -------------| | 468 +--------+ & Optional Refresh Token +---------------+ 470 Figure 2: Refreshing an Expired Access Token 472 The flow illustrated in Figure 2 includes the following steps: 474 (A) The client requests an access token by authenticating with the 475 authorization server, and presenting an authorization grant. 476 (B) The authorization server authenticates the client and validates 477 the authorization grant, and if valid issues an access token and 478 a refresh token. 479 (C) The client makes a protected resource request to the resource 480 server by presenting the access token. 481 (D) The resource server validates the access token, and if valid, 482 serves the request. 483 (E) Steps (C) and (D) repeat until the access token expires. If the 484 client knows the access token expired, it skips to step (G), 485 otherwise it makes another protected resource request. 486 (F) Since the access token is invalid, the resource server returns 487 an invalid token error. 488 (G) The client requests a new access token by authenticating with 489 the authorization server and presenting the refresh token. The 490 client authentication requirements are based on the client type 491 and on the authorization server policies. 492 (H) The authorization server authenticates the client and validates 493 the refresh token, and if valid issues a new access token (and 494 optionally, a new refresh token). 496 Steps C, D, E, and F are outside the scope of this specification as 497 described in Section 7. 499 1.6. TLS Version 501 Whenever TLS is used by this specification, the appropriate version 502 (or versions) of TLS will vary over time, based on the widespread 503 deployment and known security vulnerabilities. At the time of this 504 writing, TLS version 1.2 [RFC5246] is the most recent version, but 505 has a very limited deployment base and might not be readily available 506 for implementation. TLS version 1.0 [RFC2246] is the most widely 507 deployed version, and will provide the broadest interoperability. 509 Implementations MAY also support additional transport-layer security 510 mechanisms that meet their security requirements. 512 1.7. HTTP Redirections 514 This specification makes extensive use of HTTP redirections, in which 515 the client or the authorization server directs the resource owner's 516 user-agent to another destination. While the examples in this 517 specification show the use of the HTTP 302 status code, any other 518 method available via the user-agent to accomplish this redirection is 519 allowed and is considered to be an implementation detail. 521 1.8. Interoperability 523 OAuth 2.0 provides a rich authorization framework with well-defined 524 security properties. However, as a rich and highly extensible 525 framework with many optional components, on its own, this 526 specification is likely to produce a wide range of non-interoperable 527 implementations. 529 In addition, this specification leaves a few required components 530 partially or fully undefined (e.g. client registration, authorization 531 server capabilities, endpoint discovery). Without these components, 532 clients must be manually and specifically configured against a 533 specific authorization server and resource server in order to 534 interoperate. 536 This framework was designed with the clear expectation that future 537 work will define prescriptive profiles and extensions necessary to 538 achieve full web-scale interoperability. 540 1.9. Notational Conventions 542 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 543 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 544 specification are to be interpreted as described in [RFC2119]. 546 This specification uses the Augmented Backus-Naur Form (ABNF) 547 notation of [RFC5234]. Additionally, the rule URI-Reference is 548 included from Uniform Resource Identifier (URI) [RFC3986]. 550 Certain security-related terms are to be understood in the sense 551 defined in [RFC4949]. These terms include, but are not limited to, 552 "attack", "authentication", "authorization", "certificate", 553 "confidentiality", "credential", "encryption", "identity", "sign", 554 "signature", "trust", "validate", and "verify". 556 Unless otherwise noted, all the protocol parameter names and values 557 are case sensitive. 559 2. Client Registration 561 Before initiating the protocol, the client registers with the 562 authorization server. The means through which the client registers 563 with the authorization server are beyond the scope of this 564 specification, but typically involve end-user interaction with an 565 HTML registration form. 567 Client registration does not require a direct interaction between the 568 client and the authorization server. When supported by the 569 authorization server, registration can rely on other means for 570 establishing trust and obtaining the required client properties (e.g. 571 redirection URI, client type). For example, registration can be 572 accomplished using a self-issued or third-party-issued assertion, or 573 by the authorization server performing client discovery using a 574 trusted channel. 576 When registering a client, the client developer SHALL: 578 o specify the client type as described in Section 2.1, 579 o provide its client redirection URIs as described in Section 3.1.2, 580 and 581 o include any other information required by the authorization server 582 (e.g. application name, website, description, logo image, the 583 acceptance of legal terms). 585 2.1. Client Types 587 OAuth defines two client types, based on their ability to 588 authenticate securely with the authorization server (i.e. ability to 589 maintain the confidentiality of their client credentials): 591 confidential 592 Clients capable of maintaining the confidentiality of their 593 credentials (e.g. client implemented on a secure server with 594 restricted access to the client credentials), or capable of secure 595 client authentication using other means. 596 public 597 Clients incapable of maintaining the confidentiality of their 598 credentials (e.g. clients executing on the device used by the 599 resource owner such as an installed native application or a web 600 browser-based application), and incapable of secure client 601 authentication via any other means. 603 The client type designation is based on the authorization server's 604 definition of secure authentication and its acceptable exposure 605 levels of client credentials. The authorization server SHOULD NOT 606 make assumptions about the client type. 608 A client may be implemented as a distributed set of components, each 609 with a different client type and security context (e.g. a distributed 610 client with both a confidential server-based component and a public 611 browser-based component). If the authorization server does not 612 provide support for such clients, or does not provide guidance with 613 regard to their registration, the client SHOULD register each 614 component as a separate client. 616 This specification has been designed around the following client 617 profiles: 619 web application 620 A web application is a confidential client running on a web 621 server. Resource owners access the client via an HTML user 622 interface rendered in a user-agent on the device used by the 623 resource owner. The client credentials as well as any access 624 token issued to the client are stored on the web server and are 625 not exposed to or accessible by the resource owner. 626 user-agent-based application 627 A user-agent-based application is a public client in which the 628 client code is downloaded from a web server and executes within a 629 user-agent (e.g. web browser) on the device used by the resource 630 owner. Protocol data and credentials are easily accessible (and 631 often visible) to the resource owner. Since such applications 632 reside within the user-agent, they can make seamless use of the 633 user-agent capabilities when requesting authorization. 634 native application 635 A native application is a public client installed and executed on 636 the device used by the resource owner. Protocol data and 637 credentials are accessible to the resource owner. It is assumed 638 that any client authentication credentials included in the 639 application can be extracted. On the other hand, dynamically 640 issued credentials such as access tokens or refresh tokens can 641 receive an acceptable level of protection. At a minimum, these 642 credentials are protected from hostile servers with which the 643 application may interact with. On some platforms these 644 credentials might be protected from other applications residing on 645 the same device. 647 2.2. Client Identifier 649 The authorization server issues the registered client a client 650 identifier - a unique string representing the registration 651 information provided by the client. The client identifier is not a 652 secret; it is exposed to the resource owner, and MUST NOT be used 653 alone for client authentication. The client identifier is unique to 654 the authorization server. 656 The client identifier string size is left undefined by this 657 specification. The client should avoid making assumptions about the 658 identifier size. The authorization server SHOULD document the size 659 of any identifier it issues. 661 2.3. Client Authentication 663 If the client type is confidential, the client and authorization 664 server establish a client authentication method suitable for the 665 security requirements of the authorization server. The authorization 666 server MAY accept any form of client authentication meeting its 667 security requirements. 669 Confidential clients are typically issued (or establish) a set of 670 client credentials used for authenticating with the authorization 671 server (e.g. password, public/private key pair). 673 The authorization server MAY establish a client authentication method 674 with public clients. However, the authorization server MUST NOT rely 675 on public client authentication for the purpose of identifying the 676 client. 678 The client MUST NOT use more than one authentication method in each 679 request. 681 2.3.1. Client Password 683 Clients in possession of a client password MAY use the HTTP Basic 684 authentication scheme as defined in [RFC2617] to authenticate with 685 the authorization server. The client identifier is encoded using the 686 "application/x-www-form-urlencoded" encoding algorithm per Appendix B 687 and the encoded value is used as the username; the client password is 688 encoded using the same algorithm and used as the password. The 689 authorization server MUST support the HTTP Basic authentication 690 scheme for authenticating clients that were issued a client password. 692 For example (with extra line breaks for display purposes only): 694 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 696 Alternatively, the authorization server MAY support including the 697 client credentials in the request body using the following 698 parameters: 700 client_id 701 REQUIRED. The client identifier issued to the client during 702 the registration process described by Section 2.2. 703 client_secret 704 REQUIRED. The client secret. The client MAY omit the 705 parameter if the client secret is an empty string. 707 Including the client credentials in the request body using the two 708 parameters is NOT RECOMMENDED, and SHOULD be limited to clients 709 unable to directly utilize the HTTP Basic authentication scheme (or 710 other password-based HTTP authentication schemes). The parameters 711 can only be transmitted in the request body and MUST NOT be included 712 in the request URI. 714 For example, requesting to refresh an access token (Section 6) using 715 the body parameters (with extra line breaks for display purposes 716 only): 718 POST /token HTTP/1.1 719 Host: server.example.com 720 Content-Type: application/x-www-form-urlencoded 722 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 723 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 725 The authorization server MUST require the use of TLS as described in 726 Section 1.6 when sending requests using password authentication. 728 Since this client authentication method involves a password, the 729 authorization server MUST protect any endpoint utilizing it against 730 brute force attacks. 732 2.3.2. Other Authentication Methods 734 The authorization server MAY support any suitable HTTP authentication 735 scheme matching its security requirements. When using other 736 authentication methods, the authorization server MUST define a 737 mapping between the client identifier (registration record) and 738 authentication scheme. 740 2.4. Unregistered Clients 742 This specification does not exclude the use of unregistered clients. 743 However, the use with such clients is beyond the scope of this 744 specification, and requires additional security analysis and review 745 of its interoperability impact. 747 3. Protocol Endpoints 749 The authorization process utilizes two authorization server endpoints 750 (HTTP resources): 752 o Authorization endpoint - used by the client to obtain 753 authorization from the resource owner via user-agent redirection. 754 o Token endpoint - used by the client to exchange an authorization 755 grant for an access token, typically with client authentication. 757 As well as one client endpoint: 759 o Redirection endpoint - used by the authorization server to return 760 authorization credentials responses to the client via the resource 761 owner user-agent. 763 Not every authorization grant type utilizes both endpoints. 764 Extension grant types MAY define additional endpoints as needed. 766 3.1. Authorization Endpoint 768 The authorization endpoint is used to interact with the resource 769 owner and obtain an authorization grant. The authorization server 770 MUST first verify the identity of the resource owner. The way in 771 which the authorization server authenticates the resource owner (e.g. 772 username and password login, session cookies) is beyond the scope of 773 this specification. 775 The means through which the client obtains the location of the 776 authorization endpoint are beyond the scope of this specification, 777 but the location is typically provided in the service documentation. 779 The endpoint URI MAY include an "application/x-www-form-urlencoded" 780 formatted (per Appendix B) query component ([RFC3986] section 3.4), 781 which MUST be retained when adding additional query parameters. The 782 endpoint URI MUST NOT include a fragment component. 784 Since requests to the authorization endpoint result in user 785 authentication and the transmission of clear-text credentials (in the 786 HTTP response), the authorization server MUST require the use of TLS 787 as described in Section 1.6 when sending requests to the 788 authorization endpoint. 790 The authorization server MUST support the use of the HTTP "GET" 791 method [RFC2616] for the authorization endpoint, and MAY support the 792 use of the "POST" method as well. 794 Parameters sent without a value MUST be treated as if they were 795 omitted from the request. The authorization server MUST ignore 796 unrecognized request parameters. Request and response parameters 797 MUST NOT be included more than once. 799 3.1.1. Response Type 801 The authorization endpoint is used by the authorization code grant 802 type and implicit grant type flows. The client informs the 803 authorization server of the desired grant type using the following 804 parameter: 806 response_type 807 REQUIRED. The value MUST be one of "code" for requesting an 808 authorization code as described by Section 4.1.1, "token" for 809 requesting an access token (implicit grant) as described by 810 Section 4.2.1, or a registered extension value as described by 811 Section 8.4. 813 Extension response types MAY contain a space-delimited (%x20) list of 814 values, where the order of values does not matter (e.g. response type 815 "a b" is the same as "b a"). The meaning of such composite response 816 types is defined by their respective specifications. 818 If an authorization request is missing the "response_type" parameter, 819 or if the response type is not understood, the authorization server 820 MUST return an error response as described in Section 4.1.2.1. 822 3.1.2. Redirection Endpoint 824 After completing its interaction with the resource owner, the 825 authorization server directs the resource owner's user-agent back to 826 the client. The authorization server redirects the user-agent to the 827 client's redirection endpoint previously established with the 828 authorization server during the client registration process or when 829 making the authorization request. 831 The redirection endpoint URI MUST be an absolute URI as defined by 832 [RFC3986] section 4.3. The endpoint URI MAY include an 833 "application/x-www-form-urlencoded" formatted (per Appendix B) query 834 component ([RFC3986] section 3.4), which MUST be retained when adding 835 additional query parameters. The endpoint URI MUST NOT include a 836 fragment component. 838 3.1.2.1. Endpoint Request Confidentiality 840 The redirection endpoint SHOULD require the use of TLS as described 841 in Section 1.6 when the requested response type is "code" or "token", 842 or when the redirection request will result in the transmission of 843 sensitive credentials over an open network. This specification does 844 not mandate the use of TLS because at the time of this writing, 845 requiring clients to deploy TLS is a significant hurdle for many 846 client developers. If TLS is not available, the authorization server 847 SHOULD warn the resource owner about the insecure endpoint prior to 848 redirection (e.g. display a message during the authorization 849 request). 851 Lack of transport-layer security can have a severe impact on the 852 security of the client and the protected resources it is authorized 853 to access. The use of transport-layer security is particularly 854 critical when the authorization process is used as a form of 855 delegated end-user authentication by the client (e.g. third-party 856 sign-in service). 858 3.1.2.2. Registration Requirements 860 The authorization server MUST require the following clients to 861 register their redirection endpoint: 863 o Public clients. 864 o Confidential clients utilizing the implicit grant type. 866 The authorization server SHOULD require all clients to register their 867 redirection endpoint prior to utilizing the authorization endpoint. 869 The authorization server SHOULD require the client to provide the 870 complete redirection URI (the client MAY use the "state" request 871 parameter to achieve per-request customization). If requiring the 872 registration of the complete redirection URI is not possible, the 873 authorization server SHOULD require the registration of the URI 874 scheme, authority, and path (allowing the client to dynamically vary 875 only the query component of the redirection URI when requesting 876 authorization). 878 The authorization server MAY allow the client to register multiple 879 redirection endpoints. 881 Lack of a redirection URI registration requirement can enable an 882 attacker to use the authorization endpoint as open redirector as 883 described in Section 10.15. 885 3.1.2.3. Dynamic Configuration 887 If multiple redirection URIs have been registered, if only part of 888 the redirection URI has been registered, or if no redirection URI has 889 been registered, the client MUST include a redirection URI with the 890 authorization request using the "redirect_uri" request parameter. 892 When a redirection URI is included in an authorization request, the 893 authorization server MUST compare and match the value received 894 against at least one of the registered redirection URIs (or URI 895 components) as defined in [RFC3986] section 6, if any redirection 896 URIs were registered. If the client registration included the full 897 redirection URI, the authorization server MUST compare the two URIs 898 using simple string comparison as defined in [RFC3986] section 6.2.1. 900 3.1.2.4. Invalid Endpoint 902 If an authorization request fails validation due to a missing, 903 invalid, or mismatching redirection URI, the authorization server 904 SHOULD inform the resource owner of the error, and MUST NOT 905 automatically redirect the user-agent to the invalid redirection URI. 907 3.1.2.5. Endpoint Content 909 The redirection request to the client's endpoint typically results in 910 an HTML document response, processed by the user-agent. If the HTML 911 response is served directly as the result of the redirection request, 912 any script included in the HTML document will execute with full 913 access to the redirection URI and the credentials it contains. 915 The client SHOULD NOT include any third-party scripts (e.g. third- 916 party analytics, social plug-ins, ad networks) in the redirection 917 endpoint response. Instead, it SHOULD extract the credentials from 918 the URI and redirect the user-agent again to another endpoint without 919 exposing the credentials (in the URI or elsewhere). If third-party 920 scripts are included, the client MUST ensure that its own scripts 921 (used to extract and remove the credentials from the URI) will 922 execute first. 924 3.2. Token Endpoint 926 The token endpoint is used by the client to obtain an access token by 927 presenting its authorization grant or refresh token. The token 928 endpoint is used with every authorization grant except for the 929 implicit grant type (since an access token is issued directly). 931 The means through which the client obtains the location of the token 932 endpoint are beyond the scope of this specification but is typically 933 provided in the service documentation. 935 The endpoint URI MAY include an "application/x-www-form-urlencoded" 936 formatted (per Appendix B) query component ([RFC3986] section 3.4), 937 which MUST be retained when adding additional query parameters. The 938 endpoint URI MUST NOT include a fragment component. 940 Since requests to the token endpoint result in the transmission of 941 clear-text credentials (in the HTTP request and response), the 942 authorization server MUST require the use of TLS as described in 943 Section 1.6 when sending requests to the token endpoint. 945 The client MUST use the HTTP "POST" method when making access token 946 requests. 948 Parameters sent without a value MUST be treated as if they were 949 omitted from the request. The authorization server MUST ignore 950 unrecognized request parameters. Request and response parameters 951 MUST NOT be included more than once. 953 3.2.1. Client Authentication 955 Confidential clients or other clients issued client credentials MUST 956 authenticate with the authorization server as described in 957 Section 2.3 when making requests to the token endpoint. Client 958 authentication is used for: 960 o Enforcing the binding of refresh tokens and authorization codes to 961 the client they were issued to. Client authentication is critical 962 when an authorization code is transmitted to the redirection 963 endpoint over an insecure channel, or when the redirection URI has 964 not been registered in full. 965 o Recovering from a compromised client by disabling the client or 966 changing its credentials, thus preventing an attacker from abusing 967 stolen refresh tokens. Changing a single set of client 968 credentials is significantly faster than revoking an entire set of 969 refresh tokens. 971 o Implementing authentication management best practices, which 972 require periodic credential rotation. Rotation of an entire set 973 of refresh tokens can be challenging, while rotation of a single 974 set of client credentials is significantly easier. 976 A public client that was not issued a client password MUST use the 977 "client_id" request parameter to identify itself when sending 978 requests to the token endpoint. This allows the authorization server 979 to ensure that the code was issued to the same client. Sending 980 "client_id" prevents the client from inadvertently accepting a code 981 intended for a client with a different "client_id". This protects 982 the client from substitution of the authentication code. (It 983 provides no additional security for the protected resource.) 985 3.3. Access Token Scope 987 The authorization and token endpoints allow the client to specify the 988 scope of the access request using the "scope" request parameter. In 989 turn, the authorization server uses the "scope" response parameter to 990 inform the client of the scope of the access token issued. 992 The value of the scope parameter is expressed as a list of space- 993 delimited, case sensitive strings. The strings are defined by the 994 authorization server. If the value contains multiple space-delimited 995 strings, their order does not matter, and each string adds an 996 additional access range to the requested scope. 998 scope = scope-token *( SP scope-token ) 999 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 1001 The authorization server MAY fully or partially ignore the scope 1002 requested by the client based on the authorization server policy or 1003 the resource owner's instructions. If the issued access token scope 1004 is different from the one requested by the client, the authorization 1005 server MUST include the "scope" response parameter to inform the 1006 client of the actual scope granted. 1008 If the client omits the scope parameter when requesting 1009 authorization, the authorization server MUST either process the 1010 request using a pre-defined default value, or fail the request 1011 indicating an invalid scope. The authorization server SHOULD 1012 document its scope requirements and default value (if defined). 1014 4. Obtaining Authorization 1016 To request an access token, the client obtains authorization from the 1017 resource owner. The authorization is expressed in the form of an 1018 authorization grant, which the client uses to request the access 1019 token. OAuth defines four grant types: authorization code, implicit, 1020 resource owner password credentials, and client credentials. It also 1021 provides an extension mechanism for defining additional grant types. 1023 4.1. Authorization Code Grant 1025 The authorization code grant type is used to obtain both access 1026 tokens and refresh tokens and is optimized for confidential clients. 1027 As a redirection-based flow, the client must be capable of 1028 interacting with the resource owner's user-agent (typically a web 1029 browser) and capable of receiving incoming requests (via redirection) 1030 from the authorization server. 1032 +----------+ 1033 | Resource | 1034 | Owner | 1035 | | 1036 +----------+ 1037 ^ 1038 | 1039 (B) 1040 +----|-----+ Client Identifier +---------------+ 1041 | -+----(A)-- & Redirection URI ---->| | 1042 | User- | | Authorization | 1043 | Agent -+----(B)-- User authenticates --->| Server | 1044 | | | | 1045 | -+----(C)-- Authorization Code ---<| | 1046 +-|----|---+ +---------------+ 1047 | | ^ v 1048 (A) (C) | | 1049 | | | | 1050 ^ v | | 1051 +---------+ | | 1052 | |>---(D)-- Authorization Code ---------' | 1053 | Client | & Redirection URI | 1054 | | | 1055 | |<---(E)----- Access Token -------------------' 1056 +---------+ (w/ Optional Refresh Token) 1058 Note: The lines illustrating steps A, B, and C are broken into two 1059 parts as they pass through the user-agent. 1061 Figure 3: Authorization Code Flow 1063 The flow illustrated in Figure 3 includes the following steps: 1065 (A) The client initiates the flow by directing the resource owner's 1066 user-agent to the authorization endpoint. The client includes 1067 its client identifier, requested scope, local state, and a 1068 redirection URI to which the authorization server will send the 1069 user-agent back once access is granted (or denied). 1070 (B) The authorization server authenticates the resource owner (via 1071 the user-agent) and establishes whether the resource owner 1072 grants or denies the client's access request. 1073 (C) Assuming the resource owner grants access, the authorization 1074 server redirects the user-agent back to the client using the 1075 redirection URI provided earlier (in the request or during 1076 client registration). The redirection URI includes an 1077 authorization code and any local state provided by the client 1078 earlier. 1079 (D) The client requests an access token from the authorization 1080 server's token endpoint by including the authorization code 1081 received in the previous step. When making the request, the 1082 client authenticates with the authorization server. The client 1083 includes the redirection URI used to obtain the authorization 1084 code for verification. 1085 (E) The authorization server authenticates the client, validates the 1086 authorization code, and ensures the redirection URI received 1087 matches the URI used to redirect the client in step (C). If 1088 valid, the authorization server responds back with an access 1089 token and optionally, a refresh token. 1091 4.1.1. Authorization Request 1093 The client constructs the request URI by adding the following 1094 parameters to the query component of the authorization endpoint URI 1095 using the "application/x-www-form-urlencoded" format, per Appendix B: 1097 response_type 1098 REQUIRED. Value MUST be set to "code". 1099 client_id 1100 REQUIRED. The client identifier as described in Section 2.2. 1101 redirect_uri 1102 OPTIONAL. As described in Section 3.1.2. 1103 scope 1104 OPTIONAL. The scope of the access request as described by 1105 Section 3.3. 1106 state 1107 RECOMMENDED. An opaque value used by the client to maintain 1108 state between the request and callback. The authorization 1109 server includes this value when redirecting the user-agent back 1110 to the client. The parameter SHOULD be used for preventing 1111 cross-site request forgery as described in Section 10.12. 1113 The client directs the resource owner to the constructed URI using an 1114 HTTP redirection response, or by other means available to it via the 1115 user-agent. 1117 For example, the client directs the user-agent to make the following 1118 HTTP request using TLS (with extra line breaks for display purposes 1119 only): 1121 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1122 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1123 Host: server.example.com 1125 The authorization server validates the request to ensure all required 1126 parameters are present and valid. If the request is valid, the 1127 authorization server authenticates the resource owner and obtains an 1128 authorization decision (by asking the resource owner or by 1129 establishing approval via other means). 1131 When a decision is established, the authorization server directs the 1132 user-agent to the provided client redirection URI using an HTTP 1133 redirection response, or by other means available to it via the user- 1134 agent. 1136 4.1.2. Authorization Response 1138 If the resource owner grants the access request, the authorization 1139 server issues an authorization code and delivers it to the client by 1140 adding the following parameters to the query component of the 1141 redirection URI using the "application/x-www-form-urlencoded" format, 1142 per Appendix B: 1144 code 1145 REQUIRED. The authorization code generated by the 1146 authorization server. The authorization code MUST expire 1147 shortly after it is issued to mitigate the risk of leaks. A 1148 maximum authorization code lifetime of 10 minutes is 1149 RECOMMENDED. The client MUST NOT use the authorization code 1150 more than once. If an authorization code is used more than 1151 once, the authorization server MUST deny the request and SHOULD 1152 revoke (when possible) all tokens previously issued based on 1153 that authorization code. The authorization code is bound to 1154 the client identifier and redirection URI. 1155 state 1156 REQUIRED if the "state" parameter was present in the client 1157 authorization request. The exact value received from the 1158 client. 1160 For example, the authorization server redirects the user-agent by 1161 sending the following HTTP response: 1163 HTTP/1.1 302 Found 1164 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1165 &state=xyz 1167 The client MUST ignore unrecognized response parameters. The 1168 authorization code string size is left undefined by this 1169 specification. The client should avoid making assumptions about code 1170 value sizes. The authorization server SHOULD document the size of 1171 any value it issues. 1173 4.1.2.1. Error Response 1175 If the request fails due to a missing, invalid, or mismatching 1176 redirection URI, or if the client identifier is missing or invalid, 1177 the authorization server SHOULD inform the resource owner of the 1178 error, and MUST NOT automatically redirect the user-agent to the 1179 invalid redirection URI. 1181 If the resource owner denies the access request or if the request 1182 fails for reasons other than a missing or invalid redirection URI, 1183 the authorization server informs the client by adding the following 1184 parameters to the query component of the redirection URI using the 1185 "application/x-www-form-urlencoded" format, per Appendix B: 1187 error 1188 REQUIRED. A single ASCII [USASCII] error code from the 1189 following: 1190 invalid_request 1191 The request is missing a required parameter, includes an 1192 invalid parameter value, includes a parameter more than 1193 once, or is otherwise malformed. 1194 unauthorized_client 1195 The client is not authorized to request an authorization 1196 code using this method. 1197 access_denied 1198 The resource owner or authorization server denied the 1199 request. 1200 unsupported_response_type 1201 The authorization server does not support obtaining an 1202 authorization code using this method. 1203 invalid_scope 1204 The requested scope is invalid, unknown, or malformed. 1206 server_error 1207 The authorization server encountered an unexpected 1208 condition that prevented it from fulfilling the request. 1209 temporarily_unavailable 1210 The authorization server is currently unable to handle 1211 the request due to a temporary overloading or maintenance 1212 of the server. 1213 Values for the "error" parameter MUST NOT include characters 1214 outside the set %x20-21 / %x23-5B / %x5D-7E. 1215 error_description 1216 OPTIONAL. A human-readable ASCII [USASCII] text providing 1217 additional information, used to assist the client developer in 1218 understanding the error that occurred. 1219 Values for the "error_description" parameter MUST NOT include 1220 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1221 error_uri 1222 OPTIONAL. A URI identifying a human-readable web page with 1223 information about the error, used to provide the client 1224 developer with additional information about the error. 1225 Values for the "error_uri" parameter MUST conform to the URI- 1226 Reference syntax, and thus MUST NOT include characters outside 1227 the set %x21 / %x23-5B / %x5D-7E. 1228 state 1229 REQUIRED if a "state" parameter was present in the client 1230 authorization request. The exact value received from the 1231 client. 1233 For example, the authorization server redirects the user-agent by 1234 sending the following HTTP response: 1236 HTTP/1.1 302 Found 1237 Location: https://client.example.com/cb?error=access_denied&state=xyz 1239 4.1.3. Access Token Request 1241 The client makes a request to the token endpoint by sending the 1242 following parameters using the "application/x-www-form-urlencoded" 1243 format per Appendix B with a character encoding of UTF-8 in the HTTP 1244 request entity-body: 1246 grant_type 1247 REQUIRED. Value MUST be set to "authorization_code". 1248 code 1249 REQUIRED. The authorization code received from the 1250 authorization server. 1252 redirect_uri 1253 REQUIRED, if the "redirect_uri" parameter was included in the 1254 authorization request as described in Section 4.1.1, and their 1255 values MUST be identical. 1257 If the client type is confidential or the client was issued client 1258 credentials (or assigned other authentication requirements), the 1259 client MUST authenticate with the authorization server as described 1260 in Section 3.2.1. 1262 For example, the client makes the following HTTP request using TLS 1263 (with extra line breaks for display purposes only): 1265 POST /token HTTP/1.1 1266 Host: server.example.com 1267 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1268 Content-Type: application/x-www-form-urlencoded 1270 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1271 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1273 The authorization server MUST: 1275 o require client authentication for confidential clients or for any 1276 client that was issued client credentials (or with other 1277 authentication requirements), 1278 o authenticate the client if client authentication is included, 1279 o ensure the authorization code was issued to the authenticated 1280 confidential client or to the public client identified by the 1281 "client_id" in the request, 1282 o verify that the authorization code is valid, and 1283 o ensure that the "redirect_uri" parameter is present if the 1284 "redirect_uri" parameter was included in the initial authorization 1285 request as described in Section 4.1.1, and if included ensure 1286 their values are identical. 1288 4.1.4. Access Token Response 1290 If the access token request is valid and authorized, the 1291 authorization server issues an access token and optional refresh 1292 token as described in Section 5.1. If the request client 1293 authentication failed or is invalid, the authorization server returns 1294 an error response as described in Section 5.2. 1296 An example successful response: 1298 HTTP/1.1 200 OK 1299 Content-Type: application/json;charset=UTF-8 1300 Cache-Control: no-store 1301 Pragma: no-cache 1303 { 1304 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1305 "token_type":"example", 1306 "expires_in":3600, 1307 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1308 "example_parameter":"example_value" 1309 } 1311 4.2. Implicit Grant 1313 The implicit grant type is used to obtain access tokens (it does not 1314 support the issuance of refresh tokens) and is optimized for public 1315 clients known to operate a particular redirection URI. These clients 1316 are typically implemented in a browser using a scripting language 1317 such as JavaScript. 1319 As a redirection-based flow, the client must be capable of 1320 interacting with the resource owner's user-agent (typically a web 1321 browser) and capable of receiving incoming requests (via redirection) 1322 from the authorization server. 1324 Unlike the authorization code grant type in which the client makes 1325 separate requests for authorization and access token, the client 1326 receives the access token as the result of the authorization request. 1328 The implicit grant type does not include client authentication, and 1329 relies on the presence of the resource owner and the registration of 1330 the redirection URI. Because the access token is encoded into the 1331 redirection URI, it may be exposed to the resource owner and other 1332 applications residing on the same device. 1334 +----------+ 1335 | Resource | 1336 | Owner | 1337 | | 1338 +----------+ 1339 ^ 1340 | 1341 (B) 1342 +----|-----+ Client Identifier +---------------+ 1343 | -+----(A)-- & Redirection URI --->| | 1344 | User- | | Authorization | 1345 | Agent -|----(B)-- User authenticates -->| Server | 1346 | | | | 1347 | |<---(C)--- Redirection URI ----<| | 1348 | | with Access Token +---------------+ 1349 | | in Fragment 1350 | | +---------------+ 1351 | |----(D)--- Redirection URI ---->| Web-Hosted | 1352 | | without Fragment | Client | 1353 | | | Resource | 1354 | (F) |<---(E)------- Script ---------<| | 1355 | | +---------------+ 1356 +-|--------+ 1357 | | 1358 (A) (G) Access Token 1359 | | 1360 ^ v 1361 +---------+ 1362 | | 1363 | Client | 1364 | | 1365 +---------+ 1367 Note: The lines illustrating steps A and B are broken into two parts 1368 as they pass through the user-agent. 1370 Figure 4: Implicit Grant Flow 1372 The flow illustrated in Figure 4 includes the following steps: 1374 (A) The client initiates the flow by directing the resource owner's 1375 user-agent to the authorization endpoint. The client includes 1376 its client identifier, requested scope, local state, and a 1377 redirection URI to which the authorization server will send the 1378 user-agent back once access is granted (or denied). 1380 (B) The authorization server authenticates the resource owner (via 1381 the user-agent) and establishes whether the resource owner 1382 grants or denies the client's access request. 1383 (C) Assuming the resource owner grants access, the authorization 1384 server redirects the user-agent back to the client using the 1385 redirection URI provided earlier. The redirection URI includes 1386 the access token in the URI fragment. 1387 (D) The user-agent follows the redirection instructions by making a 1388 request to the web-hosted client resource (which does not 1389 include the fragment per [RFC2616]). The user-agent retains the 1390 fragment information locally. 1391 (E) The web-hosted client resource returns a web page (typically an 1392 HTML document with an embedded script) capable of accessing the 1393 full redirection URI including the fragment retained by the 1394 user-agent, and extracting the access token (and other 1395 parameters) contained in the fragment. 1396 (F) The user-agent executes the script provided by the web-hosted 1397 client resource locally, which extracts the access token and 1398 passes it to the client. 1400 See Section 1.3.2 and Section 9 for background on using the implicit 1401 grant. See Section 10.3 and Section 10.16 for important security 1402 considerations when using the implicit grant. 1404 4.2.1. Authorization Request 1406 The client constructs the request URI by adding the following 1407 parameters to the query component of the authorization endpoint URI 1408 using the "application/x-www-form-urlencoded" format, per Appendix B: 1410 response_type 1411 REQUIRED. Value MUST be set to "token". 1412 client_id 1413 REQUIRED. The client identifier as described in Section 2.2. 1414 redirect_uri 1415 OPTIONAL. As described in Section 3.1.2. 1416 scope 1417 OPTIONAL. The scope of the access request as described by 1418 Section 3.3. 1419 state 1420 RECOMMENDED. An opaque value used by the client to maintain 1421 state between the request and callback. The authorization 1422 server includes this value when redirecting the user-agent back 1423 to the client. The parameter SHOULD be used for preventing 1424 cross-site request forgery as described in Section 10.12. 1426 The client directs the resource owner to the constructed URI using an 1427 HTTP redirection response, or by other means available to it via the 1428 user-agent. 1430 For example, the client directs the user-agent to make the following 1431 HTTP request using TLS (with extra line breaks for display purposes 1432 only): 1434 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1435 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1436 Host: server.example.com 1438 The authorization server validates the request to ensure all required 1439 parameters are present and valid. The authorization server MUST 1440 verify that the redirection URI to which it will redirect the access 1441 token matches a redirection URI registered by the client as described 1442 in Section 3.1.2. 1444 If the request is valid, the authorization server authenticates the 1445 resource owner and obtains an authorization decision (by asking the 1446 resource owner or by establishing approval via other means). 1448 When a decision is established, the authorization server directs the 1449 user-agent to the provided client redirection URI using an HTTP 1450 redirection response, or by other means available to it via the user- 1451 agent. 1453 4.2.2. Access Token Response 1455 If the resource owner grants the access request, the authorization 1456 server issues an access token and delivers it to the client by adding 1457 the following parameters to the fragment component of the redirection 1458 URI using the "application/x-www-form-urlencoded" format, per 1459 Appendix B: 1461 access_token 1462 REQUIRED. The access token issued by the authorization server. 1463 token_type 1464 REQUIRED. The type of the token issued as described in 1465 Section 7.1. Value is case insensitive. 1466 expires_in 1467 RECOMMENDED. The lifetime in seconds of the access token. For 1468 example, the value "3600" denotes that the access token will 1469 expire in one hour from the time the response was generated. 1470 If omitted, the authorization server SHOULD provide the 1471 expiration time via other means or document the default value. 1473 scope 1474 OPTIONAL, if identical to the scope requested by the client, 1475 otherwise REQUIRED. The scope of the access token as described 1476 by Section 3.3. 1477 state 1478 REQUIRED if the "state" parameter was present in the client 1479 authorization request. The exact value received from the 1480 client. 1482 The authorization server MUST NOT issue a refresh token. 1484 For example, the authorization server redirects the user-agent by 1485 sending the following HTTP response (with extra line breaks for 1486 display purposes only): 1488 HTTP/1.1 302 Found 1489 Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1490 &state=xyz&token_type=example&expires_in=3600 1492 Developers should note that some user-agents do not support the 1493 inclusion of a fragment component in the HTTP "Location" response 1494 header field. Such clients will require using other methods for 1495 redirecting the client than a 3xx redirection response. For example, 1496 returning an HTML page that includes a 'continue' button with an 1497 action linked to the redirection URI. 1499 The client MUST ignore unrecognized response parameters. The access 1500 token string size is left undefined by this specification. The 1501 client should avoid making assumptions about value sizes. The 1502 authorization server SHOULD document the size of any value it issues. 1504 4.2.2.1. Error Response 1506 If the request fails due to a missing, invalid, or mismatching 1507 redirection URI, or if the client identifier is missing or invalid, 1508 the authorization server SHOULD inform the resource owner of the 1509 error, and MUST NOT automatically redirect the user-agent to the 1510 invalid redirection URI. 1512 If the resource owner denies the access request or if the request 1513 fails for reasons other than a missing or invalid redirection URI, 1514 the authorization server informs the client by adding the following 1515 parameters to the fragment component of the redirection URI using the 1516 "application/x-www-form-urlencoded" format, per Appendix B: 1518 error 1519 REQUIRED. A single ASCII [USASCII] error code from the 1520 following: 1521 invalid_request 1522 The request is missing a required parameter, includes an 1523 invalid parameter value, includes a parameter more than 1524 once, or is otherwise malformed. 1525 unauthorized_client 1526 The client is not authorized to request an access token 1527 using this method. 1528 access_denied 1529 The resource owner or authorization server denied the 1530 request. 1531 unsupported_response_type 1532 The authorization server does not support obtaining an 1533 access token using this method. 1534 invalid_scope 1535 The requested scope is invalid, unknown, or malformed. 1536 server_error 1537 The authorization server encountered an unexpected 1538 condition that prevented it from fulfilling the request. 1539 temporarily_unavailable 1540 The authorization server is currently unable to handle 1541 the request due to a temporary overloading or maintenance 1542 of the server. 1543 Values for the "error" parameter MUST NOT include characters 1544 outside the set %x20-21 / %x23-5B / %x5D-7E. 1545 error_description 1546 OPTIONAL. A human-readable ASCII [USASCII] text providing 1547 additional information, used to assist the client developer in 1548 understanding the error that occurred. 1549 Values for the "error_description" parameter MUST NOT include 1550 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1551 error_uri 1552 OPTIONAL. A URI identifying a human-readable web page with 1553 information about the error, used to provide the client 1554 developer with additional information about the error. 1555 Values for the "error_uri" parameter MUST conform to the URI- 1556 Reference syntax, and thus MUST NOT include characters outside 1557 the set %x21 / %x23-5B / %x5D-7E. 1558 state 1559 REQUIRED if a "state" parameter was present in the client 1560 authorization request. The exact value received from the 1561 client. 1563 For example, the authorization server redirects the user-agent by 1564 sending the following HTTP response: 1566 HTTP/1.1 302 Found 1567 Location: https://client.example.com/cb#error=access_denied&state=xyz 1569 4.3. Resource Owner Password Credentials Grant 1571 The resource owner password credentials grant type is suitable in 1572 cases where the resource owner has a trust relationship with the 1573 client, such as the device operating system or a highly privileged 1574 application. The authorization server should take special care when 1575 enabling this grant type, and only allow it when other flows are not 1576 viable. 1578 The grant type is suitable for clients capable of obtaining the 1579 resource owner's credentials (username and password, typically using 1580 an interactive form). It is also used to migrate existing clients 1581 using direct authentication schemes such as HTTP Basic or Digest 1582 authentication to OAuth by converting the stored credentials to an 1583 access token. 1585 +----------+ 1586 | Resource | 1587 | Owner | 1588 | | 1589 +----------+ 1590 v 1591 | Resource Owner 1592 (A) Password Credentials 1593 | 1594 v 1595 +---------+ +---------------+ 1596 | |>--(B)---- Resource Owner ------->| | 1597 | | Password Credentials | Authorization | 1598 | Client | | Server | 1599 | |<--(C)---- Access Token ---------<| | 1600 | | (w/ Optional Refresh Token) | | 1601 +---------+ +---------------+ 1603 Figure 5: Resource Owner Password Credentials Flow 1605 The flow illustrated in Figure 5 includes the following steps: 1607 (A) The resource owner provides the client with its username and 1608 password. 1609 (B) The client requests an access token from the authorization 1610 server's token endpoint by including the credentials received 1611 from the resource owner. When making the request, the client 1612 authenticates with the authorization server. 1613 (C) The authorization server authenticates the client and validates 1614 the resource owner credentials, and if valid issues an access 1615 token. 1617 4.3.1. Authorization Request and Response 1619 The method through which the client obtains the resource owner 1620 credentials is beyond the scope of this specification. The client 1621 MUST discard the credentials once an access token has been obtained. 1623 4.3.2. Access Token Request 1625 The client makes a request to the token endpoint by adding the 1626 following parameters using the "application/x-www-form-urlencoded" 1627 format per Appendix B with a character encoding of UTF-8 in the HTTP 1628 request entity-body: 1630 grant_type 1631 REQUIRED. Value MUST be set to "password". 1632 username 1633 REQUIRED. The resource owner username. 1634 password 1635 REQUIRED. The resource owner password. 1636 scope 1637 OPTIONAL. The scope of the access request as described by 1638 Section 3.3. 1640 If the client type is confidential or the client was issued client 1641 credentials (or assigned other authentication requirements), the 1642 client MUST authenticate with the authorization server as described 1643 in Section 3.2.1. 1645 For example, the client makes the following HTTP request using 1646 transport-layer security (with extra line breaks for display purposes 1647 only): 1649 POST /token HTTP/1.1 1650 Host: server.example.com 1651 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1652 Content-Type: application/x-www-form-urlencoded 1654 grant_type=password&username=johndoe&password=A3ddj3w 1656 The authorization server MUST: 1658 o require client authentication for confidential clients or for any 1659 client that was issued client credentials (or with other 1660 authentication requirements), 1661 o authenticate the client if client authentication is included, and 1662 o validate the resource owner password credentials using its 1663 existing password validation algorithm. 1665 Since this access token request utilizes the resource owner's 1666 password, the authorization server MUST protect the endpoint against 1667 brute force attacks (e.g. using rate-limitation or generating 1668 alerts). 1670 4.3.3. Access Token Response 1672 If the access token request is valid and authorized, the 1673 authorization server issues an access token and optional refresh 1674 token as described in Section 5.1. If the request failed client 1675 authentication or is invalid, the authorization server returns an 1676 error response as described in Section 5.2. 1678 An example successful response: 1680 HTTP/1.1 200 OK 1681 Content-Type: application/json;charset=UTF-8 1682 Cache-Control: no-store 1683 Pragma: no-cache 1685 { 1686 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1687 "token_type":"example", 1688 "expires_in":3600, 1689 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1690 "example_parameter":"example_value" 1691 } 1693 4.4. Client Credentials Grant 1695 The client can request an access token using only its client 1696 credentials (or other supported means of authentication) when the 1697 client is requesting access to the protected resources under its 1698 control, or those of another resource owner that have been previously 1699 arranged with the authorization server (the method of which is beyond 1700 the scope of this specification). 1702 The client credentials grant type MUST only be used by confidential 1703 clients. 1705 +---------+ +---------------+ 1706 | | | | 1707 | |>--(A)- Client Authentication --->| Authorization | 1708 | Client | | Server | 1709 | |<--(B)---- Access Token ---------<| | 1710 | | | | 1711 +---------+ +---------------+ 1713 Figure 6: Client Credentials Flow 1715 The flow illustrated in Figure 6 includes the following steps: 1717 (A) The client authenticates with the authorization server and 1718 requests an access token from the token endpoint. 1719 (B) The authorization server authenticates the client, and if valid 1720 issues an access token. 1722 4.4.1. Authorization Request and Response 1724 Since the client authentication is used as the authorization grant, 1725 no additional authorization request is needed. 1727 4.4.2. Access Token Request 1729 The client makes a request to the token endpoint by adding the 1730 following parameters using the "application/x-www-form-urlencoded" 1731 format per Appendix B with a character encoding of UTF-8 in the HTTP 1732 request entity-body: 1734 grant_type 1735 REQUIRED. Value MUST be set to "client_credentials". 1736 scope 1737 OPTIONAL. The scope of the access request as described by 1738 Section 3.3. 1740 The client MUST authenticate with the authorization server as 1741 described in Section 3.2.1. 1743 For example, the client makes the following HTTP request using 1744 transport-layer security (with extra line breaks for display purposes 1745 only): 1747 POST /token HTTP/1.1 1748 Host: server.example.com 1749 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1750 Content-Type: application/x-www-form-urlencoded 1752 grant_type=client_credentials 1754 The authorization server MUST authenticate the client. 1756 4.4.3. Access Token Response 1758 If the access token request is valid and authorized, the 1759 authorization server issues an access token as described in 1760 Section 5.1. A refresh token SHOULD NOT be included. If the request 1761 failed client authentication or is invalid, the authorization server 1762 returns an error response as described in Section 5.2. 1764 An example successful response: 1766 HTTP/1.1 200 OK 1767 Content-Type: application/json;charset=UTF-8 1768 Cache-Control: no-store 1769 Pragma: no-cache 1771 { 1772 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1773 "token_type":"example", 1774 "expires_in":3600, 1775 "example_parameter":"example_value" 1776 } 1778 4.5. Extension Grants 1780 The client uses an extension grant type by specifying the grant type 1781 using an absolute URI (defined by the authorization server) as the 1782 value of the "grant_type" parameter of the token endpoint, and by 1783 adding any additional parameters necessary. 1785 For example, to request an access token using a SAML 2.0 assertion 1786 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1787 could make the following HTTP request using TLS (with extra line 1788 breaks for display purposes only): 1790 POST /token HTTP/1.1 1791 Host: server.example.com 1792 Content-Type: application/x-www-form-urlencoded 1794 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1795 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1796 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1798 If the access token request is valid and authorized, the 1799 authorization server issues an access token and optional refresh 1800 token as described in Section 5.1. If the request failed client 1801 authentication or is invalid, the authorization server returns an 1802 error response as described in Section 5.2. 1804 5. Issuing an Access Token 1806 If the access token request is valid and authorized, the 1807 authorization server issues an access token and optional refresh 1808 token as described in Section 5.1. If the request failed client 1809 authentication or is invalid, the authorization server returns an 1810 error response as described in Section 5.2. 1812 5.1. Successful Response 1814 The authorization server issues an access token and optional refresh 1815 token, and constructs the response by adding the following parameters 1816 to the entity body of the HTTP response with a 200 (OK) status code: 1818 access_token 1819 REQUIRED. The access token issued by the authorization server. 1820 token_type 1821 REQUIRED. The type of the token issued as described in 1822 Section 7.1. Value is case insensitive. 1823 expires_in 1824 RECOMMENDED. The lifetime in seconds of the access token. For 1825 example, the value "3600" denotes that the access token will 1826 expire in one hour from the time the response was generated. 1827 If omitted, the authorization server SHOULD provide the 1828 expiration time via other means or document the default value. 1829 refresh_token 1830 OPTIONAL. The refresh token, which can be used to obtain new 1831 access tokens using the same authorization grant as described 1832 in Section 6. 1833 scope 1834 OPTIONAL, if identical to the scope requested by the client, 1835 otherwise REQUIRED. The scope of the access token as described 1836 by Section 3.3. 1838 The parameters are included in the entity body of the HTTP response 1839 using the "application/json" media type as defined by [RFC4627]. The 1840 parameters are serialized into a JSON structure by adding each 1841 parameter at the highest structure level. Parameter names and string 1842 values are included as JSON strings. Numerical values are included 1843 as JSON numbers. The order of parameters does not matter and can 1844 vary. 1846 The authorization server MUST include the HTTP "Cache-Control" 1847 response header field [RFC2616] with a value of "no-store" in any 1848 response containing tokens, credentials, or other sensitive 1849 information, as well as the "Pragma" response header field [RFC2616] 1850 with a value of "no-cache". 1852 For example: 1854 HTTP/1.1 200 OK 1855 Content-Type: application/json;charset=UTF-8 1856 Cache-Control: no-store 1857 Pragma: no-cache 1859 { 1860 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1861 "token_type":"example", 1862 "expires_in":3600, 1863 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1864 "example_parameter":"example_value" 1865 } 1867 The client MUST ignore unrecognized value names in the response. The 1868 sizes of tokens and other values received from the authorization 1869 server are left undefined. The client should avoid making 1870 assumptions about value sizes. The authorization server SHOULD 1871 document the size of any value it issues. 1873 5.2. Error Response 1875 The authorization server responds with an HTTP 400 (Bad Request) 1876 status code (unless specified otherwise) and includes the following 1877 parameters with the response: 1879 error 1880 REQUIRED. A single ASCII [USASCII] error code from the 1881 following: 1882 invalid_request 1883 The request is missing a required parameter, includes an 1884 unsupported parameter value (other than grant type), 1885 repeats a parameter, includes multiple credentials, 1886 utilizes more than one mechanism for authenticating the 1887 client, or is otherwise malformed. 1888 invalid_client 1889 Client authentication failed (e.g. unknown client, no 1890 client authentication included, or unsupported 1891 authentication method). The authorization server MAY 1892 return an HTTP 401 (Unauthorized) status code to indicate 1893 which HTTP authentication schemes are supported. If the 1894 client attempted to authenticate via the "Authorization" 1895 request header field, the authorization server MUST 1896 respond with an HTTP 401 (Unauthorized) status code, and 1897 include the "WWW-Authenticate" response header field 1898 matching the authentication scheme used by the client. 1899 invalid_grant 1900 The provided authorization grant (e.g. authorization 1901 code, resource owner credentials) or refresh token is 1902 invalid, expired, revoked, does not match the redirection 1903 URI used in the authorization request, or was issued to 1904 another client. 1905 unauthorized_client 1906 The authenticated client is not authorized to use this 1907 authorization grant type. 1908 unsupported_grant_type 1909 The authorization grant type is not supported by the 1910 authorization server. 1911 invalid_scope 1912 The requested scope is invalid, unknown, malformed, or 1913 exceeds the scope granted by the resource owner. 1914 Values for the "error" parameter MUST NOT include characters 1915 outside the set %x20-21 / %x23-5B / %x5D-7E. 1916 error_description 1917 OPTIONAL. A human-readable ASCII [USASCII] text providing 1918 additional information, used to assist the client developer in 1919 understanding the error that occurred. 1920 Values for the "error_description" parameter MUST NOT include 1921 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1922 error_uri 1923 OPTIONAL. A URI identifying a human-readable web page with 1924 information about the error, used to provide the client 1925 developer with additional information about the error. 1926 Values for the "error_uri" parameter MUST conform to the URI- 1927 Reference syntax, and thus MUST NOT include characters outside 1928 the set %x21 / %x23-5B / %x5D-7E. 1930 The parameters are included in the entity body of the HTTP response 1931 using the "application/json" media type as defined by [RFC4627]. The 1932 parameters are serialized into a JSON structure by adding each 1933 parameter at the highest structure level. Parameter names and string 1934 values are included as JSON strings. Numerical values are included 1935 as JSON numbers. The order of parameters does not matter and can 1936 vary. 1938 For example: 1940 HTTP/1.1 400 Bad Request 1941 Content-Type: application/json;charset=UTF-8 1942 Cache-Control: no-store 1943 Pragma: no-cache 1945 { 1946 "error":"invalid_request" 1947 } 1949 6. Refreshing an Access Token 1951 If the authorization server issued a refresh token to the client, the 1952 client makes a refresh request to the token endpoint by adding the 1953 following parameters using the "application/x-www-form-urlencoded" 1954 format per Appendix B with a character encoding of UTF-8 in the HTTP 1955 request entity-body: 1957 grant_type 1958 REQUIRED. Value MUST be set to "refresh_token". 1959 refresh_token 1960 REQUIRED. The refresh token issued to the client. 1961 scope 1962 OPTIONAL. The scope of the access request as described by 1963 Section 3.3. The requested scope MUST NOT include any scope 1964 not originally granted by the resource owner, and if omitted is 1965 treated as equal to the scope originally granted by the 1966 resource owner. 1968 Because refresh tokens are typically long-lasting credentials used to 1969 request additional access tokens, the refresh token is bound to the 1970 client to which it was issued. If the client type is confidential or 1971 the client was issued client credentials (or assigned other 1972 authentication requirements), the client MUST authenticate with the 1973 authorization server as described in Section 3.2.1. 1975 For example, the client makes the following HTTP request using 1976 transport-layer security (with extra line breaks for display purposes 1977 only): 1979 POST /token HTTP/1.1 1980 Host: server.example.com 1981 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1982 Content-Type: application/x-www-form-urlencoded 1984 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1986 The authorization server MUST: 1988 o require client authentication for confidential clients or for any 1989 client that was issued client credentials (or with other 1990 authentication requirements), 1991 o authenticate the client if client authentication is included and 1992 ensure the refresh token was issued to the authenticated client, 1993 and 1994 o validate the refresh token. 1996 If valid and authorized, the authorization server issues an access 1997 token as described in Section 5.1. If the request failed 1998 verification or is invalid, the authorization server returns an error 1999 response as described in Section 5.2. 2001 The authorization server MAY issue a new refresh token, in which case 2002 the client MUST discard the old refresh token and replace it with the 2003 new refresh token. The authorization server MAY revoke the old 2004 refresh token after issuing a new refresh token to the client. If a 2005 new refresh token is issued, the refresh token scope MUST be 2006 identical to that of the refresh token included by the client in the 2007 request. 2009 7. Accessing Protected Resources 2011 The client accesses protected resources by presenting the access 2012 token to the resource server. The resource server MUST validate the 2013 access token and ensure it has not expired and that its scope covers 2014 the requested resource. The methods used by the resource server to 2015 validate the access token (as well as any error responses) are beyond 2016 the scope of this specification, but generally involve an interaction 2017 or coordination between the resource server and the authorization 2018 server. 2020 The method in which the client utilizes the access token to 2021 authenticate with the resource server depends on the type of access 2022 token issued by the authorization server. Typically, it involves 2023 using the HTTP "Authorization" request header field [RFC2617] with an 2024 authentication scheme defined by the access token type specification. 2026 7.1. Access Token Types 2028 The access token type provides the client with the information 2029 required to successfully utilize the access token to make a protected 2030 resource request (along with type-specific attributes). The client 2031 MUST NOT use an access token if it does not understand the token 2032 type. 2034 For example, the "bearer" token type defined in 2035 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 2036 token string in the request: 2038 GET /resource/1 HTTP/1.1 2039 Host: example.com 2040 Authorization: Bearer mF_9.B5f-4.1JqM 2042 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 2043 utilized by issuing a MAC key together with the access token that is 2044 used to sign certain components of the HTTP requests: 2046 GET /resource/1 HTTP/1.1 2047 Host: example.com 2048 Authorization: MAC id="h480djs93hd8", 2049 nonce="274312:dj83hs9s", 2050 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 2052 The above examples are provided for illustration purposes only. 2053 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 2054 [I-D.ietf-oauth-v2-http-mac] specifications before use. 2056 Each access token type definition specifies the additional attributes 2057 (if any) sent to the client together with the "access_token" response 2058 parameter. It also defines the HTTP authentication method used to 2059 include the access token when making a protected resource request. 2061 7.2. Error Response 2063 If a resource access request fails, the resource server SHOULD inform 2064 the client of the error. While the specifics of such error responses 2065 are beyond the scope of this specification, this documents 2066 establishes a common registry in Section 11.4 for error values to be 2067 shared among OAuth token authentication schemes. 2069 New authentication schemes designed primarily for OAuth token 2070 authentication SHOULD define a mechanism for providing an error 2071 status code to the client, in which the error values allowed are 2072 registered in the error registry established by this specification. 2073 Such schemes MAY limit the set of valid error codes to a subset of 2074 the registered values. If the error code is returned using a named 2075 parameter, the parameter name SHOULD be "error". 2077 Other schemes capable of being used for OAuth token authentication, 2078 but not primarily designed for that purpose, MAY bind their error 2079 values to the registry in the same manner. 2081 New authentication schemes MAY choose to also specify the use of the 2082 "error_description" and "error_uri" parameters to return error 2083 information in a manner parallel to their usage in this 2084 specification. 2086 8. Extensibility 2088 8.1. Defining Access Token Types 2090 Access token types can be defined in one of two ways: registered in 2091 the access token type registry (following the procedures in 2092 Section 11.1), or by using a unique absolute URI as its name. 2094 Types utilizing a URI name SHOULD be limited to vendor-specific 2095 implementations that are not commonly applicable, and are specific to 2096 the implementation details of the resource server where they are 2097 used. 2099 All other types MUST be registered. Type names MUST conform to the 2100 type-name ABNF. If the type definition includes a new HTTP 2101 authentication scheme, the type name SHOULD be identical to the HTTP 2102 authentication scheme name (as defined by [RFC2617]). The token type 2103 "example" is reserved for use in examples. 2105 type-name = 1*name-char 2106 name-char = "-" / "." / "_" / DIGIT / ALPHA 2108 8.2. Defining New Endpoint Parameters 2110 New request or response parameters for use with the authorization 2111 endpoint or the token endpoint are defined and registered in the 2112 parameters registry following the procedure in Section 11.2. 2114 Parameter names MUST conform to the param-name ABNF and parameter 2115 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2116 to the syntax of an existing parameter). 2118 param-name = 1*name-char 2119 name-char = "-" / "." / "_" / DIGIT / ALPHA 2121 Unregistered vendor-specific parameter extensions that are not 2122 commonly applicable, and are specific to the implementation details 2123 of the authorization server where they are used SHOULD utilize a 2124 vendor-specific prefix that is not likely to conflict with other 2125 registered values (e.g. begin with 'companyname_'). 2127 8.3. Defining New Authorization Grant Types 2129 New authorization grant types can be defined by assigning them a 2130 unique absolute URI for use with the "grant_type" parameter. If the 2131 extension grant type requires additional token endpoint parameters, 2132 they MUST be registered in the OAuth parameters registry as described 2133 by Section 11.2. 2135 8.4. Defining New Authorization Endpoint Response Types 2137 New response types for use with the authorization endpoint are 2138 defined and registered in the authorization endpoint response type 2139 registry following the procedure in Section 11.3. Response type 2140 names MUST conform to the response-type ABNF. 2142 response-type = response-name *( SP response-name ) 2143 response-name = 1*response-char 2144 response-char = "_" / DIGIT / ALPHA 2146 If a response type contains one or more space characters (%x20), it 2147 is compared as a space-delimited list of values in which the order of 2148 values does not matter. Only one order of values can be registered, 2149 which covers all other arrangements of the same set of values. 2151 For example, the response type "token code" is left undefined by this 2152 specification. However, an extension can define and register the 2153 "token code" response type. Once registered, the same combination 2154 cannot be registered as "code token", but both values can be used to 2155 denote the same response type. 2157 8.5. Defining Additional Error Codes 2159 In cases where protocol extensions (i.e. access token types, 2160 extension parameters, or extension grant types) require additional 2161 error codes to be used with the authorization code grant error 2162 response (Section 4.1.2.1), the implicit grant error response 2163 (Section 4.2.2.1), the token error response (Section 5.2), or the 2164 resource access error response (Section 7.2), such error codes MAY be 2165 defined. 2167 Extension error codes MUST be registered (following the procedures in 2168 Section 11.4) if the extension they are used in conjunction with is a 2169 registered access token type, a registered endpoint parameter, or an 2170 extension grant type. Error codes used with unregistered extensions 2171 MAY be registered. 2173 Error codes MUST conform to the error ABNF, and SHOULD be prefixed by 2174 an identifying name when possible. For example, an error identifying 2175 an invalid value set to the extension parameter "example" SHOULD be 2176 named "example_invalid". 2178 error = 1*error-char 2179 error-char = %x20-21 / %x23-5B / %x5D-7E 2181 9. Native Applications 2183 Native applications are clients installed and executed on the device 2184 used by the resource owner (i.e. desktop application, native mobile 2185 application). Native applications require special consideration 2186 related to security, platform capabilities, and overall end-user 2187 experience. 2189 The authorization endpoint requires interaction between the client 2190 and the resource owner's user-agent. Native applications can invoke 2191 an external user-agent or embed a user-agent within the application. 2192 For example: 2194 o External user-agent - the native application can capture the 2195 response from the authorization server using a redirection URI 2196 with a scheme registered with the operating system to invoke the 2197 client as the handler, manual copy-and-paste of the credentials, 2198 running a local web server, installing a user-agent extension, or 2199 by providing a redirection URI identifying a server-hosted 2200 resource under the client's control, which in turn makes the 2201 response available to the native application. 2202 o Embedded user-agent - the native application obtains the response 2203 by directly communicating with the embedded user-agent by 2204 monitoring state changes emitted during the resource load, or 2205 accessing the user-agent's cookies storage. 2207 When choosing between an external or embedded user-agent, developers 2208 should consider: 2210 o An External user-agent may improve completion rate as the resource 2211 owner may already have an active session with the authorization 2212 server removing the need to re-authenticate. It provides a 2213 familiar end-user experience and functionality. The resource 2214 owner may also rely on user-agent features or extensions to assist 2215 with authentication (e.g. password manager, 2-factor device 2216 reader). 2217 o An embedded user-agent may offer improved usability, as it removes 2218 the need to switch context and open new windows. 2219 o An embedded user-agent poses a security challenge because resource 2220 owners are authenticating in an unidentified window without access 2221 to the visual protections found in most external user-agents. An 2222 embedded user-agent educates end-users to trust unidentified 2223 requests for authentication (making phishing attacks easier to 2224 execute). 2226 When choosing between the implicit grant type and the authorization 2227 code grant type, the following should be considered: 2229 o Native applications that use the authorization code grant type 2230 SHOULD do so without using client credentials, due to the native 2231 application's inability to keep client credentials confidential. 2232 o When using the implicit grant type flow, a refresh token is not 2233 returned, which requires repeating the authorization process once 2234 the access token expires. 2236 10. Security Considerations 2238 As a flexible and extensible framework, OAuth's security 2239 considerations depend on many factors. The following sections 2240 provide implementers with security guidelines focused on the three 2241 client profiles described in Section 2.1: web application, user- 2242 agent-based application, and native application. 2244 A comprehensive OAuth security model and analysis, as well as 2245 background for the protocol design, is provided by 2246 [I-D.ietf-oauth-v2-threatmodel]. 2248 10.1. Client Authentication 2250 The authorization server establishes client credentials with web 2251 application clients for the purpose of client authentication. The 2252 authorization server is encouraged to consider stronger client 2253 authentication means than a client password. Web application clients 2254 MUST ensure confidentiality of client passwords and other client 2255 credentials. 2257 The authorization server MUST NOT issue client passwords or other 2258 client credentials to native application or user-agent-based 2259 application clients for the purpose of client authentication. The 2260 authorization server MAY issue a client password or other credentials 2261 for a specific installation of a native application client on a 2262 specific device. 2264 When client authentication is not possible, the authorization server 2265 SHOULD employ other means to validate the client's identity. For 2266 example, by requiring the registration of the client redirection URI 2267 or enlisting the resource owner to confirm identity. A valid 2268 redirection URI is not sufficient to verify the client's identity 2269 when asking for resource owner authorization, but can be used to 2270 prevent delivering credentials to a counterfeit client after 2271 obtaining resource owner authorization. 2273 The authorization server must consider the security implications of 2274 interacting with unauthenticated clients and take measures to limit 2275 the potential exposure of other credentials (e.g. refresh tokens) 2276 issued to such clients. 2278 10.2. Client Impersonation 2280 A malicious client can impersonate another client and obtain access 2281 to protected resources, if the impersonated client fails to, or is 2282 unable to, keep its client credentials confidential. 2284 The authorization server MUST authenticate the client whenever 2285 possible. If the authorization server cannot authenticate the client 2286 due to the client's nature, the authorization server MUST require the 2287 registration of any redirection URI used for receiving authorization 2288 responses, and SHOULD utilize other means to protect resource owners 2289 from such potentially malicious clients. For example, the 2290 authorization server can engage the resource owner to assist in 2291 identifying the client and its origin. 2293 The authorization server SHOULD enforce explicit resource owner 2294 authentication and provide the resource owner with information about 2295 the client and the requested authorization scope and lifetime. It is 2296 up to the resource owner to review the information in the context of 2297 the current client, and authorize or deny the request. 2299 The authorization server SHOULD NOT process repeated authorization 2300 requests automatically (without active resource owner interaction) 2301 without authenticating the client or relying on other measures to 2302 ensure the repeated request comes from the original client and not an 2303 impersonator. 2305 10.3. Access Tokens 2307 Access token credentials (as well as any confidential access token 2308 attributes) MUST be kept confidential in transit and storage, and 2309 only shared among the authorization server, the resource servers the 2310 access token is valid for, and the client to whom the access token is 2311 issued. Access token credentials MUST only be transmitted using TLS 2312 as described in Section 1.6 with server authentication as defined by 2313 [RFC2818]. 2315 When using the implicit grant type, the access token is transmitted 2316 in the URI fragment, which can expose it to unauthorized parties. 2318 The authorization server MUST ensure that access tokens cannot be 2319 generated, modified, or guessed to produce valid access tokens by 2320 unauthorized parties. 2322 The client SHOULD request access tokens with the minimal scope 2323 necessary. The authorization server SHOULD take the client identity 2324 into account when choosing how to honor the requested scope, and MAY 2325 issue an access token with a less rights than requested. 2327 This specification does not provide any methods for the resource 2328 server to ensure that an access token presented to it by a given 2329 client was issued to that client by the authorization server. 2331 10.4. Refresh Tokens 2333 Authorization servers MAY issue refresh tokens to web application 2334 clients and native application clients. 2336 Refresh tokens MUST be kept confidential in transit and storage, and 2337 shared only among the authorization server and the client to whom the 2338 refresh tokens were issued. The authorization server MUST maintain 2339 the binding between a refresh token and the client to whom it was 2340 issued. Refresh tokens MUST only be transmitted using TLS as 2341 described in Section 1.6 with server authentication as defined by 2342 [RFC2818]. 2344 The authorization server MUST verify the binding between the refresh 2345 token and client identity whenever the client identity can be 2346 authenticated. When client authentication is not possible, the 2347 authorization server SHOULD deploy other means to detect refresh 2348 token abuse. 2350 For example, the authorization server could employ refresh token 2351 rotation in which a new refresh token is issued with every access 2352 token refresh response. The previous refresh token is invalidated 2353 but retained by the authorization server. If a refresh token is 2354 compromised and subsequently used by both the attacker and the 2355 legitimate client, one of them will present an invalidated refresh 2356 token, which will inform the authorization server of the breach. 2358 The authorization server MUST ensure that refresh tokens cannot be 2359 generated, modified, or guessed to produce valid refresh tokens by 2360 unauthorized parties. 2362 10.5. Authorization Codes 2364 The transmission of authorization codes SHOULD be made over a secure 2365 channel, and the client SHOULD require the use of TLS with its 2366 redirection URI if the URI identifies a network resource. Since 2367 authorization codes are transmitted via user-agent redirections, they 2368 could potentially be disclosed through user-agent history and HTTP 2369 referrer headers. 2371 Authorization codes operate as plaintext bearer credentials, used to 2372 verify that the resource owner who granted authorization at the 2373 authorization server is the same resource owner returning to the 2374 client to complete the process. Therefore, if the client relies on 2375 the authorization code for its own resource owner authentication, the 2376 client redirection endpoint MUST require the use of TLS. 2378 Authorization codes MUST be short lived and single use. If the 2379 authorization server observes multiple attempts to exchange an 2380 authorization code for an access token, the authorization server 2381 SHOULD attempt to revoke all access tokens already granted based on 2382 the compromised authorization code. 2384 If the client can be authenticated, the authorization servers MUST 2385 authenticate the client and ensure that the authorization code was 2386 issued to the same client. 2388 10.6. Authorization Code Redirection URI Manipulation 2390 When requesting authorization using the authorization code grant 2391 type, the client can specify a redirection URI via the "redirect_uri" 2392 parameter. If an attacker can manipulate the value of the 2393 redirection URI, it can cause the authorization server to redirect 2394 the resource owner user-agent to a URI under the control of the 2395 attacker with the authorization code. 2397 An attacker can create an account at a legitimate client and initiate 2398 the authorization flow. When the attacker's user-agent is sent to 2399 the authorization server to grant access, the attacker grabs the 2400 authorization URI provided by the legitimate client, and replaces the 2401 client's redirection URI with a URI under the control of the 2402 attacker. The attacker then tricks the victim into following the 2403 manipulated link to authorize access to the legitimate client. 2405 Once at the authorization server, the victim is prompted with a 2406 normal, valid request on behalf of a legitimate and trusted client, 2407 and authorizes the request. The victim is then redirected to an 2408 endpoint under the control of the attacker with the authorization 2409 code. The attacker completes the authorization flow by sending the 2410 authorization code to the client using the original redirection URI 2411 provided by the client. The client exchanges the authorization code 2412 with an access token and links it to the attacker's client account, 2413 which can now gain access to the protected resources authorized by 2414 the victim (via the client). 2416 In order to prevent such an attack, the authorization server MUST 2417 ensure that the redirection URI used to obtain the authorization code 2418 is identical to the redirection URI provided when exchanging the 2419 authorization code for an access token. The authorization server 2420 MUST require public clients and SHOULD require confidential clients 2421 to register their redirection URIs. If a redirection URI is provided 2422 in the request, the authorization server MUST validate it against the 2423 registered value. 2425 10.7. Resource Owner Password Credentials 2427 The resource owner password credentials grant type is often used for 2428 legacy or migration reasons. It reduces the overall risk of storing 2429 username and password by the client, but does not eliminate the need 2430 to expose highly privileged credentials to the client. 2432 This grant type carries a higher risk than other grant types because 2433 it maintains the password anti-pattern this protocol seeks to avoid. 2434 The client could abuse the password or the password could 2435 unintentionally be disclosed to an attacker (e.g. via log files or 2436 other records kept by the client). 2438 Additionally, because the resource owner does not have control over 2439 the authorization process (the resource owner involvement ends when 2440 it hands over its credentials to the client), the client can obtain 2441 access tokens with a broader scope than desired by the resource 2442 owner. The authorization server should consider the scope and 2443 lifetime of access tokens issued via this grant type. 2445 The authorization server and client SHOULD minimize use of this grant 2446 type and utilize other grant types whenever possible. 2448 10.8. Request Confidentiality 2450 Access tokens, refresh tokens, resource owner passwords, and client 2451 credentials MUST NOT be transmitted in the clear. Authorization 2452 codes SHOULD NOT be transmitted in the clear. 2454 The "state" and "scope" parameters SHOULD NOT include sensitive 2455 client or resource owner information in plain text as they can be 2456 transmitted over insecure channels or stored insecurely. 2458 10.9. Endpoints Authenticity 2460 In order to prevent man-in-the-middle attacks, the authorization 2461 server MUST require the use of TLS with server authentication as 2462 defined by [RFC2818] for any request sent to the authorization and 2463 token endpoints. The client MUST validate the authorization server's 2464 TLS certificate as defined by [RFC6125], and in accordance with its 2465 requirements for server identity authentication. 2467 10.10. Credentials Guessing Attacks 2469 The authorization server MUST prevent attackers from guessing access 2470 tokens, authorization codes, refresh tokens, resource owner 2471 passwords, and client credentials. 2473 The probability of an attacker guessing generated tokens (and other 2474 credentials not intended for handling by end-users) MUST be less than 2475 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2477 The authorization server MUST utilize other means to protect 2478 credentials intended for end-user usage. 2480 10.11. Phishing Attacks 2482 Wide deployment of this and similar protocols may cause end-users to 2483 become inured to the practice of being redirected to websites where 2484 they are asked to enter their passwords. If end-users are not 2485 careful to verify the authenticity of these websites before entering 2486 their credentials, it will be possible for attackers to exploit this 2487 practice to steal resource owners' passwords. 2489 Service providers should attempt to educate end-users about the risks 2490 phishing attacks pose, and should provide mechanisms that make it 2491 easy for end-users to confirm the authenticity of their sites. 2492 Client developers should consider the security implications of how 2493 they interact with the user-agent (e.g., external, embedded), and the 2494 ability of the end-user to verify the authenticity of the 2495 authorization server. 2497 To reduce the risk of phishing attacks, the authorization servers 2498 MUST require the use of TLS on every endpoint used for end-user 2499 interaction. 2501 10.12. Cross-Site Request Forgery 2503 Cross-site request forgery (CSRF) is an exploit in which an attacker 2504 causes the user-agent of a victim end-user to follow a malicious URI 2505 (e.g. provided to the user-agent as a misleading link, image, or 2506 redirection) to a trusting server (usually established via the 2507 presence of a valid session cookie). 2509 A CSRF attack against the client's redirection URI allows an attacker 2510 to inject their own authorization code or access token, which can 2511 result in the client using an access token associated with the 2512 attacker's protected resources rather than the victim's (e.g. save 2513 the victim's bank account information to a protected resource 2514 controlled by the attacker). 2516 The client MUST implement CSRF protection for its redirection URI. 2517 This is typically accomplished by requiring any request sent to the 2518 redirection URI endpoint to include a value that binds the request to 2519 the user-agent's authenticated state (e.g. a hash of the session 2520 cookie used to authenticate the user-agent). The client SHOULD 2521 utilize the "state" request parameter to deliver this value to the 2522 authorization server when making an authorization request. 2524 Once authorization has been obtained from the end-user, the 2525 authorization server redirects the end-user's user-agent back to the 2526 client with the required binding value contained in the "state" 2527 parameter. The binding value enables the client to verify the 2528 validity of the request by matching the binding value to the user- 2529 agent's authenticated state. The binding value used for CSRF 2530 protection MUST contain a non-guessable value (as described in 2531 Section 10.10), and the user-agent's authenticated state (e.g. 2532 session cookie, HTML5 local storage) MUST be kept in a location 2533 accessible only to the client and the user-agent (i.e., protected by 2534 same-origin policy). 2536 A CSRF attack against the authorization server's authorization 2537 endpoint can result in an attacker obtaining end-user authorization 2538 for a malicious client without involving or alerting the end-user. 2540 The authorization server MUST implement CSRF protection for its 2541 authorization endpoint, and ensure that a malicious client cannot 2542 obtain authorization without the awareness and explicit consent of 2543 the resource owner. 2545 10.13. Clickjacking 2547 In a clickjacking attack, an attacker registers a legitimate client 2548 and then constructs a malicious site in which it loads the 2549 authorization server's authorization endpoint web page in a 2550 transparent iframe overlaid on top of a set of dummy buttons, which 2551 are carefully constructed to be placed directly under important 2552 buttons on the authorization page. When an end-user clicks a 2553 misleading visible button, the end-user is actually clicking an 2554 invisible button on the authorization page (such as an "Authorize" 2555 button). This allows an attacker to trick a resource owner into 2556 granting its client access without their knowledge. 2558 To prevent this form of attack, native applications SHOULD use 2559 external browsers instead of embedding browsers within the 2560 application when requesting end-user authorization. For most newer 2561 browsers, avoidance of iframes can be enforced by the authorization 2562 server using the (non-standard) "x-frame-options" header. This 2563 header can have two values, "deny" and "sameorigin", which will block 2564 any framing, or framing by sites with a different origin, 2565 respectively. For older browsers, JavaScript framebusting techniques 2566 can be used but may not be effective in all browsers. 2568 10.14. Code Injection and Input Validation 2570 A code injection attack occurs when an input or otherwise external 2571 variable is used by an application unsanitized and causes 2572 modification to the application logic. This may allow an attacker to 2573 gain access to the application device or its data, cause denial of 2574 service, or a wide range of malicious side-effects. 2576 The Authorization server and client MUST sanitize (and validate when 2577 possible) any value received, in particular, the value of the "state" 2578 and "redirect_uri" parameters. 2580 10.15. Open Redirectors 2582 The authorization server authorization endpoint and the client 2583 redirection endpoint can be improperly configured and operate as open 2584 redirectors. An open redirector is an endpoint using a parameter to 2585 automatically redirect a user-agent to the location specified by the 2586 parameter value without any validation. 2588 Open redirectors can be used in phishing attacks, or by an attacker 2589 to get end-users to visit malicious sites by making the URI's 2590 authority look like a familiar and trusted destination. In addition, 2591 if the authorization server allows the client to register only part 2592 of the redirection URI, an attacker can use an open redirector 2593 operated by the client to construct a redirection URI that will pass 2594 the authorization server validation but will send the authorization 2595 code or access token to an endpoint under the control of the 2596 attacker. 2598 10.16. Misuse of Access Token to Impersonate Resource Owner in Implicit 2599 Flow 2601 For public clients using implicit flows, this specification does not 2602 provide any method for the client to determine what client an access 2603 token was issued to. 2605 A Resource Owner may willingly delegate access to a resource by 2606 granting an access token to an attacker's malicious client. This may 2607 be due to Phishing or some other pretext. An attacker may also steal 2608 a token via some other mechanism. An attacker may then attempt to 2609 impersonate the resource owner by providing the access token to a 2610 legitimate public client. 2612 In the implicit flow (response_type=token), the attacker can easily 2613 switch the token in the response from the authorization server, 2614 replacing the real access_token with the one previously issued to the 2615 attacker. 2617 Servers communicating with native applications that rely on being 2618 passed an access token in the back channel to identify the user of 2619 the client may be similarly compromised by an attacker creating a 2620 compromised application that can inject arbitrary stolen access 2621 tokens. 2623 Any public client that makes the assumption that only the resource 2624 owner can present them with a valid access token for the resource is 2625 vulnerable to this attack. 2627 This attack may expose information about the resource owner at the 2628 legitimate client to the attacker (malicious client). This will also 2629 allow the attacker to perform operations at the legitimate client 2630 with the same permissions as the resource owner who originally 2631 granted the access token or authorization code. 2633 Authenticating Resource Owners to clients is out of scope for this 2634 specification. Any specification that uses the authorization process 2635 as a form of delegated end-user authentication to the client (e.g. 2636 third-party sign-in service) MUST NOT use the implicit flow without 2637 additional security mechanisms such as audience restricting the 2638 access token that enable the client to determine if the access token 2639 was issued for its use. 2641 11. IANA Considerations 2643 11.1. OAuth Access Token Type Registry 2645 This specification establishes the OAuth access token type registry. 2647 Access token types are registered with a Specification Required 2648 ([RFC5226]) after a two week review period on the [TBD]@ietf.org 2649 mailing list, on the advice of one or more Designated Experts. 2650 However, to allow for the allocation of values prior to publication, 2651 the Designated Expert(s) may approve registration once they are 2652 satisfied that such a specification will be published. 2654 Registration requests must be sent to the [TBD]@ietf.org mailing list 2655 for review and comment, with an appropriate subject (e.g., "Request 2656 for access token type: example"). [[ Note to RFC-EDITOR: The name of 2657 the mailing list should be determined in consultation with the IESG 2658 and IANA. Suggested name: oauth-ext-review. ]] 2660 Within the review period, the Designated Expert(s) will either 2661 approve or deny the registration request, communicating this decision 2662 to the review list and IANA. Denials should include an explanation 2663 and, if applicable, suggestions as to how to make the request 2664 successful. 2666 IANA must only accept registry updates from the Designated Expert(s), 2667 and should direct all requests for registration to the review mailing 2668 list. 2670 11.1.1. Registration Template 2672 Type name: 2673 The name requested (e.g., "example"). 2674 Additional Token Endpoint Response Parameters: 2675 Additional response parameters returned together with the 2676 "access_token" parameter. New parameters MUST be separately 2677 registered in the OAuth parameters registry as described by 2678 Section 11.2. 2679 HTTP Authentication Scheme(s): 2680 The HTTP authentication scheme name(s), if any, used to 2681 authenticate protected resources requests using access tokens of 2682 this type. 2683 Change controller: 2684 For standards-track RFCs, state "IETF". For others, give the name 2685 of the responsible party. Other details (e.g., postal address, 2686 e-mail address, home page URI) may also be included. 2687 Specification document(s): 2688 Reference to the document that specifies the parameter, preferably 2689 including a URI that can be used to retrieve a copy of the 2690 document. An indication of the relevant sections may also be 2691 included, but is not required. 2693 11.2. OAuth Parameters Registry 2695 This specification establishes the OAuth parameters registry. 2697 Additional parameters for inclusion in the authorization endpoint 2698 request, the authorization endpoint response, the token endpoint 2699 request, or the token endpoint response are registered with a 2700 Specification Required ([RFC5226]) after a two week review period on 2701 the [TBD]@ietf.org mailing list, on the advice of one or more 2702 Designated Experts. However, to allow for the allocation of values 2703 prior to publication, the Designated Expert(s) may approve 2704 registration once they are satisfied that such a specification will 2705 be published. 2707 Registration requests must be sent to the [TBD]@ietf.org mailing list 2708 for review and comment, with an appropriate subject (e.g., "Request 2709 for parameter: example"). [[ Note to RFC-EDITOR: The name of the 2710 mailing list should be determined in consultation with the IESG and 2711 IANA. Suggested name: oauth-ext-review. ]] 2713 Within the review period, the Designated Expert(s) will either 2714 approve or deny the registration request, communicating this decision 2715 to the review list and IANA. Denials should include an explanation 2716 and, if applicable, suggestions as to how to make the request 2717 successful. 2719 IANA must only accept registry updates from the Designated Expert(s), 2720 and should direct all requests for registration to the review mailing 2721 list. 2723 11.2.1. Registration Template 2725 Parameter name: 2726 The name requested (e.g., "example"). 2727 Parameter usage location: 2728 The location(s) where parameter can be used. The possible 2729 locations are: authorization request, authorization response, 2730 token request, or token response. 2731 Change controller: 2732 For standards-track RFCs, state "IETF". For others, give the name 2733 of the responsible party. Other details (e.g., postal address, 2734 e-mail address, home page URI) may also be included. 2735 Specification document(s): 2736 Reference to the document that specifies the parameter, preferably 2737 including a URI that can be used to retrieve a copy of the 2738 document. An indication of the relevant sections may also be 2739 included, but is not required. 2741 11.2.2. Initial Registry Contents 2743 The OAuth Parameters Registry's initial contents are: 2745 o Parameter name: client_id 2746 o Parameter usage location: authorization request, token request 2747 o Change controller: IETF 2748 o Specification document(s): [[ this document ]] 2750 o Parameter name: client_secret 2751 o Parameter usage location: token request 2752 o Change controller: IETF 2753 o Specification document(s): [[ this document ]] 2755 o Parameter name: response_type 2756 o Parameter usage location: authorization request 2757 o Change controller: IETF 2758 o Specification document(s): [[ this document ]] 2760 o Parameter name: redirect_uri 2761 o Parameter usage location: authorization request, token request 2762 o Change controller: IETF 2763 o Specification document(s): [[ this document ]] 2765 o Parameter name: scope 2766 o Parameter usage location: authorization request, authorization 2767 response, token request, token response 2768 o Change controller: IETF 2769 o Specification document(s): [[ this document ]] 2771 o Parameter name: state 2772 o Parameter usage location: authorization request, authorization 2773 response 2774 o Change controller: IETF 2775 o Specification document(s): [[ this document ]] 2777 o Parameter name: code 2778 o Parameter usage location: authorization response, token request 2779 o Change controller: IETF 2780 o Specification document(s): [[ this document ]] 2782 o Parameter name: error_description 2783 o Parameter usage location: authorization response, token response 2784 o Change controller: IETF 2785 o Specification document(s): [[ this document ]] 2787 o Parameter name: error_uri 2788 o Parameter usage location: authorization response, token response 2789 o Change controller: IETF 2790 o Specification document(s): [[ this document ]] 2792 o Parameter name: grant_type 2793 o Parameter usage location: token request 2794 o Change controller: IETF 2795 o Specification document(s): [[ this document ]] 2797 o Parameter name: access_token 2798 o Parameter usage location: authorization response, token response 2799 o Change controller: IETF 2800 o Specification document(s): [[ this document ]] 2802 o Parameter name: token_type 2803 o Parameter usage location: authorization response, token response 2804 o Change controller: IETF 2805 o Specification document(s): [[ this document ]] 2807 o Parameter name: expires_in 2808 o Parameter usage location: authorization response, token response 2809 o Change controller: IETF 2810 o Specification document(s): [[ this document ]] 2812 o Parameter name: username 2813 o Parameter usage location: token request 2814 o Change controller: IETF 2815 o Specification document(s): [[ this document ]] 2817 o Parameter name: password 2818 o Parameter usage location: token request 2819 o Change controller: IETF 2820 o Specification document(s): [[ this document ]] 2822 o Parameter name: refresh_token 2823 o Parameter usage location: token request, token response 2824 o Change controller: IETF 2825 o Specification document(s): [[ this document ]] 2827 11.3. OAuth Authorization Endpoint Response Type Registry 2829 This specification establishes the OAuth authorization endpoint 2830 response type registry. 2832 Additional response type for use with the authorization endpoint are 2833 registered with a Specification Required ([RFC5226]) after a two week 2834 review period on the [TBD]@ietf.org mailing list, on the advice of 2835 one or more Designated Experts. However, to allow for the allocation 2836 of values prior to publication, the Designated Expert(s) may approve 2837 registration once they are satisfied that such a specification will 2838 be published. 2840 Registration requests must be sent to the [TBD]@ietf.org mailing list 2841 for review and comment, with an appropriate subject (e.g., "Request 2842 for response type: example"). [[ Note to RFC-EDITOR: The name of the 2843 mailing list should be determined in consultation with the IESG and 2844 IANA. Suggested name: oauth-ext-review. ]] 2846 Within the review period, the Designated Expert(s) will either 2847 approve or deny the registration request, communicating this decision 2848 to the review list and IANA. Denials should include an explanation 2849 and, if applicable, suggestions as to how to make the request 2850 successful. 2852 IANA must only accept registry updates from the Designated Expert(s), 2853 and should direct all requests for registration to the review mailing 2854 list. 2856 11.3.1. Registration Template 2858 Response type name: 2859 The name requested (e.g., "example"). 2860 Change controller: 2861 For standards-track RFCs, state "IETF". For others, give the name 2862 of the responsible party. Other details (e.g., postal address, 2863 e-mail address, home page URI) may also be included. 2864 Specification document(s): 2865 Reference to the document that specifies the type, preferably 2866 including a URI that can be used to retrieve a copy of the 2867 document. An indication of the relevant sections may also be 2868 included, but is not required. 2870 11.3.2. Initial Registry Contents 2872 The OAuth Authorization Endpoint Response Type Registry's initial 2873 contents are: 2875 o Response type name: code 2876 o Change controller: IETF 2877 o Specification document(s): [[ this document ]] 2879 o Response type name: token 2880 o Change controller: IETF 2881 o Specification document(s): [[ this document ]] 2883 11.4. OAuth Extensions Error Registry 2885 This specification establishes the OAuth extensions error registry. 2887 Additional error codes used together with other protocol extensions 2888 (i.e. extension grant types, access token types, or extension 2889 parameters) are registered with a Specification Required ([RFC5226]) 2890 after a two week review period on the [TBD]@ietf.org mailing list, on 2891 the advice of one or more Designated Experts. However, to allow for 2892 the allocation of values prior to publication, the Designated 2893 Expert(s) may approve registration once they are satisfied that such 2894 a specification will be published. 2896 Registration requests must be sent to the [TBD]@ietf.org mailing list 2897 for review and comment, with an appropriate subject (e.g., "Request 2898 for error code: example"). [[ Note to RFC-EDITOR: The name of the 2899 mailing list should be determined in consultation with the IESG and 2900 IANA. Suggested name: oauth-ext-review. ]] 2902 Within the review period, the Designated Expert(s) will either 2903 approve or deny the registration request, communicating this decision 2904 to the review list and IANA. Denials should include an explanation 2905 and, if applicable, suggestions as to how to make the request 2906 successful. 2908 IANA must only accept registry updates from the Designated Expert(s), 2909 and should direct all requests for registration to the review mailing 2910 list. 2912 11.4.1. Registration Template 2914 Error name: 2915 The name requested (e.g., "example"). Values for the error name 2916 MUST NOT include characters outside the set %x20-21 / %x23-5B / 2917 %x5D-7E. 2918 Error usage location: 2919 The location(s) where the error can be used. The possible 2920 locations are: authorization code grant error response 2921 (Section 4.1.2.1), implicit grant error response 2922 (Section 4.2.2.1), token error response (Section 5.2), or resource 2923 access error response (Section 7.2). 2924 Related protocol extension: 2925 The name of the extension grant type, access token type, or 2926 extension parameter, the error code is used in conjunction with. 2927 Change controller: 2928 For standards-track RFCs, state "IETF". For others, give the name 2929 of the responsible party. Other details (e.g., postal address, 2930 e-mail address, home page URI) may also be included. 2931 Specification document(s): 2932 Reference to the document that specifies the error code, 2933 preferably including a URI that can be used to retrieve a copy of 2934 the document. An indication of the relevant sections may also be 2935 included, but is not required. 2937 12. References 2939 12.1. Normative References 2941 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2942 Requirement Levels", BCP 14, RFC 2119, March 1997. 2944 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2945 RFC 2246, January 1999. 2947 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2948 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2949 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2951 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2952 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2953 Authentication: Basic and Digest Access Authentication", 2954 RFC 2617, June 1999. 2956 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2958 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2959 10646", STD 63, RFC 3629, November 2003. 2961 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2962 Resource Identifier (URI): Generic Syntax", STD 66, 2963 RFC 3986, January 2005. 2965 [RFC4627] Crockford, D., "The application/json Media Type for 2966 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2968 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2969 RFC 4949, August 2007. 2971 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2972 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2973 May 2008. 2975 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2976 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2978 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2979 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2981 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2982 Verification of Domain-Based Application Service Identity 2983 within Internet Public Key Infrastructure Using X.509 2984 (PKIX) Certificates in the Context of Transport Layer 2985 Security (TLS)", RFC 6125, March 2011. 2987 [USASCII] American National Standards Institute, "Coded Character 2988 Set -- 7-bit American Standard Code for Information 2989 Interchange", ANSI X3.4, 1986. 2991 [W3C.REC-html401-19991224] 2992 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 2993 Specification", World Wide Web Consortium 2994 Recommendation REC-html401-19991224, December 1999, 2995 . 2997 [W3C.REC-xml-20081126] 2998 Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., 2999 and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth 3000 Edition)", World Wide Web Consortium Recommendation REC- 3001 xml-20081126, November 2008, 3002 . 3004 12.2. Informative References 3006 [I-D.draft-hardt-oauth-01] 3007 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 3008 Web Resource Authorization Profiles", January 2010. 3010 [I-D.ietf-oauth-saml2-bearer] 3011 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 3012 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-13 3013 (work in progress), July 2012. 3015 [I-D.ietf-oauth-v2-bearer] 3016 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 3017 Authorization Framework: Bearer Token Usage", 3018 draft-ietf-oauth-v2-bearer-21 (work in progress), 3019 June 2012. 3021 [I-D.ietf-oauth-v2-http-mac] 3022 Hammer-Lahav, E., "HTTP Authentication: MAC Access 3023 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 3024 progress), February 2012. 3026 [I-D.ietf-oauth-v2-threatmodel] 3027 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3028 Threat Model and Security Considerations", 3029 draft-ietf-oauth-v2-threatmodel-06 (work in progress), 3030 June 2012. 3032 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 3033 April 2010. 3035 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3037 This section provides Augmented Backus-Naur Form (ABNF) syntax 3038 descriptions for the elements defined in this specification using the 3039 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3040 code points [W3C.REC-xml-20081126]; these characters are typically 3041 encoded in UTF-8. Elements are presented in the order first defined. 3043 Some of the definitions that follow use the "URI-reference" 3044 definition from [RFC3986]. 3046 Some of the definitions that follow use these common definitions: 3048 VSCHAR = %x20-7E 3049 NQCHAR = %x21 / %x23-5B / %x5D-7E 3050 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3051 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3052 %xE000-FFFD / %x10000-10FFFF 3054 (The UNICODECHARNOCRLF definition is based upon the Char definition 3055 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3056 Return and Linefeed characters.) 3058 A.1. "client_id" Syntax 3060 The "client_id" element is defined in Section 2.3.1: 3062 client-id = *VSCHAR 3064 A.2. "client_secret" Syntax 3066 The "client_secret" element is defined in Section 2.3.1: 3068 client-secret = *VSCHAR 3070 A.3. "response_type" Syntax 3072 The "response_type" element is defined in Section 3.1.1 and 3073 Section 8.4: 3075 response-type = response-name *( SP response-name ) 3076 response-name = 1*response-char 3077 response-char = "_" / DIGIT / ALPHA 3079 A.4. "scope" Syntax 3081 The "scope" element is defined in Section 3.3: 3083 scope = scope-token *( SP scope-token ) 3084 scope-token = 1*NQCHAR 3086 A.5. "state" Syntax 3088 The "state" element is defined in Section 4.1.1, Section 4.1.2, 3089 Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1: 3091 state = 1*VSCHAR 3093 A.6. "redirect_uri" Syntax 3095 The "redirect_uri" element is defined in Section 4.1.1, 3096 Section 4.1.3, and Section 4.2.1: 3098 redirect-uri = URI-reference 3100 A.7. "error" Syntax 3102 The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1, 3103 Section 5.2, Section 7.2, and Section 8.5: 3105 error = 1*NQSCHAR 3107 A.8. "error_description" Syntax 3109 The "error_description" element is defined in Section 4.1.2.1, 3110 Section 4.2.2.1, Section 5.2, and Section 7.2: 3112 error-description = 1*NQSCHAR 3114 A.9. "error_uri" Syntax 3116 The "error_uri" element is defined in Section 4.1.2.1, 3117 Section 4.2.2.1, Section 5.2, and Section 7.2: 3119 error-uri = URI-reference 3121 A.10. "grant_type" Syntax 3123 The "grant_type" element is defined in Section 4.1.3, Section 4.3.2, 3124 Section 4.4.2, Section 6, and Section 4.5: 3126 grant-type = grant-name / URI-reference 3127 grant-name = 1*name-char 3128 name-char = "-" / "." / "_" / DIGIT / ALPHA 3130 A.11. "code" Syntax 3132 The "code" element is defined in Section 4.1.3: 3134 code = 1*VSCHAR 3136 A.12. "access_token" Syntax 3138 The "access_token" element is defined in Section 4.2.2 and 3139 Section 5.1: 3141 access-token = 1*VSCHAR 3143 A.13. "token_type" Syntax 3145 The "token_type" element is defined in Section 4.2.2, Section 5.1, 3146 and Section 8.1: 3148 token-type = type-name / URI-reference 3149 type-name = 1*name-char 3150 name-char = "-" / "." / "_" / DIGIT / ALPHA 3152 A.14. "expires_in" Syntax 3154 The "expires_in" element is defined in Section 4.2.2 and Section 5.1: 3156 expires-in = 1*DIGIT 3158 A.15. "username" Syntax 3160 The "username" element is defined in Section 4.3.2: 3162 username = *UNICODECHARNOCRLF 3164 A.16. "password" Syntax 3166 The "password" element is defined in Section 4.3.2: 3168 password = *UNICODECHARNOCRLF 3170 A.17. "refresh_token" Syntax 3172 The "refresh_token" element is defined in Section 5.1 and Section 6: 3174 refresh-token = 1*VSCHAR 3176 A.18. Endpoint Parameter Syntax 3178 The syntax for new endpoint parameters is defined in Section 8.2: 3180 param-name = 1*name-char 3181 name-char = "-" / "." / "_" / DIGIT / ALPHA 3183 Appendix B. Use of application/x-www-form-urlencoded Media Type 3185 At the time of publication of this specification, the 3186 "application/x-www-form-urlencoded" media type was defined in Section 3187 17.13.4 of [W3C.REC-html401-19991224], but not registered in the IANA 3188 media types registry 3189 (). 3190 Furthermore, that definition is incomplete, as it does not consider 3191 non-US-ASCII characters. 3193 To address this shortcoming when generating payloads using this media 3194 type, names and values MUST be encoded using the UTF-8 character 3195 encoding scheme [RFC3629] first; the resulting octet sequence then 3196 needs to be further encoded using the escaping rules defined in 3197 [W3C.REC-html401-19991224]. 3199 When parsing data from a payload using this media type, the names and 3200 values resulting from reversing the name/value encoding consequently 3201 need to be treated as octet sequences, to be decoded using the UTF-8 3202 character encoding scheme. 3204 For example, the value consisting of the six Unicode code points (1) 3205 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3206 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3207 SIGN) would be encoded into the octet sequence below (using 3208 hexadecimal notation): 3210 20 25 26 2B C2 A3 E2 82 AC 3212 and then represented in the payload as: 3214 +%25%26%2B%C2%A3%E2%82%AC 3216 Appendix C. Acknowledgements 3218 The initial OAuth 2.0 protocol specification was edited by David 3219 Recordon, based on two previous publications: the OAuth 1.0 community 3220 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 3221 Authorization Profiles) [I-D.draft-hardt-oauth-01]. Eran Hammer then 3222 edited the drafts through draft -26. The Security Considerations 3223 section was drafted by Torsten Lodderstedt, Mark McGloin, Phil Hunt, 3224 Anthony Nadalin, and John Bradley. The section on use of the 3225 application/x-www-form-urlencoded media type was drafted by Julian 3226 Reschke. The ABNF section was drafted by Michael B. Jones. 3228 The OAuth 1.0 community specification was edited by Eran Hammer and 3229 authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 3230 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 3231 Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 3232 Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 3233 Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 3235 The OAuth WRAP specification was edited by Dick Hardt and authored by 3236 Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. 3238 This specification is the work of the OAuth Working Group, which 3239 includes dozens of active and dedicated participants. In particular, 3240 the following individuals contributed ideas, feedback, and wording 3241 that shaped and formed the final specification: 3243 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 3244 Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres, 3245 Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill 3246 de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin, 3247 Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan 3248 Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Eran 3249 Hammer, Justin Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. 3250 Jones, Terry Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le 3251 Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, 3252 Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin, 3253 Laurence Miao, William Mills, Chuck Mortimore, Anthony Nadalin, 3254 Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob 3255 Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, 3256 Justin Smith, Haibin Song, Niv Steingarten, Christian Stuebner, 3257 Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. Thompson, 3258 Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar 3259 Woodward. 3261 This document was produced under the chairmanship of Blaine Cook, 3262 Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. 3263 The area directors included Lisa Dusseault, Peter Saint-Andre, and 3264 Stephen Farrell. 3266 Appendix D. Document History 3268 [[ to be removed by the RFC editor before publication as an RFC ]] 3270 -29 3271 o Added "MUST" to "A public client that was not issued a client 3272 password MUST use the "client_id" request parameter to identify 3273 itself when sending requests to the token endpoint" and added text 3274 explaining why this must be so. 3275 o Added that the authorization server MUST "ensure the authorization 3276 code was issued to the authenticated confidential client or to the 3277 public client identified by the "client_id" in the request". 3278 o Added Security Considerations section "Misuse of Access Token to 3279 Impersonate Resource Owner in Implicit Flow". 3280 o Added references in the "Implicit" and "Implicit Grant" sections 3281 to particularly pertinent security considerations. 3282 o Added appendix "Use of application/x-www-form-urlencoded Media 3283 Type" and referenced it in places that this encoding is used. 3284 o Deleted ";charset=UTF-8" from examples formerly using "Content- 3285 Type: application/x-www-form-urlencoded;charset=UTF-8". 3286 o Added the phrase "with a character encoding of UTF-8" when 3287 describing how to send requests using the HTTP request entity- 3288 body. 3289 o For symmetry when using HTTP Basic authentication, also apply the 3290 "application/x-www-form-urlencoded" encoding to the client 3291 password, just as was already done for the client identifier. 3292 o Added "The ABNF below is defined in terms of Unicode code points 3293 [W3C.REC-xml-20081126]; these characters are typically encoded in 3294 UTF-8". 3295 o Replaced UNICODENOCTRLCHAR in ABNF with UNICODECHARNOCRLF = %x09 / 3296 %x20-7E / %x80-D7FF / %xE000-FFFD / %x10000-10FFFF. 3297 o Corrected incorrect uses of "which". 3298 o Reduced multiple blank lines around artwork elements to single 3299 blank lines. 3300 o Removed Eran Hammer's name from the author list, at his request. 3301 Dick Hardt is now listed as the editor. 3303 -28 3304 o Updated the ABNF in the manner discussed by the working group, 3305 allowing "username" and "password" to be Unicode and restricting 3306 "client_id" and "client_secret" to ASCII. 3307 o Specified the use of the application/x-www-form-urlencoded 3308 content-type encoding method to encode the "client_id" when used 3309 as the password for HTTP Basic. 3311 -27 3312 o Added character set restrictions for error, error_description, and 3313 error_uri parameters consistent with the OAuth Bearer spec. 3314 o Added "resource access error response" as an error usage location 3315 in the OAuth Extensions Error Registry. 3316 o Added an ABNF for all message elements. 3317 o Corrected editorial issues identified during review. 3319 Authors' Addresses 3321 Dick Hardt (editor) 3322 Microsoft 3324 Email: dick.hardt@gmail.com 3325 URI: http://dickhardt.org/ 3327 David Recordon 3328 Facebook 3330 Email: dr@fb.com 3331 URI: http://www.davidrecordon.com/