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