idnits 2.17.1 draft-ietf-oauth-v2-31.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 31, 2012) is 4284 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 2661, 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-22 == 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) July 31, 2012 5 Intended status: Standards Track 6 Expires: February 1, 2013 8 The OAuth 2.0 Authorization Framework 9 draft-ietf-oauth-v2-31 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 February 1, 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 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 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 client MAY use the "client_id" request parameter to identify itself 977 when sending requests to the token endpoint. In the 978 "authorization_code" "grant_type" request to the token endpoint, an 979 unauthenticated client MUST send its "client_id" to prevent itself 980 from inadvertently accepting a code intended for a client with a 981 different "client_id". This protects the client from substitution of 982 the authentication code. (It provides no additional security for the 983 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 (This error code is needed because a 500 Internal Server 1210 Error HTTP status code cannot be returned to the client 1211 via a HTTP redirect.) 1212 temporarily_unavailable 1213 The authorization server is currently unable to handle 1214 the request due to a temporary overloading or maintenance 1215 of the server. (This error code is needed because a 503 1216 Service Unavailable HTTP status code cannot be returned 1217 to the client via a HTTP redirect.) 1218 Values for the "error" parameter MUST NOT include characters 1219 outside the set %x20-21 / %x23-5B / %x5D-7E. 1220 error_description 1221 OPTIONAL. A human-readable ASCII [USASCII] text providing 1222 additional information, used to assist the client developer in 1223 understanding the error that occurred. 1224 Values for the "error_description" parameter MUST NOT include 1225 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1226 error_uri 1227 OPTIONAL. A URI identifying a human-readable web page with 1228 information about the error, used to provide the client 1229 developer with additional information about the error. 1230 Values for the "error_uri" parameter MUST conform to the URI- 1231 Reference syntax, and thus MUST NOT include characters outside 1232 the set %x21 / %x23-5B / %x5D-7E. 1233 state 1234 REQUIRED if a "state" parameter was present in the client 1235 authorization request. The exact value received from the 1236 client. 1238 For example, the authorization server redirects the user-agent by 1239 sending the following HTTP response: 1241 HTTP/1.1 302 Found 1242 Location: https://client.example.com/cb?error=access_denied&state=xyz 1244 4.1.3. Access Token Request 1246 The client makes a request to the token endpoint by sending the 1247 following parameters using the "application/x-www-form-urlencoded" 1248 format per Appendix B with a character encoding of UTF-8 in the HTTP 1249 request entity-body: 1251 grant_type 1252 REQUIRED. Value MUST be set to "authorization_code". 1253 code 1254 REQUIRED. The authorization code received from the 1255 authorization server. 1256 redirect_uri 1257 REQUIRED, if the "redirect_uri" parameter was included in the 1258 authorization request as described in Section 4.1.1, and their 1259 values MUST be identical. 1260 client_id 1261 REQUIRED, if the client is not authenticating with the 1262 authorization server as described in Section 3.2.1. 1264 If the client type is confidential or the client was issued client 1265 credentials (or assigned other authentication requirements), the 1266 client MUST authenticate with the authorization server as described 1267 in Section 3.2.1. 1269 For example, the client makes the following HTTP request using TLS 1270 (with extra line breaks for display purposes only): 1272 POST /token HTTP/1.1 1273 Host: server.example.com 1274 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1275 Content-Type: application/x-www-form-urlencoded 1277 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1278 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1280 The authorization server MUST: 1282 o require client authentication for confidential clients or for any 1283 client that was issued client credentials (or with other 1284 authentication requirements), 1285 o authenticate the client if client authentication is included, 1286 o ensure the authorization code was issued to the authenticated 1287 confidential client, or if the client is public, ensure the code 1288 was issued to "client_id" in the request, 1289 o verify that the authorization code is valid, and 1290 o ensure that the "redirect_uri" parameter is present if the 1291 "redirect_uri" parameter was included in the initial authorization 1292 request as described in Section 4.1.1, and if included ensure 1293 their values are identical. 1295 4.1.4. Access Token Response 1297 If the access token request is valid and authorized, the 1298 authorization server issues an access token and optional refresh 1299 token as described in Section 5.1. If the request client 1300 authentication failed or is invalid, the authorization server returns 1301 an error response as described in Section 5.2. 1303 An example successful response: 1305 HTTP/1.1 200 OK 1306 Content-Type: application/json;charset=UTF-8 1307 Cache-Control: no-store 1308 Pragma: no-cache 1310 { 1311 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1312 "token_type":"example", 1313 "expires_in":3600, 1314 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1315 "example_parameter":"example_value" 1316 } 1318 4.2. Implicit Grant 1320 The implicit grant type is used to obtain access tokens (it does not 1321 support the issuance of refresh tokens) and is optimized for public 1322 clients known to operate a particular redirection URI. These clients 1323 are typically implemented in a browser using a scripting language 1324 such as JavaScript. 1326 As a redirection-based flow, the client must be capable of 1327 interacting with the resource owner's user-agent (typically a web 1328 browser) and capable of receiving incoming requests (via redirection) 1329 from the authorization server. 1331 Unlike the authorization code grant type in which the client makes 1332 separate requests for authorization and access token, the client 1333 receives the access token as the result of the authorization request. 1335 The implicit grant type does not include client authentication, and 1336 relies on the presence of the resource owner and the registration of 1337 the redirection URI. Because the access token is encoded into the 1338 redirection URI, it may be exposed to the resource owner and other 1339 applications residing on the same device. 1341 +----------+ 1342 | Resource | 1343 | Owner | 1344 | | 1345 +----------+ 1346 ^ 1347 | 1348 (B) 1349 +----|-----+ Client Identifier +---------------+ 1350 | -+----(A)-- & Redirection URI --->| | 1351 | User- | | Authorization | 1352 | Agent -|----(B)-- User authenticates -->| Server | 1353 | | | | 1354 | |<---(C)--- Redirection URI ----<| | 1355 | | with Access Token +---------------+ 1356 | | in Fragment 1357 | | +---------------+ 1358 | |----(D)--- Redirection URI ---->| Web-Hosted | 1359 | | without Fragment | Client | 1360 | | | Resource | 1361 | (F) |<---(E)------- Script ---------<| | 1362 | | +---------------+ 1363 +-|--------+ 1364 | | 1365 (A) (G) Access Token 1366 | | 1367 ^ v 1368 +---------+ 1369 | | 1370 | Client | 1371 | | 1372 +---------+ 1374 Note: The lines illustrating steps A and B are broken into two parts 1375 as they pass through the user-agent. 1377 Figure 4: Implicit Grant Flow 1379 The flow illustrated in Figure 4 includes the following steps: 1381 (A) The client initiates the flow by directing the resource owner's 1382 user-agent to the authorization endpoint. The client includes 1383 its client identifier, requested scope, local state, and a 1384 redirection URI to which the authorization server will send the 1385 user-agent back once access is granted (or denied). 1387 (B) The authorization server authenticates the resource owner (via 1388 the user-agent) and establishes whether the resource owner 1389 grants or denies the client's access request. 1390 (C) Assuming the resource owner grants access, the authorization 1391 server redirects the user-agent back to the client using the 1392 redirection URI provided earlier. The redirection URI includes 1393 the access token in the URI fragment. 1394 (D) The user-agent follows the redirection instructions by making a 1395 request to the web-hosted client resource (which does not 1396 include the fragment per [RFC2616]). The user-agent retains the 1397 fragment information locally. 1398 (E) The web-hosted client resource returns a web page (typically an 1399 HTML document with an embedded script) capable of accessing the 1400 full redirection URI including the fragment retained by the 1401 user-agent, and extracting the access token (and other 1402 parameters) contained in the fragment. 1403 (F) The user-agent executes the script provided by the web-hosted 1404 client resource locally, which extracts the access token and 1405 passes it to the client. 1407 See Section 1.3.2 and Section 9 for background on using the implicit 1408 grant. See Section 10.3 and Section 10.16 for important security 1409 considerations when using the implicit grant. 1411 4.2.1. Authorization Request 1413 The client constructs the request URI by adding the following 1414 parameters to the query component of the authorization endpoint URI 1415 using the "application/x-www-form-urlencoded" format, per Appendix B: 1417 response_type 1418 REQUIRED. Value MUST be set to "token". 1419 client_id 1420 REQUIRED. The client identifier as described in Section 2.2. 1421 redirect_uri 1422 OPTIONAL. As described in Section 3.1.2. 1423 scope 1424 OPTIONAL. The scope of the access request as described by 1425 Section 3.3. 1426 state 1427 RECOMMENDED. An opaque value used by the client to maintain 1428 state between the request and callback. The authorization 1429 server includes this value when redirecting the user-agent back 1430 to the client. The parameter SHOULD be used for preventing 1431 cross-site request forgery as described in Section 10.12. 1433 The client directs the resource owner to the constructed URI using an 1434 HTTP redirection response, or by other means available to it via the 1435 user-agent. 1437 For example, the client directs the user-agent to make the following 1438 HTTP request using TLS (with extra line breaks for display purposes 1439 only): 1441 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1442 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1443 Host: server.example.com 1445 The authorization server validates the request to ensure all required 1446 parameters are present and valid. The authorization server MUST 1447 verify that the redirection URI to which it will redirect the access 1448 token matches a redirection URI registered by the client as described 1449 in Section 3.1.2. 1451 If the request is valid, the authorization server authenticates the 1452 resource owner and obtains an authorization decision (by asking the 1453 resource owner or by establishing approval via other means). 1455 When a decision is established, the authorization server directs the 1456 user-agent to the provided client redirection URI using an HTTP 1457 redirection response, or by other means available to it via the user- 1458 agent. 1460 4.2.2. Access Token Response 1462 If the resource owner grants the access request, the authorization 1463 server issues an access token and delivers it to the client by adding 1464 the following parameters to the fragment component of the redirection 1465 URI using the "application/x-www-form-urlencoded" format, per 1466 Appendix B: 1468 access_token 1469 REQUIRED. The access token issued by the authorization server. 1470 token_type 1471 REQUIRED. The type of the token issued as described in 1472 Section 7.1. Value is case insensitive. 1473 expires_in 1474 RECOMMENDED. The lifetime in seconds of the access token. For 1475 example, the value "3600" denotes that the access token will 1476 expire in one hour from the time the response was generated. 1477 If omitted, the authorization server SHOULD provide the 1478 expiration time via other means or document the default value. 1480 scope 1481 OPTIONAL, if identical to the scope requested by the client, 1482 otherwise REQUIRED. The scope of the access token as described 1483 by Section 3.3. 1484 state 1485 REQUIRED if the "state" parameter was present in the client 1486 authorization request. The exact value received from the 1487 client. 1489 The authorization server MUST NOT issue a refresh token. 1491 For example, the authorization server redirects the user-agent by 1492 sending the following HTTP response (with extra line breaks for 1493 display purposes only): 1495 HTTP/1.1 302 Found 1496 Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1497 &state=xyz&token_type=example&expires_in=3600 1499 Developers should note that some user-agents do not support the 1500 inclusion of a fragment component in the HTTP "Location" response 1501 header field. Such clients will require using other methods for 1502 redirecting the client than a 3xx redirection response. For example, 1503 returning an HTML page that includes a 'continue' button with an 1504 action linked to the redirection URI. 1506 The client MUST ignore unrecognized response parameters. The access 1507 token string size is left undefined by this specification. The 1508 client should avoid making assumptions about value sizes. The 1509 authorization server SHOULD document the size of any value it issues. 1511 4.2.2.1. Error Response 1513 If the request fails due to a missing, invalid, or mismatching 1514 redirection URI, or if the client identifier is missing or invalid, 1515 the authorization server SHOULD inform the resource owner of the 1516 error, and MUST NOT automatically redirect the user-agent to the 1517 invalid redirection URI. 1519 If the resource owner denies the access request or if the request 1520 fails for reasons other than a missing or invalid redirection URI, 1521 the authorization server informs the client by adding the following 1522 parameters to the fragment component of the redirection URI using the 1523 "application/x-www-form-urlencoded" format, per Appendix B: 1525 error 1526 REQUIRED. A single ASCII [USASCII] error code from the 1527 following: 1528 invalid_request 1529 The request is missing a required parameter, includes an 1530 invalid parameter value, includes a parameter more than 1531 once, or is otherwise malformed. 1532 unauthorized_client 1533 The client is not authorized to request an access token 1534 using this method. 1535 access_denied 1536 The resource owner or authorization server denied the 1537 request. 1538 unsupported_response_type 1539 The authorization server does not support obtaining an 1540 access token using this method. 1541 invalid_scope 1542 The requested scope is invalid, unknown, or malformed. 1543 server_error 1544 The authorization server encountered an unexpected 1545 condition that prevented it from fulfilling the request. 1546 (This error code is needed because a 500 Internal Server 1547 Error HTTP status code cannot be returned to the client 1548 via a HTTP redirect.) 1549 temporarily_unavailable 1550 The authorization server is currently unable to handle 1551 the request due to a temporary overloading or maintenance 1552 of the server. (This error code is needed because a 503 1553 Service Unavailable HTTP status code cannot be returned 1554 to the client via a HTTP redirect.) 1555 Values for the "error" parameter MUST NOT include characters 1556 outside the set %x20-21 / %x23-5B / %x5D-7E. 1557 error_description 1558 OPTIONAL. A human-readable ASCII [USASCII] text providing 1559 additional information, used to assist the client developer in 1560 understanding the error that occurred. 1561 Values for the "error_description" parameter MUST NOT include 1562 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1563 error_uri 1564 OPTIONAL. A URI identifying a human-readable web page with 1565 information about the error, used to provide the client 1566 developer with additional information about the error. 1567 Values for the "error_uri" parameter MUST conform to the URI- 1568 Reference syntax, and thus MUST NOT include characters outside 1569 the set %x21 / %x23-5B / %x5D-7E. 1571 state 1572 REQUIRED if a "state" parameter was present in the client 1573 authorization request. The exact value received from the 1574 client. 1576 For example, the authorization server redirects the user-agent by 1577 sending the following HTTP response: 1579 HTTP/1.1 302 Found 1580 Location: https://client.example.com/cb#error=access_denied&state=xyz 1582 4.3. Resource Owner Password Credentials Grant 1584 The resource owner password credentials grant type is suitable in 1585 cases where the resource owner has a trust relationship with the 1586 client, such as the device operating system or a highly privileged 1587 application. The authorization server should take special care when 1588 enabling this grant type, and only allow it when other flows are not 1589 viable. 1591 The grant type is suitable for clients capable of obtaining the 1592 resource owner's credentials (username and password, typically using 1593 an interactive form). It is also used to migrate existing clients 1594 using direct authentication schemes such as HTTP Basic or Digest 1595 authentication to OAuth by converting the stored credentials to an 1596 access token. 1598 +----------+ 1599 | Resource | 1600 | Owner | 1601 | | 1602 +----------+ 1603 v 1604 | Resource Owner 1605 (A) Password Credentials 1606 | 1607 v 1608 +---------+ +---------------+ 1609 | |>--(B)---- Resource Owner ------->| | 1610 | | Password Credentials | Authorization | 1611 | Client | | Server | 1612 | |<--(C)---- Access Token ---------<| | 1613 | | (w/ Optional Refresh Token) | | 1614 +---------+ +---------------+ 1616 Figure 5: Resource Owner Password Credentials Flow 1618 The flow illustrated in Figure 5 includes the following steps: 1620 (A) The resource owner provides the client with its username and 1621 password. 1622 (B) The client requests an access token from the authorization 1623 server's token endpoint by including the credentials received 1624 from the resource owner. When making the request, the client 1625 authenticates with the authorization server. 1626 (C) The authorization server authenticates the client and validates 1627 the resource owner credentials, and if valid issues an access 1628 token. 1630 4.3.1. Authorization Request and Response 1632 The method through which the client obtains the resource owner 1633 credentials is beyond the scope of this specification. The client 1634 MUST discard the credentials once an access token has been obtained. 1636 4.3.2. Access Token Request 1638 The client makes a request to the token endpoint by adding the 1639 following parameters using the "application/x-www-form-urlencoded" 1640 format per Appendix B with a character encoding of UTF-8 in the HTTP 1641 request entity-body: 1643 grant_type 1644 REQUIRED. Value MUST be set to "password". 1645 username 1646 REQUIRED. The resource owner username. 1647 password 1648 REQUIRED. The resource owner password. 1649 scope 1650 OPTIONAL. The scope of the access request as described by 1651 Section 3.3. 1653 If the client type is confidential or the client was issued client 1654 credentials (or assigned other authentication requirements), the 1655 client MUST authenticate with the authorization server as described 1656 in Section 3.2.1. 1658 For example, the client makes the following HTTP request using 1659 transport-layer security (with extra line breaks for display purposes 1660 only): 1662 POST /token HTTP/1.1 1663 Host: server.example.com 1664 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1665 Content-Type: application/x-www-form-urlencoded 1667 grant_type=password&username=johndoe&password=A3ddj3w 1669 The authorization server MUST: 1671 o require client authentication for confidential clients or for any 1672 client that was issued client credentials (or with other 1673 authentication requirements), 1674 o authenticate the client if client authentication is included, and 1675 o validate the resource owner password credentials using its 1676 existing password validation algorithm. 1678 Since this access token request utilizes the resource owner's 1679 password, the authorization server MUST protect the endpoint against 1680 brute force attacks (e.g. using rate-limitation or generating 1681 alerts). 1683 4.3.3. Access Token Response 1685 If the access token request is valid and authorized, the 1686 authorization server issues an access token and optional refresh 1687 token as described in Section 5.1. If the request failed client 1688 authentication or is invalid, the authorization server returns an 1689 error response as described in Section 5.2. 1691 An example successful response: 1693 HTTP/1.1 200 OK 1694 Content-Type: application/json;charset=UTF-8 1695 Cache-Control: no-store 1696 Pragma: no-cache 1698 { 1699 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1700 "token_type":"example", 1701 "expires_in":3600, 1702 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1703 "example_parameter":"example_value" 1704 } 1706 4.4. Client Credentials Grant 1708 The client can request an access token using only its client 1709 credentials (or other supported means of authentication) when the 1710 client is requesting access to the protected resources under its 1711 control, or those of another resource owner that have been previously 1712 arranged with the authorization server (the method of which is beyond 1713 the scope of this specification). 1715 The client credentials grant type MUST only be used by confidential 1716 clients. 1718 +---------+ +---------------+ 1719 | | | | 1720 | |>--(A)- Client Authentication --->| Authorization | 1721 | Client | | Server | 1722 | |<--(B)---- Access Token ---------<| | 1723 | | | | 1724 +---------+ +---------------+ 1726 Figure 6: Client Credentials Flow 1728 The flow illustrated in Figure 6 includes the following steps: 1730 (A) The client authenticates with the authorization server and 1731 requests an access token from the token endpoint. 1732 (B) The authorization server authenticates the client, and if valid 1733 issues an access token. 1735 4.4.1. Authorization Request and Response 1737 Since the client authentication is used as the authorization grant, 1738 no additional authorization request is needed. 1740 4.4.2. Access Token Request 1742 The client makes a request to the token endpoint by adding the 1743 following parameters using the "application/x-www-form-urlencoded" 1744 format per Appendix B with a character encoding of UTF-8 in the HTTP 1745 request entity-body: 1747 grant_type 1748 REQUIRED. Value MUST be set to "client_credentials". 1749 scope 1750 OPTIONAL. The scope of the access request as described by 1751 Section 3.3. 1753 The client MUST authenticate with the authorization server as 1754 described in Section 3.2.1. 1756 For example, the client makes the following HTTP request using 1757 transport-layer security (with extra line breaks for display purposes 1758 only): 1760 POST /token HTTP/1.1 1761 Host: server.example.com 1762 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1763 Content-Type: application/x-www-form-urlencoded 1765 grant_type=client_credentials 1767 The authorization server MUST authenticate the client. 1769 4.4.3. Access Token Response 1771 If the access token request is valid and authorized, the 1772 authorization server issues an access token as described in 1773 Section 5.1. A refresh token SHOULD NOT be included. If the request 1774 failed client authentication or is invalid, the authorization server 1775 returns an error response as described in Section 5.2. 1777 An example successful response: 1779 HTTP/1.1 200 OK 1780 Content-Type: application/json;charset=UTF-8 1781 Cache-Control: no-store 1782 Pragma: no-cache 1784 { 1785 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1786 "token_type":"example", 1787 "expires_in":3600, 1788 "example_parameter":"example_value" 1789 } 1791 4.5. Extension Grants 1793 The client uses an extension grant type by specifying the grant type 1794 using an absolute URI (defined by the authorization server) as the 1795 value of the "grant_type" parameter of the token endpoint, and by 1796 adding any additional parameters necessary. 1798 For example, to request an access token using a SAML 2.0 assertion 1799 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1800 could make the following HTTP request using TLS (with extra line 1801 breaks for display purposes only): 1803 POST /token HTTP/1.1 1804 Host: server.example.com 1805 Content-Type: application/x-www-form-urlencoded 1807 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1808 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1809 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1811 If the access token request is valid and authorized, the 1812 authorization server issues an access token and optional refresh 1813 token as described in Section 5.1. If the request failed client 1814 authentication or is invalid, the authorization server returns an 1815 error response as described in Section 5.2. 1817 5. Issuing an Access Token 1819 If the access token request is valid and authorized, the 1820 authorization server issues an access token and optional refresh 1821 token as described in Section 5.1. If the request failed client 1822 authentication or is invalid, the authorization server returns an 1823 error response as described in Section 5.2. 1825 5.1. Successful Response 1827 The authorization server issues an access token and optional refresh 1828 token, and constructs the response by adding the following parameters 1829 to the entity body of the HTTP response with a 200 (OK) status code: 1831 access_token 1832 REQUIRED. The access token issued by the authorization server. 1833 token_type 1834 REQUIRED. The type of the token issued as described in 1835 Section 7.1. Value is case insensitive. 1836 expires_in 1837 RECOMMENDED. The lifetime in seconds of the access token. For 1838 example, the value "3600" denotes that the access token will 1839 expire in one hour from the time the response was generated. 1840 If omitted, the authorization server SHOULD provide the 1841 expiration time via other means or document the default value. 1842 refresh_token 1843 OPTIONAL. The refresh token, which can be used to obtain new 1844 access tokens using the same authorization grant as described 1845 in Section 6. 1846 scope 1847 OPTIONAL, if identical to the scope requested by the client, 1848 otherwise REQUIRED. The scope of the access token as described 1849 by Section 3.3. 1851 The parameters are included in the entity body of the HTTP response 1852 using the "application/json" media type as defined by [RFC4627]. The 1853 parameters are serialized into a JSON structure by adding each 1854 parameter at the highest structure level. Parameter names and string 1855 values are included as JSON strings. Numerical values are included 1856 as JSON numbers. The order of parameters does not matter and can 1857 vary. 1859 The authorization server MUST include the HTTP "Cache-Control" 1860 response header field [RFC2616] with a value of "no-store" in any 1861 response containing tokens, credentials, or other sensitive 1862 information, as well as the "Pragma" response header field [RFC2616] 1863 with a value of "no-cache". 1865 For example: 1867 HTTP/1.1 200 OK 1868 Content-Type: application/json;charset=UTF-8 1869 Cache-Control: no-store 1870 Pragma: no-cache 1872 { 1873 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1874 "token_type":"example", 1875 "expires_in":3600, 1876 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1877 "example_parameter":"example_value" 1878 } 1880 The client MUST ignore unrecognized value names in the response. The 1881 sizes of tokens and other values received from the authorization 1882 server are left undefined. The client should avoid making 1883 assumptions about value sizes. The authorization server SHOULD 1884 document the size of any value it issues. 1886 5.2. Error Response 1888 The authorization server responds with an HTTP 400 (Bad Request) 1889 status code (unless specified otherwise) and includes the following 1890 parameters with the response: 1892 error 1893 REQUIRED. A single ASCII [USASCII] error code from the 1894 following: 1895 invalid_request 1896 The request is missing a required parameter, includes an 1897 unsupported parameter value (other than grant type), 1898 repeats a parameter, includes multiple credentials, 1899 utilizes more than one mechanism for authenticating the 1900 client, or is otherwise malformed. 1901 invalid_client 1902 Client authentication failed (e.g. unknown client, no 1903 client authentication included, or unsupported 1904 authentication method). The authorization server MAY 1905 return an HTTP 401 (Unauthorized) status code to indicate 1906 which HTTP authentication schemes are supported. If the 1907 client attempted to authenticate via the "Authorization" 1908 request header field, the authorization server MUST 1909 respond with an HTTP 401 (Unauthorized) status code, and 1910 include the "WWW-Authenticate" response header field 1911 matching the authentication scheme used by the client. 1912 invalid_grant 1913 The provided authorization grant (e.g. authorization 1914 code, resource owner credentials) or refresh token is 1915 invalid, expired, revoked, does not match the redirection 1916 URI used in the authorization request, or was issued to 1917 another client. 1918 unauthorized_client 1919 The authenticated client is not authorized to use this 1920 authorization grant type. 1921 unsupported_grant_type 1922 The authorization grant type is not supported by the 1923 authorization server. 1924 invalid_scope 1925 The requested scope is invalid, unknown, malformed, or 1926 exceeds the scope granted by the resource owner. 1927 Values for the "error" parameter MUST NOT include characters 1928 outside the set %x20-21 / %x23-5B / %x5D-7E. 1929 error_description 1930 OPTIONAL. A human-readable ASCII [USASCII] text providing 1931 additional information, used to assist the client developer in 1932 understanding the error that occurred. 1933 Values for the "error_description" parameter MUST NOT include 1934 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1935 error_uri 1936 OPTIONAL. A URI identifying a human-readable web page with 1937 information about the error, used to provide the client 1938 developer with additional information about the error. 1939 Values for the "error_uri" parameter MUST conform to the URI- 1940 Reference syntax, and thus MUST NOT include characters outside 1941 the set %x21 / %x23-5B / %x5D-7E. 1943 The parameters are included in the entity body of the HTTP response 1944 using the "application/json" media type as defined by [RFC4627]. The 1945 parameters are serialized into a JSON structure by adding each 1946 parameter at the highest structure level. Parameter names and string 1947 values are included as JSON strings. Numerical values are included 1948 as JSON numbers. The order of parameters does not matter and can 1949 vary. 1951 For example: 1953 HTTP/1.1 400 Bad Request 1954 Content-Type: application/json;charset=UTF-8 1955 Cache-Control: no-store 1956 Pragma: no-cache 1958 { 1959 "error":"invalid_request" 1960 } 1962 6. Refreshing an Access Token 1964 If the authorization server issued a refresh token to the client, the 1965 client makes a refresh request to the token endpoint by adding the 1966 following parameters using the "application/x-www-form-urlencoded" 1967 format per Appendix B with a character encoding of UTF-8 in the HTTP 1968 request entity-body: 1970 grant_type 1971 REQUIRED. Value MUST be set to "refresh_token". 1972 refresh_token 1973 REQUIRED. The refresh token issued to the client. 1974 scope 1975 OPTIONAL. The scope of the access request as described by 1976 Section 3.3. The requested scope MUST NOT include any scope 1977 not originally granted by the resource owner, and if omitted is 1978 treated as equal to the scope originally granted by the 1979 resource owner. 1981 Because refresh tokens are typically long-lasting credentials used to 1982 request additional access tokens, the refresh token is bound to the 1983 client to which it was issued. If the client type is confidential or 1984 the client was issued client credentials (or assigned other 1985 authentication requirements), the client MUST authenticate with the 1986 authorization server as described in Section 3.2.1. 1988 For example, the client makes the following HTTP request using 1989 transport-layer security (with extra line breaks for display purposes 1990 only): 1992 POST /token HTTP/1.1 1993 Host: server.example.com 1994 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1995 Content-Type: application/x-www-form-urlencoded 1997 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1999 The authorization server MUST: 2001 o require client authentication for confidential clients or for any 2002 client that was issued client credentials (or with other 2003 authentication requirements), 2004 o authenticate the client if client authentication is included and 2005 ensure the refresh token was issued to the authenticated client, 2006 and 2007 o validate the refresh token. 2009 If valid and authorized, the authorization server issues an access 2010 token as described in Section 5.1. If the request failed 2011 verification or is invalid, the authorization server returns an error 2012 response as described in Section 5.2. 2014 The authorization server MAY issue a new refresh token, in which case 2015 the client MUST discard the old refresh token and replace it with the 2016 new refresh token. The authorization server MAY revoke the old 2017 refresh token after issuing a new refresh token to the client. If a 2018 new refresh token is issued, the refresh token scope MUST be 2019 identical to that of the refresh token included by the client in the 2020 request. 2022 7. Accessing Protected Resources 2024 The client accesses protected resources by presenting the access 2025 token to the resource server. The resource server MUST validate the 2026 access token and ensure it has not expired and that its scope covers 2027 the requested resource. The methods used by the resource server to 2028 validate the access token (as well as any error responses) are beyond 2029 the scope of this specification, but generally involve an interaction 2030 or coordination between the resource server and the authorization 2031 server. 2033 The method in which the client utilizes the access token to 2034 authenticate with the resource server depends on the type of access 2035 token issued by the authorization server. Typically, it involves 2036 using the HTTP "Authorization" request header field [RFC2617] with an 2037 authentication scheme defined by the access token type specification. 2039 7.1. Access Token Types 2041 The access token type provides the client with the information 2042 required to successfully utilize the access token to make a protected 2043 resource request (along with type-specific attributes). The client 2044 MUST NOT use an access token if it does not understand the token 2045 type. 2047 For example, the "bearer" token type defined in 2048 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 2049 token string in the request: 2051 GET /resource/1 HTTP/1.1 2052 Host: example.com 2053 Authorization: Bearer mF_9.B5f-4.1JqM 2055 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 2056 utilized by issuing a MAC key together with the access token that is 2057 used to sign certain components of the HTTP requests: 2059 GET /resource/1 HTTP/1.1 2060 Host: example.com 2061 Authorization: MAC id="h480djs93hd8", 2062 nonce="274312:dj83hs9s", 2063 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 2065 The above examples are provided for illustration purposes only. 2066 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 2067 [I-D.ietf-oauth-v2-http-mac] specifications before use. 2069 Each access token type definition specifies the additional attributes 2070 (if any) sent to the client together with the "access_token" response 2071 parameter. It also defines the HTTP authentication method used to 2072 include the access token when making a protected resource request. 2074 7.2. Error Response 2076 If a resource access request fails, the resource server SHOULD inform 2077 the client of the error. While the specifics of such error responses 2078 are beyond the scope of this specification, this documents 2079 establishes a common registry in Section 11.4 for error values to be 2080 shared among OAuth token authentication schemes. 2082 New authentication schemes designed primarily for OAuth token 2083 authentication SHOULD define a mechanism for providing an error 2084 status code to the client, in which the error values allowed are 2085 registered in the error registry established by this specification. 2086 Such schemes MAY limit the set of valid error codes to a subset of 2087 the registered values. If the error code is returned using a named 2088 parameter, the parameter name SHOULD be "error". 2090 Other schemes capable of being used for OAuth token authentication, 2091 but not primarily designed for that purpose, MAY bind their error 2092 values to the registry in the same manner. 2094 New authentication schemes MAY choose to also specify the use of the 2095 "error_description" and "error_uri" parameters to return error 2096 information in a manner parallel to their usage in this 2097 specification. 2099 8. Extensibility 2101 8.1. Defining Access Token Types 2103 Access token types can be defined in one of two ways: registered in 2104 the access token type registry (following the procedures in 2105 Section 11.1), or by using a unique absolute URI as its name. 2107 Types utilizing a URI name SHOULD be limited to vendor-specific 2108 implementations that are not commonly applicable, and are specific to 2109 the implementation details of the resource server where they are 2110 used. 2112 All other types MUST be registered. Type names MUST conform to the 2113 type-name ABNF. If the type definition includes a new HTTP 2114 authentication scheme, the type name SHOULD be identical to the HTTP 2115 authentication scheme name (as defined by [RFC2617]). The token type 2116 "example" is reserved for use in examples. 2118 type-name = 1*name-char 2119 name-char = "-" / "." / "_" / DIGIT / ALPHA 2121 8.2. Defining New Endpoint Parameters 2123 New request or response parameters for use with the authorization 2124 endpoint or the token endpoint are defined and registered in the 2125 parameters registry following the procedure in Section 11.2. 2127 Parameter names MUST conform to the param-name ABNF and parameter 2128 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2129 to the syntax of an existing parameter). 2131 param-name = 1*name-char 2132 name-char = "-" / "." / "_" / DIGIT / ALPHA 2134 Unregistered vendor-specific parameter extensions that are not 2135 commonly applicable, and are specific to the implementation details 2136 of the authorization server where they are used SHOULD utilize a 2137 vendor-specific prefix that is not likely to conflict with other 2138 registered values (e.g. begin with 'companyname_'). 2140 8.3. Defining New Authorization Grant Types 2142 New authorization grant types can be defined by assigning them a 2143 unique absolute URI for use with the "grant_type" parameter. If the 2144 extension grant type requires additional token endpoint parameters, 2145 they MUST be registered in the OAuth parameters registry as described 2146 by Section 11.2. 2148 8.4. Defining New Authorization Endpoint Response Types 2150 New response types for use with the authorization endpoint are 2151 defined and registered in the authorization endpoint response type 2152 registry following the procedure in Section 11.3. Response type 2153 names MUST conform to the response-type ABNF. 2155 response-type = response-name *( SP response-name ) 2156 response-name = 1*response-char 2157 response-char = "_" / DIGIT / ALPHA 2159 If a response type contains one or more space characters (%x20), it 2160 is compared as a space-delimited list of values in which the order of 2161 values does not matter. Only one order of values can be registered, 2162 which covers all other arrangements of the same set of values. 2164 For example, the response type "token code" is left undefined by this 2165 specification. However, an extension can define and register the 2166 "token code" response type. Once registered, the same combination 2167 cannot be registered as "code token", but both values can be used to 2168 denote the same response type. 2170 8.5. Defining Additional Error Codes 2172 In cases where protocol extensions (i.e. access token types, 2173 extension parameters, or extension grant types) require additional 2174 error codes to be used with the authorization code grant error 2175 response (Section 4.1.2.1), the implicit grant error response 2176 (Section 4.2.2.1), the token error response (Section 5.2), or the 2177 resource access error response (Section 7.2), such error codes MAY be 2178 defined. 2180 Extension error codes MUST be registered (following the procedures in 2181 Section 11.4) if the extension they are used in conjunction with is a 2182 registered access token type, a registered endpoint parameter, or an 2183 extension grant type. Error codes used with unregistered extensions 2184 MAY be registered. 2186 Error codes MUST conform to the error ABNF, and SHOULD be prefixed by 2187 an identifying name when possible. For example, an error identifying 2188 an invalid value set to the extension parameter "example" SHOULD be 2189 named "example_invalid". 2191 error = 1*error-char 2192 error-char = %x20-21 / %x23-5B / %x5D-7E 2194 9. Native Applications 2196 Native applications are clients installed and executed on the device 2197 used by the resource owner (i.e. desktop application, native mobile 2198 application). Native applications require special consideration 2199 related to security, platform capabilities, and overall end-user 2200 experience. 2202 The authorization endpoint requires interaction between the client 2203 and the resource owner's user-agent. Native applications can invoke 2204 an external user-agent or embed a user-agent within the application. 2205 For example: 2207 o External user-agent - the native application can capture the 2208 response from the authorization server using a redirection URI 2209 with a scheme registered with the operating system to invoke the 2210 client as the handler, manual copy-and-paste of the credentials, 2211 running a local web server, installing a user-agent extension, or 2212 by providing a redirection URI identifying a server-hosted 2213 resource under the client's control, which in turn makes the 2214 response available to the native application. 2215 o Embedded user-agent - the native application obtains the response 2216 by directly communicating with the embedded user-agent by 2217 monitoring state changes emitted during the resource load, or 2218 accessing the user-agent's cookies storage. 2220 When choosing between an external or embedded user-agent, developers 2221 should consider: 2223 o An External user-agent may improve completion rate as the resource 2224 owner may already have an active session with the authorization 2225 server removing the need to re-authenticate. It provides a 2226 familiar end-user experience and functionality. The resource 2227 owner may also rely on user-agent features or extensions to assist 2228 with authentication (e.g. password manager, 2-factor device 2229 reader). 2230 o An embedded user-agent may offer improved usability, as it removes 2231 the need to switch context and open new windows. 2232 o An embedded user-agent poses a security challenge because resource 2233 owners are authenticating in an unidentified window without access 2234 to the visual protections found in most external user-agents. An 2235 embedded user-agent educates end-users to trust unidentified 2236 requests for authentication (making phishing attacks easier to 2237 execute). 2239 When choosing between the implicit grant type and the authorization 2240 code grant type, the following should be considered: 2242 o Native applications that use the authorization code grant type 2243 SHOULD do so without using client credentials, due to the native 2244 application's inability to keep client credentials confidential. 2245 o When using the implicit grant type flow, a refresh token is not 2246 returned, which requires repeating the authorization process once 2247 the access token expires. 2249 10. Security Considerations 2251 As a flexible and extensible framework, OAuth's security 2252 considerations depend on many factors. The following sections 2253 provide implementers with security guidelines focused on the three 2254 client profiles described in Section 2.1: web application, user- 2255 agent-based application, and native application. 2257 A comprehensive OAuth security model and analysis, as well as 2258 background for the protocol design, is provided by 2259 [I-D.ietf-oauth-v2-threatmodel]. 2261 10.1. Client Authentication 2263 The authorization server establishes client credentials with web 2264 application clients for the purpose of client authentication. The 2265 authorization server is encouraged to consider stronger client 2266 authentication means than a client password. Web application clients 2267 MUST ensure confidentiality of client passwords and other client 2268 credentials. 2270 The authorization server MUST NOT issue client passwords or other 2271 client credentials to native application or user-agent-based 2272 application clients for the purpose of client authentication. The 2273 authorization server MAY issue a client password or other credentials 2274 for a specific installation of a native application client on a 2275 specific device. 2277 When client authentication is not possible, the authorization server 2278 SHOULD employ other means to validate the client's identity. For 2279 example, by requiring the registration of the client redirection URI 2280 or enlisting the resource owner to confirm identity. A valid 2281 redirection URI is not sufficient to verify the client's identity 2282 when asking for resource owner authorization, but can be used to 2283 prevent delivering credentials to a counterfeit client after 2284 obtaining resource owner authorization. 2286 The authorization server must consider the security implications of 2287 interacting with unauthenticated clients and take measures to limit 2288 the potential exposure of other credentials (e.g. refresh tokens) 2289 issued to such clients. 2291 10.2. Client Impersonation 2293 A malicious client can impersonate another client and obtain access 2294 to protected resources, if the impersonated client fails to, or is 2295 unable to, keep its client credentials confidential. 2297 The authorization server MUST authenticate the client whenever 2298 possible. If the authorization server cannot authenticate the client 2299 due to the client's nature, the authorization server MUST require the 2300 registration of any redirection URI used for receiving authorization 2301 responses, and SHOULD utilize other means to protect resource owners 2302 from such potentially malicious clients. For example, the 2303 authorization server can engage the resource owner to assist in 2304 identifying the client and its origin. 2306 The authorization server SHOULD enforce explicit resource owner 2307 authentication and provide the resource owner with information about 2308 the client and the requested authorization scope and lifetime. It is 2309 up to the resource owner to review the information in the context of 2310 the current client, and authorize or deny the request. 2312 The authorization server SHOULD NOT process repeated authorization 2313 requests automatically (without active resource owner interaction) 2314 without authenticating the client or relying on other measures to 2315 ensure the repeated request comes from the original client and not an 2316 impersonator. 2318 10.3. Access Tokens 2320 Access token credentials (as well as any confidential access token 2321 attributes) MUST be kept confidential in transit and storage, and 2322 only shared among the authorization server, the resource servers the 2323 access token is valid for, and the client to whom the access token is 2324 issued. Access token credentials MUST only be transmitted using TLS 2325 as described in Section 1.6 with server authentication as defined by 2326 [RFC2818]. 2328 When using the implicit grant type, the access token is transmitted 2329 in the URI fragment, which can expose it to unauthorized parties. 2331 The authorization server MUST ensure that access tokens cannot be 2332 generated, modified, or guessed to produce valid access tokens by 2333 unauthorized parties. 2335 The client SHOULD request access tokens with the minimal scope 2336 necessary. The authorization server SHOULD take the client identity 2337 into account when choosing how to honor the requested scope, and MAY 2338 issue an access token with a less rights than requested. 2340 This specification does not provide any methods for the resource 2341 server to ensure that an access token presented to it by a given 2342 client was issued to that client by the authorization server. 2344 10.4. Refresh Tokens 2346 Authorization servers MAY issue refresh tokens to web application 2347 clients and native application clients. 2349 Refresh tokens MUST be kept confidential in transit and storage, and 2350 shared only among the authorization server and the client to whom the 2351 refresh tokens were issued. The authorization server MUST maintain 2352 the binding between a refresh token and the client to whom it was 2353 issued. Refresh tokens MUST only be transmitted using TLS as 2354 described in Section 1.6 with server authentication as defined by 2355 [RFC2818]. 2357 The authorization server MUST verify the binding between the refresh 2358 token and client identity whenever the client identity can be 2359 authenticated. When client authentication is not possible, the 2360 authorization server SHOULD deploy other means to detect refresh 2361 token abuse. 2363 For example, the authorization server could employ refresh token 2364 rotation in which a new refresh token is issued with every access 2365 token refresh response. The previous refresh token is invalidated 2366 but retained by the authorization server. If a refresh token is 2367 compromised and subsequently used by both the attacker and the 2368 legitimate client, one of them will present an invalidated refresh 2369 token, which will inform the authorization server of the breach. 2371 The authorization server MUST ensure that refresh tokens cannot be 2372 generated, modified, or guessed to produce valid refresh tokens by 2373 unauthorized parties. 2375 10.5. Authorization Codes 2377 The transmission of authorization codes SHOULD be made over a secure 2378 channel, and the client SHOULD require the use of TLS with its 2379 redirection URI if the URI identifies a network resource. Since 2380 authorization codes are transmitted via user-agent redirections, they 2381 could potentially be disclosed through user-agent history and HTTP 2382 referrer headers. 2384 Authorization codes operate as plaintext bearer credentials, used to 2385 verify that the resource owner who granted authorization at the 2386 authorization server is the same resource owner returning to the 2387 client to complete the process. Therefore, if the client relies on 2388 the authorization code for its own resource owner authentication, the 2389 client redirection endpoint MUST require the use of TLS. 2391 Authorization codes MUST be short lived and single use. If the 2392 authorization server observes multiple attempts to exchange an 2393 authorization code for an access token, the authorization server 2394 SHOULD attempt to revoke all access tokens already granted based on 2395 the compromised authorization code. 2397 If the client can be authenticated, the authorization servers MUST 2398 authenticate the client and ensure that the authorization code was 2399 issued to the same client. 2401 10.6. Authorization Code Redirection URI Manipulation 2403 When requesting authorization using the authorization code grant 2404 type, the client can specify a redirection URI via the "redirect_uri" 2405 parameter. If an attacker can manipulate the value of the 2406 redirection URI, it can cause the authorization server to redirect 2407 the resource owner user-agent to a URI under the control of the 2408 attacker with the authorization code. 2410 An attacker can create an account at a legitimate client and initiate 2411 the authorization flow. When the attacker's user-agent is sent to 2412 the authorization server to grant access, the attacker grabs the 2413 authorization URI provided by the legitimate client, and replaces the 2414 client's redirection URI with a URI under the control of the 2415 attacker. The attacker then tricks the victim into following the 2416 manipulated link to authorize access to the legitimate client. 2418 Once at the authorization server, the victim is prompted with a 2419 normal, valid request on behalf of a legitimate and trusted client, 2420 and authorizes the request. The victim is then redirected to an 2421 endpoint under the control of the attacker with the authorization 2422 code. The attacker completes the authorization flow by sending the 2423 authorization code to the client using the original redirection URI 2424 provided by the client. The client exchanges the authorization code 2425 with an access token and links it to the attacker's client account, 2426 which can now gain access to the protected resources authorized by 2427 the victim (via the client). 2429 In order to prevent such an attack, the authorization server MUST 2430 ensure that the redirection URI used to obtain the authorization code 2431 is identical to the redirection URI provided when exchanging the 2432 authorization code for an access token. The authorization server 2433 MUST require public clients and SHOULD require confidential clients 2434 to register their redirection URIs. If a redirection URI is provided 2435 in the request, the authorization server MUST validate it against the 2436 registered value. 2438 10.7. Resource Owner Password Credentials 2440 The resource owner password credentials grant type is often used for 2441 legacy or migration reasons. It reduces the overall risk of storing 2442 username and password by the client, but does not eliminate the need 2443 to expose highly privileged credentials to the client. 2445 This grant type carries a higher risk than other grant types because 2446 it maintains the password anti-pattern this protocol seeks to avoid. 2447 The client could abuse the password or the password could 2448 unintentionally be disclosed to an attacker (e.g. via log files or 2449 other records kept by the client). 2451 Additionally, because the resource owner does not have control over 2452 the authorization process (the resource owner involvement ends when 2453 it hands over its credentials to the client), the client can obtain 2454 access tokens with a broader scope than desired by the resource 2455 owner. The authorization server should consider the scope and 2456 lifetime of access tokens issued via this grant type. 2458 The authorization server and client SHOULD minimize use of this grant 2459 type and utilize other grant types whenever possible. 2461 10.8. Request Confidentiality 2463 Access tokens, refresh tokens, resource owner passwords, and client 2464 credentials MUST NOT be transmitted in the clear. Authorization 2465 codes SHOULD NOT be transmitted in the clear. 2467 The "state" and "scope" parameters SHOULD NOT include sensitive 2468 client or resource owner information in plain text as they can be 2469 transmitted over insecure channels or stored insecurely. 2471 10.9. Endpoints Authenticity 2473 In order to prevent man-in-the-middle attacks, the authorization 2474 server MUST require the use of TLS with server authentication as 2475 defined by [RFC2818] for any request sent to the authorization and 2476 token endpoints. The client MUST validate the authorization server's 2477 TLS certificate as defined by [RFC6125], and in accordance with its 2478 requirements for server identity authentication. 2480 10.10. Credentials Guessing Attacks 2482 The authorization server MUST prevent attackers from guessing access 2483 tokens, authorization codes, refresh tokens, resource owner 2484 passwords, and client credentials. 2486 The probability of an attacker guessing generated tokens (and other 2487 credentials not intended for handling by end-users) MUST be less than 2488 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2490 The authorization server MUST utilize other means to protect 2491 credentials intended for end-user usage. 2493 10.11. Phishing Attacks 2495 Wide deployment of this and similar protocols may cause end-users to 2496 become inured to the practice of being redirected to websites where 2497 they are asked to enter their passwords. If end-users are not 2498 careful to verify the authenticity of these websites before entering 2499 their credentials, it will be possible for attackers to exploit this 2500 practice to steal resource owners' passwords. 2502 Service providers should attempt to educate end-users about the risks 2503 phishing attacks pose, and should provide mechanisms that make it 2504 easy for end-users to confirm the authenticity of their sites. 2505 Client developers should consider the security implications of how 2506 they interact with the user-agent (e.g., external, embedded), and the 2507 ability of the end-user to verify the authenticity of the 2508 authorization server. 2510 To reduce the risk of phishing attacks, the authorization servers 2511 MUST require the use of TLS on every endpoint used for end-user 2512 interaction. 2514 10.12. Cross-Site Request Forgery 2516 Cross-site request forgery (CSRF) is an exploit in which an attacker 2517 causes the user-agent of a victim end-user to follow a malicious URI 2518 (e.g. provided to the user-agent as a misleading link, image, or 2519 redirection) to a trusting server (usually established via the 2520 presence of a valid session cookie). 2522 A CSRF attack against the client's redirection URI allows an attacker 2523 to inject their own authorization code or access token, which can 2524 result in the client using an access token associated with the 2525 attacker's protected resources rather than the victim's (e.g. save 2526 the victim's bank account information to a protected resource 2527 controlled by the attacker). 2529 The client MUST implement CSRF protection for its redirection URI. 2530 This is typically accomplished by requiring any request sent to the 2531 redirection URI endpoint to include a value that binds the request to 2532 the user-agent's authenticated state (e.g. a hash of the session 2533 cookie used to authenticate the user-agent). The client SHOULD 2534 utilize the "state" request parameter to deliver this value to the 2535 authorization server when making an authorization request. 2537 Once authorization has been obtained from the end-user, the 2538 authorization server redirects the end-user's user-agent back to the 2539 client with the required binding value contained in the "state" 2540 parameter. The binding value enables the client to verify the 2541 validity of the request by matching the binding value to the user- 2542 agent's authenticated state. The binding value used for CSRF 2543 protection MUST contain a non-guessable value (as described in 2544 Section 10.10), and the user-agent's authenticated state (e.g. 2545 session cookie, HTML5 local storage) MUST be kept in a location 2546 accessible only to the client and the user-agent (i.e., protected by 2547 same-origin policy). 2549 A CSRF attack against the authorization server's authorization 2550 endpoint can result in an attacker obtaining end-user authorization 2551 for a malicious client without involving or alerting the end-user. 2553 The authorization server MUST implement CSRF protection for its 2554 authorization endpoint, and ensure that a malicious client cannot 2555 obtain authorization without the awareness and explicit consent of 2556 the resource owner. 2558 10.13. Clickjacking 2560 In a clickjacking attack, an attacker registers a legitimate client 2561 and then constructs a malicious site in which it loads the 2562 authorization server's authorization endpoint web page in a 2563 transparent iframe overlaid on top of a set of dummy buttons, which 2564 are carefully constructed to be placed directly under important 2565 buttons on the authorization page. When an end-user clicks a 2566 misleading visible button, the end-user is actually clicking an 2567 invisible button on the authorization page (such as an "Authorize" 2568 button). This allows an attacker to trick a resource owner into 2569 granting its client access without their knowledge. 2571 To prevent this form of attack, native applications SHOULD use 2572 external browsers instead of embedding browsers within the 2573 application when requesting end-user authorization. For most newer 2574 browsers, avoidance of iframes can be enforced by the authorization 2575 server using the (non-standard) "x-frame-options" header. This 2576 header can have two values, "deny" and "sameorigin", which will block 2577 any framing, or framing by sites with a different origin, 2578 respectively. For older browsers, JavaScript framebusting techniques 2579 can be used but may not be effective in all browsers. 2581 10.14. Code Injection and Input Validation 2583 A code injection attack occurs when an input or otherwise external 2584 variable is used by an application unsanitized and causes 2585 modification to the application logic. This may allow an attacker to 2586 gain access to the application device or its data, cause denial of 2587 service, or a wide range of malicious side-effects. 2589 The Authorization server and client MUST sanitize (and validate when 2590 possible) any value received, in particular, the value of the "state" 2591 and "redirect_uri" parameters. 2593 10.15. Open Redirectors 2595 The authorization server authorization endpoint and the client 2596 redirection endpoint can be improperly configured and operate as open 2597 redirectors. An open redirector is an endpoint using a parameter to 2598 automatically redirect a user-agent to the location specified by the 2599 parameter value without any validation. 2601 Open redirectors can be used in phishing attacks, or by an attacker 2602 to get end-users to visit malicious sites by making the URI's 2603 authority look like a familiar and trusted destination. In addition, 2604 if the authorization server allows the client to register only part 2605 of the redirection URI, an attacker can use an open redirector 2606 operated by the client to construct a redirection URI that will pass 2607 the authorization server validation but will send the authorization 2608 code or access token to an endpoint under the control of the 2609 attacker. 2611 10.16. Misuse of Access Token to Impersonate Resource Owner in Implicit 2612 Flow 2614 For public clients using implicit flows, this specification does not 2615 provide any method for the client to determine what client an access 2616 token was issued to. 2618 A Resource Owner may willingly delegate access to a resource by 2619 granting an access token to an attacker's malicious client. This may 2620 be due to Phishing or some other pretext. An attacker may also steal 2621 a token via some other mechanism. An attacker may then attempt to 2622 impersonate the resource owner by providing the access token to a 2623 legitimate public client. 2625 In the implicit flow (response_type=token), the attacker can easily 2626 switch the token in the response from the authorization server, 2627 replacing the real access_token with the one previously issued to the 2628 attacker. 2630 Servers communicating with native applications that rely on being 2631 passed an access token in the back channel to identify the user of 2632 the client may be similarly compromised by an attacker creating a 2633 compromised application that can inject arbitrary stolen access 2634 tokens. 2636 Any public client that makes the assumption that only the resource 2637 owner can present them with a valid access token for the resource is 2638 vulnerable to this attack. 2640 This attack may expose information about the resource owner at the 2641 legitimate client to the attacker (malicious client). This will also 2642 allow the attacker to perform operations at the legitimate client 2643 with the same permissions as the resource owner who originally 2644 granted the access token or authorization code. 2646 Authenticating Resource Owners to clients is out of scope for this 2647 specification. Any specification that uses the authorization process 2648 as a form of delegated end-user authentication to the client (e.g. 2649 third-party sign-in service) MUST NOT use the implicit flow without 2650 additional security mechanisms such as audience restricting the 2651 access token that enable the client to determine if the access token 2652 was issued for its use. 2654 11. IANA Considerations 2656 11.1. OAuth Access Token Type Registry 2658 This specification establishes the OAuth access token type registry. 2660 Access token types are registered with a Specification Required 2661 ([RFC5226]) after a two week review period on the [TBD]@ietf.org 2662 mailing list, on the advice of one or more Designated Experts. 2663 However, to allow for the allocation of values prior to publication, 2664 the Designated Expert(s) may approve registration once they are 2665 satisfied that such a specification will be published. 2667 Registration requests must be sent to the [TBD]@ietf.org mailing list 2668 for review and comment, with an appropriate subject (e.g., "Request 2669 for access token type: example"). [[ Note to RFC-EDITOR: The name of 2670 the mailing list should be determined in consultation with the IESG 2671 and IANA. Suggested name: oauth-ext-review. ]] 2673 Within the review period, the Designated Expert(s) will either 2674 approve or deny the registration request, communicating this decision 2675 to the review list and IANA. Denials should include an explanation 2676 and, if applicable, suggestions as to how to make the request 2677 successful. 2679 IANA must only accept registry updates from the Designated Expert(s), 2680 and should direct all requests for registration to the review mailing 2681 list. 2683 11.1.1. Registration Template 2685 Type name: 2686 The name requested (e.g., "example"). 2687 Additional Token Endpoint Response Parameters: 2688 Additional response parameters returned together with the 2689 "access_token" parameter. New parameters MUST be separately 2690 registered in the OAuth parameters registry as described by 2691 Section 11.2. 2692 HTTP Authentication Scheme(s): 2693 The HTTP authentication scheme name(s), if any, used to 2694 authenticate protected resources requests using access tokens of 2695 this type. 2696 Change controller: 2697 For standards-track RFCs, state "IETF". For others, give the name 2698 of the responsible party. Other details (e.g., postal address, 2699 e-mail address, home page URI) may also be included. 2700 Specification document(s): 2701 Reference to the document that specifies the parameter, preferably 2702 including a URI that can be used to retrieve a copy of the 2703 document. An indication of the relevant sections may also be 2704 included, but is not required. 2706 11.2. OAuth Parameters Registry 2708 This specification establishes the OAuth parameters registry. 2710 Additional parameters for inclusion in the authorization endpoint 2711 request, the authorization endpoint response, the token endpoint 2712 request, or the token endpoint response are registered with a 2713 Specification Required ([RFC5226]) after a two week review period on 2714 the [TBD]@ietf.org mailing list, on the advice of one or more 2715 Designated Experts. However, to allow for the allocation of values 2716 prior to publication, the Designated Expert(s) may approve 2717 registration once they are satisfied that such a specification will 2718 be published. 2720 Registration requests must be sent to the [TBD]@ietf.org mailing list 2721 for review and comment, with an appropriate subject (e.g., "Request 2722 for parameter: example"). [[ Note to RFC-EDITOR: The name of the 2723 mailing list should be determined in consultation with the IESG and 2724 IANA. Suggested name: oauth-ext-review. ]] 2726 Within the review period, the Designated Expert(s) will either 2727 approve or deny the registration request, communicating this decision 2728 to the review list and IANA. Denials should include an explanation 2729 and, if applicable, suggestions as to how to make the request 2730 successful. 2732 IANA must only accept registry updates from the Designated Expert(s), 2733 and should direct all requests for registration to the review mailing 2734 list. 2736 11.2.1. Registration Template 2738 Parameter name: 2739 The name requested (e.g., "example"). 2740 Parameter usage location: 2741 The location(s) where parameter can be used. The possible 2742 locations are: authorization request, authorization response, 2743 token request, or token response. 2744 Change controller: 2745 For standards-track RFCs, state "IETF". For others, give the name 2746 of the responsible party. Other details (e.g., postal address, 2747 e-mail address, home page URI) may also be included. 2748 Specification document(s): 2749 Reference to the document that specifies the parameter, preferably 2750 including a URI that can be used to retrieve a copy of the 2751 document. An indication of the relevant sections may also be 2752 included, but is not required. 2754 11.2.2. Initial Registry Contents 2756 The OAuth Parameters Registry's initial contents are: 2758 o Parameter name: client_id 2759 o Parameter usage location: authorization request, token request 2760 o Change controller: IETF 2761 o Specification document(s): [[ this document ]] 2763 o Parameter name: client_secret 2764 o Parameter usage location: token request 2765 o Change controller: IETF 2766 o Specification document(s): [[ this document ]] 2768 o Parameter name: response_type 2769 o Parameter usage location: authorization request 2770 o Change controller: IETF 2771 o Specification document(s): [[ this document ]] 2773 o Parameter name: redirect_uri 2774 o Parameter usage location: authorization request, token request 2775 o Change controller: IETF 2776 o Specification document(s): [[ this document ]] 2778 o Parameter name: scope 2779 o Parameter usage location: authorization request, authorization 2780 response, token request, token response 2781 o Change controller: IETF 2782 o Specification document(s): [[ this document ]] 2784 o Parameter name: state 2785 o Parameter usage location: authorization request, authorization 2786 response 2787 o Change controller: IETF 2788 o Specification document(s): [[ this document ]] 2790 o Parameter name: code 2791 o Parameter usage location: authorization response, token request 2792 o Change controller: IETF 2793 o Specification document(s): [[ this document ]] 2795 o Parameter name: error_description 2796 o Parameter usage location: authorization response, token response 2797 o Change controller: IETF 2798 o Specification document(s): [[ this document ]] 2800 o Parameter name: error_uri 2801 o Parameter usage location: authorization response, token response 2802 o Change controller: IETF 2803 o Specification document(s): [[ this document ]] 2805 o Parameter name: grant_type 2806 o Parameter usage location: token request 2807 o Change controller: IETF 2808 o Specification document(s): [[ this document ]] 2810 o Parameter name: access_token 2811 o Parameter usage location: authorization response, token response 2812 o Change controller: IETF 2813 o Specification document(s): [[ this document ]] 2815 o Parameter name: token_type 2816 o Parameter usage location: authorization response, token response 2817 o Change controller: IETF 2818 o Specification document(s): [[ this document ]] 2820 o Parameter name: expires_in 2821 o Parameter usage location: authorization response, token response 2822 o Change controller: IETF 2823 o Specification document(s): [[ this document ]] 2825 o Parameter name: username 2826 o Parameter usage location: token request 2827 o Change controller: IETF 2828 o Specification document(s): [[ this document ]] 2830 o Parameter name: password 2831 o Parameter usage location: token request 2832 o Change controller: IETF 2833 o Specification document(s): [[ this document ]] 2835 o Parameter name: refresh_token 2836 o Parameter usage location: token request, token response 2837 o Change controller: IETF 2838 o Specification document(s): [[ this document ]] 2840 11.3. OAuth Authorization Endpoint Response Type Registry 2842 This specification establishes the OAuth authorization endpoint 2843 response type registry. 2845 Additional response type for use with the authorization endpoint are 2846 registered with a Specification Required ([RFC5226]) after a two week 2847 review period on the [TBD]@ietf.org mailing list, on the advice of 2848 one or more Designated Experts. However, to allow for the allocation 2849 of values prior to publication, the Designated Expert(s) may approve 2850 registration once they are satisfied that such a specification will 2851 be published. 2853 Registration requests must be sent to the [TBD]@ietf.org mailing list 2854 for review and comment, with an appropriate subject (e.g., "Request 2855 for response type: example"). [[ Note to RFC-EDITOR: The name of the 2856 mailing list should be determined in consultation with the IESG and 2857 IANA. Suggested name: oauth-ext-review. ]] 2859 Within the review period, the Designated Expert(s) will either 2860 approve or deny the registration request, communicating this decision 2861 to the review list and IANA. Denials should include an explanation 2862 and, if applicable, suggestions as to how to make the request 2863 successful. 2865 IANA must only accept registry updates from the Designated Expert(s), 2866 and should direct all requests for registration to the review mailing 2867 list. 2869 11.3.1. Registration Template 2871 Response type name: 2872 The name requested (e.g., "example"). 2873 Change controller: 2874 For standards-track RFCs, state "IETF". For others, give the name 2875 of the responsible party. Other details (e.g., postal address, 2876 e-mail address, home page URI) may also be included. 2877 Specification document(s): 2878 Reference to the document that specifies the type, preferably 2879 including a URI that can be used to retrieve a copy of the 2880 document. An indication of the relevant sections may also be 2881 included, but is not required. 2883 11.3.2. Initial Registry Contents 2885 The OAuth Authorization Endpoint Response Type Registry's initial 2886 contents are: 2888 o Response type name: code 2889 o Change controller: IETF 2890 o Specification document(s): [[ this document ]] 2892 o Response type name: token 2893 o Change controller: IETF 2894 o Specification document(s): [[ this document ]] 2896 11.4. OAuth Extensions Error Registry 2898 This specification establishes the OAuth extensions error registry. 2900 Additional error codes used together with other protocol extensions 2901 (i.e. extension grant types, access token types, or extension 2902 parameters) are registered with a Specification Required ([RFC5226]) 2903 after a two week review period on the [TBD]@ietf.org mailing list, on 2904 the advice of one or more Designated Experts. However, to allow for 2905 the allocation of values prior to publication, the Designated 2906 Expert(s) may approve registration once they are satisfied that such 2907 a specification will be published. 2909 Registration requests must be sent to the [TBD]@ietf.org mailing list 2910 for review and comment, with an appropriate subject (e.g., "Request 2911 for error code: example"). [[ Note to RFC-EDITOR: The name of the 2912 mailing list should be determined in consultation with the IESG and 2913 IANA. Suggested name: oauth-ext-review. ]] 2915 Within the review period, the Designated Expert(s) will either 2916 approve or deny the registration request, communicating this decision 2917 to the review list and IANA. Denials should include an explanation 2918 and, if applicable, suggestions as to how to make the request 2919 successful. 2921 IANA must only accept registry updates from the Designated Expert(s), 2922 and should direct all requests for registration to the review mailing 2923 list. 2925 11.4.1. Registration Template 2927 Error name: 2928 The name requested (e.g., "example"). Values for the error name 2929 MUST NOT include characters outside the set %x20-21 / %x23-5B / 2930 %x5D-7E. 2931 Error usage location: 2932 The location(s) where the error can be used. The possible 2933 locations are: authorization code grant error response 2934 (Section 4.1.2.1), implicit grant error response 2935 (Section 4.2.2.1), token error response (Section 5.2), or resource 2936 access error response (Section 7.2). 2937 Related protocol extension: 2938 The name of the extension grant type, access token type, or 2939 extension parameter, the error code is used in conjunction with. 2940 Change controller: 2941 For standards-track RFCs, state "IETF". For others, give the name 2942 of the responsible party. Other details (e.g., postal address, 2943 e-mail address, home page URI) may also be included. 2944 Specification document(s): 2945 Reference to the document that specifies the error code, 2946 preferably including a URI that can be used to retrieve a copy of 2947 the document. An indication of the relevant sections may also be 2948 included, but is not required. 2950 12. References 2952 12.1. Normative References 2954 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2955 Requirement Levels", BCP 14, RFC 2119, March 1997. 2957 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2958 RFC 2246, January 1999. 2960 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2961 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2962 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2964 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2965 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2966 Authentication: Basic and Digest Access Authentication", 2967 RFC 2617, June 1999. 2969 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2971 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2972 10646", STD 63, RFC 3629, November 2003. 2974 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2975 Resource Identifier (URI): Generic Syntax", STD 66, 2976 RFC 3986, January 2005. 2978 [RFC4627] Crockford, D., "The application/json Media Type for 2979 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2981 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2982 RFC 4949, August 2007. 2984 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2985 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2986 May 2008. 2988 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2989 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2991 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2992 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2994 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2995 Verification of Domain-Based Application Service Identity 2996 within Internet Public Key Infrastructure Using X.509 2997 (PKIX) Certificates in the Context of Transport Layer 2998 Security (TLS)", RFC 6125, March 2011. 3000 [USASCII] American National Standards Institute, "Coded Character 3001 Set -- 7-bit American Standard Code for Information 3002 Interchange", ANSI X3.4, 1986. 3004 [W3C.REC-html401-19991224] 3005 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 3006 Specification", World Wide Web Consortium 3007 Recommendation REC-html401-19991224, December 1999, 3008 . 3010 [W3C.REC-xml-20081126] 3011 Sperberg-McQueen, C., Yergeau, F., Paoli, J., Bray, T., 3012 and E. Maler, "Extensible Markup Language (XML) 1.0 (Fifth 3013 Edition)", World Wide Web Consortium Recommendation REC- 3014 xml-20081126, November 2008, 3015 . 3017 12.2. Informative References 3019 [I-D.draft-hardt-oauth-01] 3020 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 3021 Web Resource Authorization Profiles", January 2010. 3023 [I-D.ietf-oauth-saml2-bearer] 3024 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 3025 Profiles for OAuth 2.0", draft-ietf-oauth-saml2-bearer-13 3026 (work in progress), July 2012. 3028 [I-D.ietf-oauth-v2-bearer] 3029 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 3030 Authorization Framework: Bearer Token Usage", 3031 draft-ietf-oauth-v2-bearer-22 (work in progress), 3032 July 2012. 3034 [I-D.ietf-oauth-v2-http-mac] 3035 Hammer-Lahav, E., "HTTP Authentication: MAC Access 3036 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 3037 progress), February 2012. 3039 [I-D.ietf-oauth-v2-threatmodel] 3040 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 3041 Threat Model and Security Considerations", 3042 draft-ietf-oauth-v2-threatmodel-06 (work in progress), 3043 June 2012. 3045 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 3046 April 2010. 3048 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 3050 This section provides Augmented Backus-Naur Form (ABNF) syntax 3051 descriptions for the elements defined in this specification using the 3052 notation of [RFC5234]. The ABNF below is defined in terms of Unicode 3053 code points [W3C.REC-xml-20081126]; these characters are typically 3054 encoded in UTF-8. Elements are presented in the order first defined. 3056 Some of the definitions that follow use the "URI-reference" 3057 definition from [RFC3986]. 3059 Some of the definitions that follow use these common definitions: 3061 VSCHAR = %x20-7E 3062 NQCHAR = %x21 / %x23-5B / %x5D-7E 3063 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 3064 UNICODECHARNOCRLF = %x09 /%x20-7E / %x80-D7FF / 3065 %xE000-FFFD / %x10000-10FFFF 3067 (The UNICODECHARNOCRLF definition is based upon the Char definition 3068 in Section 2.2 of [W3C.REC-xml-20081126], but omitting the Carriage 3069 Return and Linefeed characters.) 3071 A.1. "client_id" Syntax 3073 The "client_id" element is defined in Section 2.3.1: 3075 client-id = *VSCHAR 3077 A.2. "client_secret" Syntax 3079 The "client_secret" element is defined in Section 2.3.1: 3081 client-secret = *VSCHAR 3083 A.3. "response_type" Syntax 3085 The "response_type" element is defined in Section 3.1.1 and 3086 Section 8.4: 3088 response-type = response-name *( SP response-name ) 3089 response-name = 1*response-char 3090 response-char = "_" / DIGIT / ALPHA 3092 A.4. "scope" Syntax 3094 The "scope" element is defined in Section 3.3: 3096 scope = scope-token *( SP scope-token ) 3097 scope-token = 1*NQCHAR 3099 A.5. "state" Syntax 3101 The "state" element is defined in Section 4.1.1, Section 4.1.2, 3102 Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1: 3104 state = 1*VSCHAR 3106 A.6. "redirect_uri" Syntax 3108 The "redirect_uri" element is defined in Section 4.1.1, 3109 Section 4.1.3, and Section 4.2.1: 3111 redirect-uri = URI-reference 3113 A.7. "error" Syntax 3115 The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1, 3116 Section 5.2, Section 7.2, and Section 8.5: 3118 error = 1*NQSCHAR 3120 A.8. "error_description" Syntax 3122 The "error_description" element is defined in Section 4.1.2.1, 3123 Section 4.2.2.1, Section 5.2, and Section 7.2: 3125 error-description = 1*NQSCHAR 3127 A.9. "error_uri" Syntax 3129 The "error_uri" element is defined in Section 4.1.2.1, 3130 Section 4.2.2.1, Section 5.2, and Section 7.2: 3132 error-uri = URI-reference 3134 A.10. "grant_type" Syntax 3136 The "grant_type" element is defined in Section 4.1.3, Section 4.3.2, 3137 Section 4.4.2, Section 6, and Section 4.5: 3139 grant-type = grant-name / URI-reference 3140 grant-name = 1*name-char 3141 name-char = "-" / "." / "_" / DIGIT / ALPHA 3143 A.11. "code" Syntax 3145 The "code" element is defined in Section 4.1.3: 3147 code = 1*VSCHAR 3149 A.12. "access_token" Syntax 3151 The "access_token" element is defined in Section 4.2.2 and 3152 Section 5.1: 3154 access-token = 1*VSCHAR 3156 A.13. "token_type" Syntax 3158 The "token_type" element is defined in Section 4.2.2, Section 5.1, 3159 and Section 8.1: 3161 token-type = type-name / URI-reference 3162 type-name = 1*name-char 3163 name-char = "-" / "." / "_" / DIGIT / ALPHA 3165 A.14. "expires_in" Syntax 3167 The "expires_in" element is defined in Section 4.2.2 and Section 5.1: 3169 expires-in = 1*DIGIT 3171 A.15. "username" Syntax 3173 The "username" element is defined in Section 4.3.2: 3175 username = *UNICODECHARNOCRLF 3177 A.16. "password" Syntax 3179 The "password" element is defined in Section 4.3.2: 3181 password = *UNICODECHARNOCRLF 3183 A.17. "refresh_token" Syntax 3185 The "refresh_token" element is defined in Section 5.1 and Section 6: 3187 refresh-token = 1*VSCHAR 3189 A.18. Endpoint Parameter Syntax 3191 The syntax for new endpoint parameters is defined in Section 8.2: 3193 param-name = 1*name-char 3194 name-char = "-" / "." / "_" / DIGIT / ALPHA 3196 Appendix B. Use of application/x-www-form-urlencoded Media Type 3198 At the time of publication of this specification, the 3199 "application/x-www-form-urlencoded" media type was defined in Section 3200 17.13.4 of [W3C.REC-html401-19991224], but not registered in the IANA 3201 media types registry 3202 (). 3203 Furthermore, that definition is incomplete, as it does not consider 3204 non-US-ASCII characters. 3206 To address this shortcoming when generating payloads using this media 3207 type, names and values MUST be encoded using the UTF-8 character 3208 encoding scheme [RFC3629] first; the resulting octet sequence then 3209 needs to be further encoded using the escaping rules defined in 3210 [W3C.REC-html401-19991224]. 3212 When parsing data from a payload using this media type, the names and 3213 values resulting from reversing the name/value encoding consequently 3214 need to be treated as octet sequences, to be decoded using the UTF-8 3215 character encoding scheme. 3217 For example, the value consisting of the six Unicode code points (1) 3218 U+0020 (SPACE), (2) U+0025 (PERCENT SIGN), (3) U+0026 (AMPERSAND), 3219 (4) U+002B (PLUS SIGN), (5) U+00A3 (POUND SIGN), and (6) U+20AC (EURO 3220 SIGN) would be encoded into the octet sequence below (using 3221 hexadecimal notation): 3223 20 25 26 2B C2 A3 E2 82 AC 3225 and then represented in the payload as: 3227 +%25%26%2B%C2%A3%E2%82%AC 3229 Appendix C. Acknowledgements 3231 The initial OAuth 2.0 protocol specification was edited by David 3232 Recordon, based on two previous publications: the OAuth 1.0 community 3233 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 3234 Authorization Profiles) [I-D.draft-hardt-oauth-01]. Eran Hammer then 3235 edited the drafts through draft -26. The Security Considerations 3236 section was drafted by Torsten Lodderstedt, Mark McGloin, Phil Hunt, 3237 Anthony Nadalin, and John Bradley. The section on use of the 3238 application/x-www-form-urlencoded media type was drafted by Julian 3239 Reschke. The ABNF section was drafted by Michael B. Jones. 3241 The OAuth 1.0 community specification was edited by Eran Hammer and 3242 authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 3243 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 3244 Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 3245 Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 3246 Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 3248 The OAuth WRAP specification was edited by Dick Hardt and authored by 3249 Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. 3251 This specification is the work of the OAuth Working Group, which 3252 includes dozens of active and dedicated participants. In particular, 3253 the following individuals contributed ideas, feedback, and wording 3254 that shaped and formed the final specification: 3256 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 3257 Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres, 3258 Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill 3259 de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin, 3260 Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan 3261 Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Eran 3262 Hammer, Justin Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. 3263 Jones, Terry Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le 3264 Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, 3265 Paul Madsen, Alastair Mair, Eve Maler, James Manger, Mark McGloin, 3266 Laurence Miao, William Mills, Chuck Mortimore, Anthony Nadalin, 3267 Julian Reschke, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob 3268 Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, 3269 Justin Smith, Haibin Song, Niv Steingarten, Christian Stuebner, 3270 Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. Thompson, 3271 Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar 3272 Woodward. 3274 This document was produced under the chairmanship of Blaine Cook, 3275 Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. 3276 The area directors included Lisa Dusseault, Peter Saint-Andre, and 3277 Stephen Farrell. 3279 Appendix D. Document History 3281 [[ to be removed by the RFC editor before publication as an RFC ]] 3283 -31 3284 o Clarify that any client can send "client_id" but that sending it 3285 is only required when using the code flow if the client is not 3286 otherwise authenticated. 3287 o Removed David Recordon's name from the author list, at his 3288 request. 3290 -30 3291 o Added text explaining why the "server_error" and 3292 "temporarily_unavailable" error codes are needed. 3294 -29 3295 o Added "MUST" to "A public client that was not issued a client 3296 password MUST use the "client_id" request parameter to identify 3297 itself when sending requests to the token endpoint" and added text 3298 explaining why this must be so. 3299 o Added that the authorization server MUST "ensure the authorization 3300 code was issued to the authenticated confidential client or to the 3301 public client identified by the "client_id" in the request". 3302 o Added Security Considerations section "Misuse of Access Token to 3303 Impersonate Resource Owner in Implicit Flow". 3304 o Added references in the "Implicit" and "Implicit Grant" sections 3305 to particularly pertinent security considerations. 3306 o Added appendix "Use of application/x-www-form-urlencoded Media 3307 Type" and referenced it in places that this encoding is used. 3308 o Deleted ";charset=UTF-8" from examples formerly using "Content- 3309 Type: application/x-www-form-urlencoded;charset=UTF-8". 3310 o Added the phrase "with a character encoding of UTF-8" when 3311 describing how to send requests using the HTTP request entity- 3312 body. 3313 o For symmetry when using HTTP Basic authentication, also apply the 3314 "application/x-www-form-urlencoded" encoding to the client 3315 password, just as was already done for the client identifier. 3316 o Added "The ABNF below is defined in terms of Unicode code points 3317 [W3C.REC-xml-20081126]; these characters are typically encoded in 3318 UTF-8". 3320 o Replaced UNICODENOCTRLCHAR in ABNF with UNICODECHARNOCRLF = %x09 / 3321 %x20-7E / %x80-D7FF / %xE000-FFFD / %x10000-10FFFF. 3322 o Corrected incorrect uses of "which". 3323 o Reduced multiple blank lines around artwork elements to single 3324 blank lines. 3325 o Removed Eran Hammer's name from the author list, at his request. 3326 Dick Hardt is now listed as the editor. 3328 -28 3329 o Updated the ABNF in the manner discussed by the working group, 3330 allowing "username" and "password" to be Unicode and restricting 3331 "client_id" and "client_secret" to ASCII. 3332 o Specified the use of the application/x-www-form-urlencoded 3333 content-type encoding method to encode the "client_id" when used 3334 as the password for HTTP Basic. 3336 -27 3337 o Added character set restrictions for error, error_description, and 3338 error_uri parameters consistent with the OAuth Bearer spec. 3339 o Added "resource access error response" as an error usage location 3340 in the OAuth Extensions Error Registry. 3341 o Added an ABNF for all message elements. 3342 o Corrected editorial issues identified during review. 3344 Author's Address 3346 Dick Hardt (editor) 3347 Microsoft 3349 Email: dick.hardt@gmail.com 3350 URI: http://dickhardt.org/