idnits 2.17.1 draft-ietf-oauth-v2-27.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 (June 8, 2012) is 4340 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 2594, but not defined == Unused Reference: 'I-D.ietf-httpbis-p7-auth' is defined on line 2944, but no explicit reference was found in the text ** 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 (-26) exists of draft-ietf-httpbis-p7-auth-19 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-12 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-v2-bearer-19 == 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-02 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 9 errors (**), 0 flaws (~~), 9 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OAuth Working Group E. Hammer, Ed. 3 Internet-Draft 4 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: December 10, 2012 D. Hardt 7 Microsoft 8 June 8, 2012 10 The OAuth 2.0 Authorization Framework 11 draft-ietf-oauth-v2-27 13 Abstract 15 The OAuth 2.0 authorization framework enables a third-party 16 application to obtain limited access to an HTTP service, either on 17 behalf of a resource owner by orchestrating an approval interaction 18 between the resource owner and the HTTP service, or by allowing the 19 third-party application to obtain access on its own behalf. This 20 specification replaces and obsoletes the OAuth 1.0 protocol described 21 in RFC 5849. 23 Status of this Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on December 10, 2012. 40 Copyright Notice 42 Copyright (c) 2012 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 7 60 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 8 61 1.3.1. Authorization Code . . . . . . . . . . . . . . . . . . 8 62 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 63 1.3.3. Resource Owner Password Credentials . . . . . . . . . 9 64 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 9 65 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 66 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 10 67 1.6. TLS Version . . . . . . . . . . . . . . . . . . . . . . . 12 68 1.7. HTTP Redirections . . . . . . . . . . . . . . . . . . . . 12 69 1.8. Interoperability . . . . . . . . . . . . . . . . . . . . 12 70 1.9. Notational Conventions . . . . . . . . . . . . . . . . . 13 71 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 13 72 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 14 73 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 15 74 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15 75 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 16 76 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 17 77 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 17 78 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 17 79 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 80 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 81 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 19 82 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 21 83 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 84 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 22 85 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 23 86 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 23 87 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24 88 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 25 89 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 27 90 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 28 91 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 29 92 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 31 93 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 32 94 4.3. Resource Owner Password Credentials Grant . . . . . . . . 35 95 4.3.1. Authorization Request and Response . . . . . . . . . . 36 96 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 36 97 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 37 98 4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 37 99 4.4.1. Authorization Request and Response . . . . . . . . . . 38 100 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 38 101 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 39 102 4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 39 103 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 40 104 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 40 105 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 41 106 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 43 107 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 44 108 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 45 109 7.2. Error Response . . . . . . . . . . . . . . . . . . . . . 46 110 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 46 111 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 46 112 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 47 113 8.3. Defining New Authorization Grant Types . . . . . . . . . 47 114 8.4. Defining New Authorization Endpoint Response Types . . . 47 115 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 48 116 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 48 117 10. Security Considerations . . . . . . . . . . . . . . . . . . . 50 118 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 50 119 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 50 120 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 51 121 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 52 122 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 52 123 10.6. Authorization Code Redirection URI Manipulation . . . . . 53 124 10.7. Resource Owner Password Credentials . . . . . . . . . . . 54 125 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 54 126 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 54 127 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 54 128 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 55 129 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 55 130 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 56 131 10.14. Code Injection and Input Validation . . . . . . . . . . . 57 132 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 57 133 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 57 134 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 57 135 11.1.1. Registration Template . . . . . . . . . . . . . . . . 58 136 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 58 137 11.2.1. Registration Template . . . . . . . . . . . . . . . . 59 138 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 59 139 11.3. The OAuth Authorization Endpoint Response Type 140 Registry . . . . . . . . . . . . . . . . . . . . . . . . 61 141 11.3.1. Registration Template . . . . . . . . . . . . . . . . 62 142 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 62 143 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 62 144 11.4.1. Registration Template . . . . . . . . . . . . . . . . 63 145 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 63 146 12.1. Normative References . . . . . . . . . . . . . . . . . . 63 147 12.2. Informative References . . . . . . . . . . . . . . . . . 65 148 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax . . . . . . 65 149 A.1. "client_id" Syntax . . . . . . . . . . . . . . . . . . . 66 150 A.2. "client_secret" Syntax . . . . . . . . . . . . . . . . . 66 151 A.3. "response_type" Syntax . . . . . . . . . . . . . . . . . 66 152 A.4. "scope" Syntax . . . . . . . . . . . . . . . . . . . . . 66 153 A.5. "state" Syntax . . . . . . . . . . . . . . . . . . . . . 66 154 A.6. "redirect_uri" Syntax . . . . . . . . . . . . . . . . . . 67 155 A.7. "error" Syntax . . . . . . . . . . . . . . . . . . . . . 67 156 A.8. "error_description" Syntax . . . . . . . . . . . . . . . 67 157 A.9. "error_uri" Syntax . . . . . . . . . . . . . . . . . . . 67 158 A.10. "grant_type" Syntax . . . . . . . . . . . . . . . . . . . 67 159 A.11. "code" Syntax . . . . . . . . . . . . . . . . . . . . . . 67 160 A.12. "access_token" Syntax . . . . . . . . . . . . . . . . . . 68 161 A.13. "token_type" Syntax . . . . . . . . . . . . . . . . . . . 68 162 A.14. "expires_in" Syntax . . . . . . . . . . . . . . . . . . . 68 163 A.15. "username" Syntax . . . . . . . . . . . . . . . . . . . . 68 164 A.16. "password" Syntax . . . . . . . . . . . . . . . . . . . . 68 165 A.17. "refresh_token" Syntax . . . . . . . . . . . . . . . . . 68 166 A.18. Endpoint Parameter Syntax . . . . . . . . . . . . . . . . 69 167 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 69 168 Appendix C. Editor's Notes . . . . . . . . . . . . . . . . . . . 70 169 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 70 171 1. Introduction 173 In the traditional client-server authentication model, the client 174 requests an access restricted resource (protected resource) on the 175 server by authenticating with the server using the resource owner's 176 credentials. In order to provide third-party applications access to 177 restricted resources, the resource owner shares its credentials with 178 the third-party. This creates several problems and limitations: 180 o Third-party applications are required to store the resource 181 owner's credentials for future use, typically a password in clear- 182 text. 183 o Servers are required to support password authentication, despite 184 the security weaknesses inherent in passwords. 185 o Third-party applications gain overly broad access to the resource 186 owner's protected resources, leaving resource owners without any 187 ability to restrict duration or access to a limited subset of 188 resources. 189 o Resource owners cannot revoke access to an individual third-party 190 without revoking access to all third-parties, and must do so by 191 changing their password. 192 o Compromise of any third-party application results in compromise of 193 the end-user's password and all of the data protected by that 194 password. 196 OAuth addresses these issues by introducing an authorization layer 197 and separating the role of the client from that of the resource 198 owner. In OAuth, the client requests access to resources controlled 199 by the resource owner and hosted by the resource server, and is 200 issued a different set of credentials than those of the resource 201 owner. 203 Instead of using the resource owner's credentials to access protected 204 resources, the client obtains an access token - a string denoting a 205 specific scope, lifetime, and other access attributes. Access tokens 206 are issued to third-party clients by an authorization server with the 207 approval of the resource owner. The client uses the access token to 208 access the protected resources hosted by the resource server. 210 For example, an end-user (resource owner) can grant a printing 211 service (client) access to her protected photos stored at a photo 212 sharing service (resource server), without sharing her username and 213 password with the printing service. Instead, she authenticates 214 directly with a server trusted by the photo sharing service 215 (authorization server) which issues the printing service delegation- 216 specific credentials (access token). 218 This specification is designed for use with HTTP ([RFC2616]). The 219 use of OAuth over any other protocol than HTTP is out of scope. 221 The OAuth 1.0 protocol ([RFC5849]), published as an informational 222 document, was the result of a small ad-hoc community effort. This 223 standards-track specification builds on the OAuth 1.0 deployment 224 experience, as well as additional use cases and extensibility 225 requirements gathered from the wider IETF community. The OAuth 2.0 226 protocol is not backward compatible with OAuth 1.0. The two versions 227 may co-exist on the network and implementations may choose to support 228 both. However, it is the intention of this specification that new 229 implementation support OAuth 2.0 as specified in this document, and 230 that OAuth 1.0 is used only to support existing deployments. The 231 OAuth 2.0 protocol shares very few implementation details with the 232 OAuth 1.0 protocol. Implementers familiar with OAuth 1.0 should 233 approach this document without any assumptions as to its structure 234 and details. 236 1.1. Roles 238 OAuth defines four roles: 240 resource owner 241 An entity capable of granting access to a protected resource. 242 When the resource owner is a person, it is referred to as an end- 243 user. 244 resource server 245 The server hosting the protected resources, capable of accepting 246 and responding to protected resource requests using access tokens. 247 client 248 An application making protected resource requests on behalf of the 249 resource owner and with its authorization. The term client does 250 not imply any particular implementation characteristics (e.g. 251 whether the application executes on a server, a desktop, or other 252 devices). 253 authorization server 254 The server issuing access tokens to the client after successfully 255 authenticating the resource owner and obtaining authorization. 257 The interaction between the authorization server and resource server 258 is beyond the scope of this specification. The authorization server 259 may be the same server as the resource server or a separate entity. 260 A single authorization server may issue access tokens accepted by 261 multiple resource servers. 263 1.2. Protocol Flow 265 +--------+ +---------------+ 266 | |--(A)- Authorization Request ->| Resource | 267 | | | Owner | 268 | |<-(B)-- Authorization Grant ---| | 269 | | +---------------+ 270 | | 271 | | +---------------+ 272 | |--(C)-- Authorization Grant -->| Authorization | 273 | Client | | Server | 274 | |<-(D)----- Access Token -------| | 275 | | +---------------+ 276 | | 277 | | +---------------+ 278 | |--(E)----- Access Token ------>| Resource | 279 | | | Server | 280 | |<-(F)--- Protected Resource ---| | 281 +--------+ +---------------+ 283 Figure 1: Abstract Protocol Flow 285 The abstract flow illustrated in Figure 1 describes the interaction 286 between the four roles and includes the following steps: 288 (A) The client requests authorization from the resource owner. The 289 authorization request can be made directly to the resource owner 290 (as shown), or preferably indirectly via the authorization 291 server as an intermediary. 292 (B) The client receives an authorization grant which is a credential 293 representing the resource owner's authorization, expressed using 294 one of four grant types defined in this specification or using 295 an extension grant type. The authorization grant type depends 296 on the method used by the client to request authorization and 297 the types supported by the authorization server. 298 (C) The client requests an access token by authenticating with the 299 authorization server and presenting the authorization grant. 300 (D) The authorization server authenticates the client and validates 301 the authorization grant, and if valid issues an access token. 302 (E) The client requests the protected resource from the resource 303 server and authenticates by presenting the access token. 304 (F) The resource server validates the access token, and if valid, 305 serves the request. 307 The preferred method for the client to obtain an authorization grant 308 from the resource owner (depicted in steps (A) and (B)) is to use the 309 authorization server as an intermediary which is illustrated in 310 Figure 3. 312 1.3. Authorization Grant 314 An authorization grant is a credential representing the resource 315 owner's authorization (to access its protected resources) used by the 316 client to obtain an access token. This specification defines four 317 grant types: authorization code, implicit, resource owner password 318 credentials, and client credentials, as well as an extensibility 319 mechanism for defining additional types. 321 1.3.1. Authorization Code 323 The authorization code is obtained by using an authorization server 324 as an intermediary between the client and resource owner. Instead of 325 requesting authorization directly from the resource owner, the client 326 directs the resource owner to an authorization server (via its user- 327 agent as defined in [RFC2616]), which in turn directs the resource 328 owner back to the client with the authorization code. 330 Before directing the resource owner back to the client with the 331 authorization code, the authorization server authenticates the 332 resource owner and obtains authorization. Because the resource owner 333 only authenticates with the authorization server, the resource 334 owner's credentials are never shared with the client. 336 The authorization code provides a few important security benefits 337 such as the ability to authenticate the client, and the transmission 338 of the access token directly to the client without passing it through 339 the resource owner's user-agent, potentially exposing it to others, 340 including the resource owner. 342 1.3.2. Implicit 344 The implicit grant is a simplified authorization code flow optimized 345 for clients implemented in a browser using a scripting language such 346 as JavaScript. In the implicit flow, instead of issuing the client 347 an authorization code, the client is issued an access token directly 348 (as the result of the resource owner authorization). The grant type 349 is implicit as no intermediate credentials (such as an authorization 350 code) are issued (and later used to obtain an access token). 352 When issuing an access token during the implicit grant flow, the 353 authorization server does not authenticate the client. In some 354 cases, the client identity can be verified via the redirection URI 355 used to deliver the access token to the client. The access token may 356 be exposed to the resource owner or other applications with access to 357 the resource owner's user-agent. 359 Implicit grants improve the responsiveness and efficiency of some 360 clients (such as a client implemented as an in-browser application) 361 since it reduces the number of round trips required to obtain an 362 access token. However, this convenience should be weighed against 363 the security implications of using implicit grants, especially when 364 the authorization code grant type is available. 366 1.3.3. Resource Owner Password Credentials 368 The resource owner password credentials (i.e. username and password) 369 can be used directly as an authorization grant to obtain an access 370 token. The credentials should only be used when there is a high 371 degree of trust between the resource owner and the client (e.g. the 372 client is part of the device operating system or a highly privileged 373 application), and when other authorization grant types are not 374 available (such as an authorization code). 376 Even though this grant type requires direct client access to the 377 resource owner credentials, the resource owner credentials are used 378 for a single request and are exchanged for an access token. This 379 grant type can eliminate the need for the client to store the 380 resource owner credentials for future use, by exchanging the 381 credentials with a long-lived access token or refresh token. 383 1.3.4. Client Credentials 385 The client credentials (or other forms of client authentication) can 386 be used as an authorization grant when the authorization scope is 387 limited to the protected resources under the control of the client, 388 or to protected resources previously arranged with the authorization 389 server. Client credentials are used as an authorization grant 390 typically when the client is acting on its own behalf (the client is 391 also the resource owner), or is requesting access to protected 392 resources based on an authorization previously arranged with the 393 authorization server. 395 1.4. Access Token 397 Access tokens are credentials used to access protected resources. An 398 access token is a string representing an authorization issued to the 399 client. The string is usually opaque to the client. Tokens 400 represent specific scopes and durations of access, granted by the 401 resource owner, and enforced by the resource server and authorization 402 server. 404 The token may denote an identifier used to retrieve the authorization 405 information, or self-contain the authorization information in a 406 verifiable manner (i.e. a token string consisting of some data and a 407 signature). Additional authentication credentials, which are beyond 408 the scope of this specification, may be required in order for the 409 client to use a token. 411 The access token provides an abstraction layer, replacing different 412 authorization constructs (e.g. username and password) with a single 413 token understood by the resource server. This abstraction enables 414 issuing access tokens more restrictive than the authorization grant 415 used to obtain them, as well as removing the resource server's need 416 to understand a wide range of authentication methods. 418 Access tokens can have different formats, structures, and methods of 419 utilization (e.g. cryptographic properties) based on the resource 420 server security requirements. Access token attributes and the 421 methods used to access protected resources are beyond the scope of 422 this specification and are defined by companion specifications. 424 1.5. Refresh Token 426 Refresh tokens are credentials used to obtain access tokens. Refresh 427 tokens are issued to the client by the authorization server and are 428 used to obtain a new access token when the current access token 429 becomes invalid or expires, or to obtain additional access tokens 430 with identical or narrower scope (access tokens may have a shorter 431 lifetime and fewer permissions than authorized by the resource 432 owner). Issuing a refresh token is optional at the discretion of the 433 authorization server. If the authorization server issues a refresh 434 token, it is included when issuing an access token (i.e. step (D) in 435 Figure 1). 437 A refresh token is a string representing the authorization granted to 438 the client by the resource owner. The string is usually opaque to 439 the client. The token denotes an identifier used to retrieve the 440 authorization information. Unlike access tokens, refresh tokens are 441 intended for use only with authorization servers and are never sent 442 to resource servers. 444 +--------+ +---------------+ 445 | |--(A)------- Authorization Grant --------->| | 446 | | | | 447 | |<-(B)----------- Access Token -------------| | 448 | | & Refresh Token | | 449 | | | | 450 | | +----------+ | | 451 | |--(C)---- Access Token ---->| | | | 452 | | | | | | 453 | |<-(D)- Protected Resource --| Resource | | Authorization | 454 | Client | | Server | | Server | 455 | |--(E)---- Access Token ---->| | | | 456 | | | | | | 457 | |<-(F)- Invalid Token Error -| | | | 458 | | +----------+ | | 459 | | | | 460 | |--(G)----------- Refresh Token ----------->| | 461 | | | | 462 | |<-(H)----------- Access Token -------------| | 463 +--------+ & Optional Refresh Token +---------------+ 465 Figure 2: Refreshing an Expired Access Token 467 The flow illustrated in Figure 2 includes the following steps: 469 (A) The client requests an access token by authenticating with the 470 authorization server, and presenting an authorization grant. 471 (B) The authorization server authenticates the client and validates 472 the authorization grant, and if valid issues an access token and 473 a refresh token. 474 (C) The client makes a protected resource request to the resource 475 server by presenting the access token. 476 (D) The resource server validates the access token, and if valid, 477 serves the request. 478 (E) Steps (C) and (D) repeat until the access token expires. If the 479 client knows the access token expired, it skips to step (G), 480 otherwise it makes another protected resource request. 481 (F) Since the access token is invalid, the resource server returns 482 an invalid token error. 483 (G) The client requests a new access token by authenticating with 484 the authorization server and presenting the refresh token. The 485 client authentication requirements are based on the client type 486 and on the authorization server policies. 488 (H) The authorization server authenticates the client and validates 489 the refresh token, and if valid issues a new access token (and 490 optionally, a new refresh token). 492 Steps C, D, E, and F are outside the scope of this specification as 493 described in Section 7. 495 1.6. TLS Version 497 Whenever TLS is used by this specification, the appropriate version 498 (or versions) of TLS will vary over time, based on the widespread 499 deployment and known security vulnerabilities. At the time of this 500 writing, TLS version 1.2 [RFC5246] is the most recent version, but 501 has a very limited deployment base and might not be readily available 502 for implementation. TLS version 1.0 [RFC2246] is the most widely 503 deployed version, and will provide the broadest interoperability. 505 Implementations MAY also support additional transport-layer security 506 mechanisms that meet their security requirements. 508 1.7. HTTP Redirections 510 This specification makes extensive use of HTTP redirections, in which 511 the client or the authorization server direct the resource owner's 512 user-agent to another destination. While the examples in this 513 specification show the use of the HTTP 302 status code, any other 514 method available via the user-agent to accomplish this redirection is 515 allowed and is considered to be an implementation detail. 517 1.8. Interoperability 519 OAuth 2.0 provides a rich authorization framework with well-defined 520 security properties. However, as a rich and highly extensible 521 framework with many optional components, on its own, this 522 specification is likely to produce a wide range of non-interoperable 523 implementations. 525 In addition, this specification leaves a few required components 526 partially or fully undefined (e.g. client registration, authorization 527 server capabilities, endpoint discovery). Without these components, 528 clients must be manually and specifically configured against a 529 specific authorization server and resource server in order to 530 interoperate. 532 This framework was designed with the clear expectation that future 533 work will define prescriptive profiles and extensions necessary to 534 achieve full web-scale interoperability. 536 1.9. Notational Conventions 538 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 539 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 540 specification are to be interpreted as described in [RFC2119]. 542 This specification uses the Augmented Backus-Naur Form (ABNF) 543 notation of [RFC5234]. Additionally, the rule URI-Reference is 544 included from Uniform Resource Identifier (URI) [RFC3986]. 546 Certain security-related terms are to be understood in the sense 547 defined in [RFC4949]. These terms include, but are not limited to, 548 "attack", "authentication", "authorization", "certificate", 549 "confidentiality", "credential", "encryption", "identity", "sign", 550 "signature", "trust", "validate", and "verify". 552 Unless otherwise noted, all the protocol parameter names and values 553 are case sensitive. 555 2. Client Registration 557 Before initiating the protocol, the client registers with the 558 authorization server. The means through which the client registers 559 with the authorization server are beyond the scope of this 560 specification, but typically involve end-user interaction with an 561 HTML registration form. 563 Client registration does not require a direct interaction between the 564 client and the authorization server. When supported by the 565 authorization server, registration can rely on other means for 566 establishing trust and obtaining the required client properties (e.g. 567 redirection URI, client type). For example, registration can be 568 accomplished using a self-issued or third-party-issued assertion, or 569 by the authorization server performing client discovery using a 570 trusted channel. 572 When registering a client, the client developer SHALL: 574 o specify the client type as described in Section 2.1, 575 o provide its client redirection URIs as described in Section 3.1.2, 576 and 577 o include any other information required by the authorization server 578 (e.g. application name, website, description, logo image, the 579 acceptance of legal terms). 581 2.1. Client Types 583 OAuth defines two client types, based on their ability to 584 authenticate securely with the authorization server (i.e. ability to 585 maintain the confidentiality of their client credentials): 587 confidential 588 Clients capable of maintaining the confidentiality of their 589 credentials (e.g. client implemented on a secure server with 590 restricted access to the client credentials), or capable of secure 591 client authentication using other means. 592 public 593 Clients incapable of maintaining the confidentiality of their 594 credentials (e.g. clients executing on the device used by the 595 resource owner such as an installed native application or a web 596 browser-based application), and incapable of secure client 597 authentication via any other means. 599 The client type designation is based on the authorization server's 600 definition of secure authentication and its acceptable exposure 601 levels of client credentials. The authorization server SHOULD NOT 602 make assumptions about the client type. 604 A client may be implemented as a distributed set of components, each 605 with a different client type and security context (e.g. a distributed 606 client with both a confidential server-based component and a public 607 browser-based component). If the authorization server does not 608 provide support for such clients, or does not provide guidance with 609 regard to their registration, the client SHOULD register each 610 component as a separate client. 612 This specification has been designed around the following client 613 profiles: 615 web application 616 A web application is a confidential client running on a web 617 server. Resource owners access the client via an HTML user 618 interface rendered in a user-agent on the device used by the 619 resource owner. The client credentials as well as any access 620 token issued to the client are stored on the web server and are 621 not exposed to or accessible by the resource owner. 622 user-agent-based application 623 A user-agent-based application is a public client in which the 624 client code is downloaded from a web server and executes within a 625 user-agent (e.g. web browser) on the device used by the resource 626 owner. Protocol data and credentials are easily accessible (and 627 often visible) to the resource owner. Since such applications 628 reside within the user-agent, they can make seamless use of the 629 user-agent capabilities when requesting authorization. 630 native application 631 A native application is a public client installed and executed on 632 the device used by the resource owner. Protocol data and 633 credentials are accessible to the resource owner. It is assumed 634 that any client authentication credentials included in the 635 application can be extracted. On the other hand, dynamically 636 issued credentials such as access tokens or refresh tokens can 637 receive an acceptable level of protection. At a minimum, these 638 credentials are protected from hostile servers with which the 639 application may interact with. On some platforms these 640 credentials might be protected from other applications residing on 641 the same device. 643 2.2. Client Identifier 645 The authorization server issues the registered client a client 646 identifier - a unique string representing the registration 647 information provided by the client. The client identifier is not a 648 secret; it is exposed to the resource owner, and MUST NOT be used 649 alone for client authentication. The client identifier is unique to 650 the authorization server. 652 The client identifier string size is left undefined by this 653 specification. The client should avoid making assumptions about the 654 identifier size. The authorization server SHOULD document the size 655 of any identifier it issues. 657 2.3. Client Authentication 659 If the client type is confidential, the client and authorization 660 server establish a client authentication method suitable for the 661 security requirements of the authorization server. The authorization 662 server MAY accept any form of client authentication meeting its 663 security requirements. 665 Confidential clients are typically issued (or establish) a set of 666 client credentials used for authenticating with the authorization 667 server (e.g. password, public/private key pair). 669 The authorization server MAY establish a client authentication method 670 with public clients. However, the authorization server MUST NOT rely 671 on public client authentication for the purpose of identifying the 672 client. 674 The client MUST NOT use more than one authentication method in each 675 request. 677 2.3.1. Client Password 679 Clients in possession of a client password MAY use the HTTP Basic 680 authentication scheme as defined in [RFC2617] to authenticate with 681 the authorization server. The client identifier is used as the 682 username, and the client password is used as the password. The 683 authorization server MUST support the HTTP Basic authentication 684 scheme for authenticating clients which were issued a client 685 password. 687 For example (extra line breaks are for display purposes only): 689 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 691 Alternatively, the authorization server MAY support including the 692 client credentials in the request body using the following 693 parameters: 695 client_id 696 REQUIRED. The client identifier issued to the client during 697 the registration process described by Section 2.2. 698 client_secret 699 REQUIRED. The client secret. The client MAY omit the 700 parameter if the client secret is an empty string. 702 Including the client credentials in the request body using the two 703 parameters is NOT RECOMMENDED, and SHOULD be limited to clients 704 unable to directly utilize the HTTP Basic authentication scheme (or 705 other password-based HTTP authentication schemes). The parameters 706 can only be transmitted in the request body and MUST NOT be included 707 in the request URI. 709 For example, requesting to refresh an access token (Section 6) using 710 the body parameters (extra line breaks are for display purposes 711 only): 713 POST /token HTTP/1.1 714 Host: server.example.com 715 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 717 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 718 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 720 The authorization server MUST require the use of TLS as described in 721 Section 1.6 when sending requests using password authentication. 723 Since this client authentication method involves a password, the 724 authorization server MUST protect any endpoint utilizing it against 725 brute force attacks. 727 2.3.2. Other Authentication Methods 729 The authorization server MAY support any suitable HTTP authentication 730 scheme matching its security requirements. When using other 731 authentication methods, the authorization server MUST define a 732 mapping between the client identifier (registration record) and 733 authentication scheme. 735 2.4. Unregistered Clients 737 This specification does not exclude the use of unregistered clients. 738 However, the use with such clients is beyond the scope of this 739 specification, and requires additional security analysis and review 740 of its interoperability impact. 742 3. Protocol Endpoints 744 The authorization process utilizes two authorization server endpoints 745 (HTTP resources): 747 o Authorization endpoint - used by the client to obtain 748 authorization from the resource owner via user-agent redirection. 749 o Token endpoint - used by the client to exchange an authorization 750 grant for an access token, typically with client authentication. 752 As well as one client endpoint: 754 o Redirection endpoint - used by the authorization server to return 755 authorization credentials responses to the client via the resource 756 owner user-agent. 758 Not every authorization grant type utilizes both endpoints. 759 Extension grant types MAY define additional endpoints as needed. 761 3.1. Authorization Endpoint 763 The authorization endpoint is used to interact with the resource 764 owner and obtain an authorization grant. The authorization server 765 MUST first verify the identity of the resource owner. The way in 766 which the authorization server authenticates the resource owner (e.g. 767 username and password login, session cookies) is beyond the scope of 768 this specification. 770 The means through which the client obtains the location of the 771 authorization endpoint are beyond the scope of this specification, 772 but the location is typically provided in the service documentation. 774 The endpoint URI MAY include an "application/x-www-form-urlencoded" 775 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 776 section 3.4), which MUST be retained when adding additional query 777 parameters. The endpoint URI MUST NOT include a fragment component. 779 Since requests to the authorization endpoint result in user 780 authentication and the transmission of clear-text credentials (in the 781 HTTP response), the authorization server MUST require the use of TLS 782 as described in Section 1.6 when sending requests to the 783 authorization endpoint. 785 The authorization server MUST support the use of the HTTP "GET" 786 method [RFC2616] for the authorization endpoint, and MAY support the 787 use of the "POST" method as well. 789 Parameters sent without a value MUST be treated as if they were 790 omitted from the request. The authorization server MUST ignore 791 unrecognized request parameters. Request and response parameters 792 MUST NOT be included more than once. 794 3.1.1. Response Type 796 The authorization endpoint is used by the authorization code grant 797 type and implicit grant type flows. The client informs the 798 authorization server of the desired grant type using the following 799 parameter: 801 response_type 802 REQUIRED. The value MUST be one of "code" for requesting an 803 authorization code as described by Section 4.1.1, "token" for 804 requesting an access token (implicit grant) as described by 805 Section 4.2.1, or a registered extension value as described by 806 Section 8.4. 808 Extension response types MAY contain a space-delimited (%x20) list of 809 values, where the order of values does not matter (e.g. response type 810 "a b" is the same as "b a"). The meaning of such composite response 811 types is defined by their respective specifications. 813 If an authorization request is missing the "response_type" parameter, 814 or if the response type is not understood, the authorization server 815 MUST return an error response as described in Section 4.1.2.1. 817 3.1.2. Redirection Endpoint 819 After completing its interaction with the resource owner, the 820 authorization server directs the resource owner's user-agent back to 821 the client. The authorization server redirects the user-agent to the 822 client's redirection endpoint previously established with the 823 authorization server during the client registration process or when 824 making the authorization request. 826 The redirection endpoint URI MUST be an absolute URI as defined by 827 [RFC3986] section 4.3. The endpoint URI MAY include an 828 "application/x-www-form-urlencoded" formatted 829 ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), 830 which MUST be retained when adding additional query parameters. The 831 endpoint URI MUST NOT include a fragment component. 833 3.1.2.1. Endpoint Request Confidentiality 835 The redirection endpoint SHOULD require the use of TLS as described 836 in Section 1.6 when the requested response type is "code" or "token", 837 or when the redirection request will result in the transmission of 838 sensitive credentials over an open network. This specification does 839 not mandate the use of TLS because at the time of this writing, 840 requiring clients to deploy TLS is a significant hurdle for many 841 client developers. If TLS is not available, the authorization server 842 SHOULD warn the resource owner about the insecure endpoint prior to 843 redirection (e.g. display a message during the authorization 844 request). 846 Lack of transport-layer security can have a severe impact on the 847 security of the client and the protected resources it is authorized 848 to access. The use of transport-layer security is particularly 849 critical when the authorization process is used as a form of 850 delegated end-user authentication by the client (e.g. third-party 851 sign-in service). 853 3.1.2.2. Registration Requirements 855 The authorization server MUST require the following clients to 856 register their redirection endpoint: 858 o Public clients. 859 o Confidential clients utilizing the implicit grant type. 861 The authorization server SHOULD require all clients to register their 862 redirection endpoint prior to utilizing the authorization endpoint. 864 The authorization server SHOULD require the client to provide the 865 complete redirection URI (the client MAY use the "state" request 866 parameter to achieve per-request customization). If requiring the 867 registration of the complete redirection URI is not possible, the 868 authorization server SHOULD require the registration of the URI 869 scheme, authority, and path (allowing the client to dynamically vary 870 only the query component of the redirection URI when requesting 871 authorization). 873 The authorization server MAY allow the client to register multiple 874 redirection endpoints. 876 Lack of a redirection URI registration requirement can enable an 877 attacker to use the authorization endpoint as open redirector as 878 described in Section 10.15. 880 3.1.2.3. Dynamic Configuration 882 If multiple redirection URIs have been registered, if only part of 883 the redirection URI has been registered, or if no redirection URI has 884 been registered, the client MUST include a redirection URI with the 885 authorization request using the "redirect_uri" request parameter. 887 When a redirection URI is included in an authorization request, the 888 authorization server MUST compare and match the value received 889 against at least one of the registered redirection URIs (or URI 890 components) as defined in [RFC3986] section 6, if any redirection 891 URIs were registered. If the client registration included the full 892 redirection URI, the authorization server MUST compare the two URIs 893 using simple string comparison as defined in [RFC3986] section 6.2.1. 895 3.1.2.4. Invalid Endpoint 897 If an authorization request fails validation due to a missing, 898 invalid, or mismatching redirection URI, the authorization server 899 SHOULD inform the resource owner of the error, and MUST NOT 900 automatically redirect the user-agent to the invalid redirection URI. 902 3.1.2.5. Endpoint Content 904 The redirection request to the client's endpoint typically results in 905 an HTML document response, processed by the user-agent. If the HTML 906 response is served directly as the result of the redirection request, 907 any script included in the HTML document will execute with full 908 access to the redirection URI and the credentials it contains. 910 The client SHOULD NOT include any third-party scripts (e.g. third- 911 party analytics, social plug-ins, ad networks) in the redirection 912 endpoint response. Instead, it SHOULD extract the credentials from 913 the URI and redirect the user-agent again to another endpoint without 914 exposing the credentials (in the URI or elsewhere). If third-party 915 scripts are included, the client MUST ensure that its own scripts 916 (used to extract and remove the credentials from the URI) will 917 execute first. 919 3.2. Token Endpoint 921 The token endpoint is used by the client to obtain an access token by 922 presenting its authorization grant or refresh token. The token 923 endpoint is used with every authorization grant except for the 924 implicit grant type (since an access token is issued directly). 926 The means through which the client obtains the location of the token 927 endpoint are beyond the scope of this specification but is typically 928 provided in the service documentation. 930 The endpoint URI MAY include an "application/x-www-form-urlencoded" 931 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 932 section 3.4), which MUST be retained when adding additional query 933 parameters. The endpoint URI MUST NOT include a fragment component. 935 Since requests to the token endpoint result in the transmission of 936 clear-text credentials (in the HTTP request and response), the 937 authorization server MUST require the use of TLS as described in 938 Section 1.6 when sending requests to the token endpoint. 940 The client MUST use the HTTP "POST" method when making access token 941 requests. 943 Parameters sent without a value MUST be treated as if they were 944 omitted from the request. The authorization server MUST ignore 945 unrecognized request parameters. Request and response parameters 946 MUST NOT be included more than once. 948 3.2.1. Client Authentication 950 Confidential clients or other clients issued client credentials MUST 951 authenticate with the authorization server as described in 952 Section 2.3 when making requests to the token endpoint. Client 953 authentication is used for: 955 o Enforcing the binding of refresh tokens and authorization codes to 956 the client they were issued to. Client authentication is critical 957 when an authorization code is transmitted to the redirection 958 endpoint over an insecure channel, or when the redirection URI has 959 not been registered in full. 961 o Recovering from a compromised client by disabling the client or 962 changing its credentials, thus preventing an attacker from abusing 963 stolen refresh tokens. Changing a single set of client 964 credentials is significantly faster than revoking an entire set of 965 refresh tokens. 966 o Implementing authentication management best practices which 967 require periodic credential rotation. Rotation of an entire set 968 of refresh tokens can be challenging, while rotation of a single 969 set of client credentials is significantly easier. 971 A public client that was not issued a client password MAY use the 972 "client_id" request parameter to identify itself when sending 973 requests to the token endpoint (e.g. for the purpose of providing 974 end-user context, client usage statistics). 976 3.3. Access Token Scope 978 The authorization and token endpoints allow the client to specify the 979 scope of the access request using the "scope" request parameter. In 980 turn, the authorization server uses the "scope" response parameter to 981 inform the client of the scope of the access token issued. 983 The value of the scope parameter is expressed as a list of space- 984 delimited, case sensitive strings. The strings are defined by the 985 authorization server. If the value contains multiple space-delimited 986 strings, their order does not matter, and each string adds an 987 additional access range to the requested scope. 989 scope = scope-token *( SP scope-token ) 990 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 992 The authorization server MAY fully or partially ignore the scope 993 requested by the client based on the authorization server policy or 994 the resource owner's instructions. If the issued access token scope 995 is different from the one requested by the client, the authorization 996 server MUST include the "scope" response parameter to inform the 997 client of the actual scope granted. 999 If the client omits the scope parameter when requesting 1000 authorization, the authorization server MUST either process the 1001 request using a pre-defined default value, or fail the request 1002 indicating an invalid scope. The authorization server SHOULD 1003 document its scope requirements and default value (if defined). 1005 4. Obtaining Authorization 1007 To request an access token, the client obtains authorization from the 1008 resource owner. The authorization is expressed in the form of an 1009 authorization grant which the client uses to request the access 1010 token. OAuth defines four grant types: authorization code, implicit, 1011 resource owner password credentials, and client credentials. It also 1012 provides an extension mechanism for defining additional grant types. 1014 4.1. Authorization Code Grant 1016 The authorization code grant type is used to obtain both access 1017 tokens and refresh tokens and is optimized for confidential clients. 1018 As a redirection-based flow, the client must be capable of 1019 interacting with the resource owner's user-agent (typically a web 1020 browser) and capable of receiving incoming requests (via redirection) 1021 from the authorization server. 1023 +----------+ 1024 | resource | 1025 | owner | 1026 | | 1027 +----------+ 1028 ^ 1029 | 1030 (B) 1031 +----|-----+ Client Identifier +---------------+ 1032 | -+----(A)-- & Redirection URI ---->| | 1033 | User- | | Authorization | 1034 | Agent -+----(B)-- User authenticates --->| Server | 1035 | | | | 1036 | -+----(C)-- Authorization Code ---<| | 1037 +-|----|---+ +---------------+ 1038 | | ^ v 1039 (A) (C) | | 1040 | | | | 1041 ^ v | | 1042 +---------+ | | 1043 | |>---(D)-- Authorization Code ---------' | 1044 | Client | & Redirection URI | 1045 | | | 1046 | |<---(E)----- Access Token -------------------' 1047 +---------+ (w/ Optional Refresh Token) 1049 Note: The lines illustrating steps A, B, and C are broken into two 1050 parts as they pass through the user-agent. 1052 Figure 3: Authorization Code Flow 1054 The flow illustrated in Figure 3 includes the following steps: 1056 (A) The client initiates the flow by directing the resource owner's 1057 user-agent to the authorization endpoint. The client includes 1058 its client identifier, requested scope, local state, and a 1059 redirection URI to which the authorization server will send the 1060 user-agent back once access is granted (or denied). 1061 (B) The authorization server authenticates the resource owner (via 1062 the user-agent) and establishes whether the resource owner 1063 grants or denies the client's access request. 1064 (C) Assuming the resource owner grants access, the authorization 1065 server redirects the user-agent back to the client using the 1066 redirection URI provided earlier (in the request or during 1067 client registration). The redirection URI includes an 1068 authorization code and any local state provided by the client 1069 earlier. 1070 (D) The client requests an access token from the authorization 1071 server's token endpoint by including the authorization code 1072 received in the previous step. When making the request, the 1073 client authenticates with the authorization server. The client 1074 includes the redirection URI used to obtain the authorization 1075 code for verification. 1076 (E) The authorization server authenticates the client, validates the 1077 authorization code, and ensures the redirection URI received 1078 matches the URI used to redirect the client in step (C). If 1079 valid, the authorization server responds back with an access 1080 token and optionally, a refresh token. 1082 4.1.1. Authorization Request 1084 The client constructs the request URI by adding the following 1085 parameters to the query component of the authorization endpoint URI 1086 using the "application/x-www-form-urlencoded" format as defined by 1087 [W3C.REC-html401-19991224]: 1089 response_type 1090 REQUIRED. Value MUST be set to "code". 1091 client_id 1092 REQUIRED. The client identifier as described in Section 2.2. 1093 redirect_uri 1094 OPTIONAL. As described in Section 3.1.2. 1095 scope 1096 OPTIONAL. The scope of the access request as described by 1097 Section 3.3. 1099 state 1100 RECOMMENDED. An opaque value used by the client to maintain 1101 state between the request and callback. The authorization 1102 server includes this value when redirecting the user-agent back 1103 to the client. The parameter SHOULD be used for preventing 1104 cross-site request forgery as described in Section 10.12. 1106 The client directs the resource owner to the constructed URI using an 1107 HTTP redirection response, or by other means available to it via the 1108 user-agent. 1110 For example, the client directs the user-agent to make the following 1111 HTTP request using TLS (extra line breaks are for display purposes 1112 only): 1114 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1115 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1116 Host: server.example.com 1118 The authorization server validates the request to ensure all required 1119 parameters are present and valid. If the request is valid, the 1120 authorization server authenticates the resource owner and obtains an 1121 authorization decision (by asking the resource owner or by 1122 establishing approval via other means). 1124 When a decision is established, the authorization server directs the 1125 user-agent to the provided client redirection URI using an HTTP 1126 redirection response, or by other means available to it via the user- 1127 agent. 1129 4.1.2. Authorization Response 1131 If the resource owner grants the access request, the authorization 1132 server issues an authorization code and delivers it to the client by 1133 adding the following parameters to the query component of the 1134 redirection URI using the "application/x-www-form-urlencoded" format: 1136 code 1137 REQUIRED. The authorization code generated by the 1138 authorization server. The authorization code MUST expire 1139 shortly after it is issued to mitigate the risk of leaks. A 1140 maximum authorization code lifetime of 10 minutes is 1141 RECOMMENDED. The client MUST NOT use the authorization code 1142 more than once. If an authorization code is used more than 1143 once, the authorization server MUST deny the request and SHOULD 1144 revoke (when possible) all tokens previously issued based on 1145 that authorization code. The authorization code is bound to 1146 the client identifier and redirection URI. 1147 state 1148 REQUIRED if the "state" parameter was present in the client 1149 authorization request. The exact value received from the 1150 client. 1152 For example, the authorization server redirects the user-agent by 1153 sending the following HTTP response: 1155 HTTP/1.1 302 Found 1156 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1157 &state=xyz 1159 The client MUST ignore unrecognized response parameters. The 1160 authorization code string size is left undefined by this 1161 specification. The client should avoid making assumptions about code 1162 value sizes. The authorization server SHOULD document the size of 1163 any value it issues. 1165 4.1.2.1. Error Response 1167 If the request fails due to a missing, invalid, or mismatching 1168 redirection URI, or if the client identifier is missing or invalid, 1169 the authorization server SHOULD inform the resource owner of the 1170 error, and MUST NOT automatically redirect the user-agent to the 1171 invalid redirection URI. 1173 If the resource owner denies the access request or if the request 1174 fails for reasons other than a missing or invalid redirection URI, 1175 the authorization server informs the client by adding the following 1176 parameters to the query component of the redirection URI using the 1177 "application/x-www-form-urlencoded" format: 1179 error 1180 REQUIRED. A single ASCII [USASCII] error code from the 1181 following: 1182 invalid_request 1183 The request is missing a required parameter, includes an 1184 invalid parameter value, includes a parameter more than 1185 once, or is otherwise malformed. 1186 unauthorized_client 1187 The client is not authorized to request an authorization 1188 code using this method. 1190 access_denied 1191 The resource owner or authorization server denied the 1192 request. 1193 unsupported_response_type 1194 The authorization server does not support obtaining an 1195 authorization code using this method. 1196 invalid_scope 1197 The requested scope is invalid, unknown, or malformed. 1198 server_error 1199 The authorization server encountered an unexpected 1200 condition which prevented it from fulfilling the request. 1201 temporarily_unavailable 1202 The authorization server is currently unable to handle 1203 the request due to a temporary overloading or maintenance 1204 of the server. 1205 Values for the "error" parameter MUST NOT include characters 1206 outside the set %x20-21 / %x23-5B / %x5D-7E. 1207 error_description 1208 OPTIONAL. A human-readable ASCII [USASCII] text providing 1209 additional information, used to assist the client developer in 1210 understanding the error that occurred. 1211 Values for the "error_description" parameter MUST NOT include 1212 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1213 error_uri 1214 OPTIONAL. A URI identifying a human-readable web page with 1215 information about the error, used to provide the client 1216 developer with additional information about the error. 1217 Values for the "error_uri" parameter MUST conform to the URI- 1218 Reference syntax, and thus MUST NOT include characters outside 1219 the set %x21 / %x23-5B / %x5D-7E. 1220 state 1221 REQUIRED if a "state" parameter was present in the client 1222 authorization request. The exact value received from the 1223 client. 1225 For example, the authorization server redirects the user-agent by 1226 sending the following HTTP response: 1228 HTTP/1.1 302 Found 1229 Location: https://client.example.com/cb?error=access_denied&state=xyz 1231 4.1.3. Access Token Request 1233 The client makes a request to the token endpoint by adding the 1234 following parameters using the "application/x-www-form-urlencoded" 1235 format in the HTTP request entity-body: 1237 grant_type 1238 REQUIRED. Value MUST be set to "authorization_code". 1239 code 1240 REQUIRED. The authorization code received from the 1241 authorization server. 1242 redirect_uri 1243 REQUIRED, if the "redirect_uri" parameter was included in the 1244 authorization request as described in Section 4.1.1, and their 1245 values MUST be identical. 1247 If the client type is confidential or the client was issued client 1248 credentials (or assigned other authentication requirements), the 1249 client MUST authenticate with the authorization server as described 1250 in Section 3.2.1. 1252 For example, the client makes the following HTTP request using TLS 1253 (extra line breaks are for display purposes only): 1255 POST /token HTTP/1.1 1256 Host: server.example.com 1257 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1258 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1260 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1261 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1263 The authorization server MUST: 1265 o require client authentication for confidential clients or for any 1266 client that was issued client credentials (or with other 1267 authentication requirements), 1268 o authenticate the client if client authentication is included and 1269 ensure the authorization code was issued to the authenticated 1270 client, 1271 o verify that the authorization code is valid, and 1272 o ensure that the "redirect_uri" parameter is present if the 1273 "redirect_uri" parameter was included in the initial authorization 1274 request as described in Section 4.1.1, and if included ensure 1275 their values are identical. 1277 4.1.4. Access Token Response 1279 If the access token request is valid and authorized, the 1280 authorization server issues an access token and optional refresh 1281 token as described in Section 5.1. If the request client 1282 authentication failed or is invalid, the authorization server returns 1283 an error response as described in Section 5.2. 1285 An example successful response: 1287 HTTP/1.1 200 OK 1288 Content-Type: application/json;charset=UTF-8 1289 Cache-Control: no-store 1290 Pragma: no-cache 1292 { 1293 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1294 "token_type":"example", 1295 "expires_in":3600, 1296 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1297 "example_parameter":"example_value" 1298 } 1300 4.2. Implicit Grant 1302 The implicit grant type is used to obtain access tokens (it does not 1303 support the issuance of refresh tokens) and is optimized for public 1304 clients known to operate a particular redirection URI. These clients 1305 are typically implemented in a browser using a scripting language 1306 such as JavaScript. 1308 As a redirection-based flow, the client must be capable of 1309 interacting with the resource owner's user-agent (typically a web 1310 browser) and capable of receiving incoming requests (via redirection) 1311 from the authorization server. 1313 Unlike the authorization code grant type in which the client makes 1314 separate requests for authorization and access token, the client 1315 receives the access token as the result of the authorization request. 1317 The implicit grant type does not include client authentication, and 1318 relies on the presence of the resource owner and the registration of 1319 the redirection URI. Because the access token is encoded into the 1320 redirection URI, it may be exposed to the resource owner and other 1321 applications residing on the same device. 1323 +----------+ 1324 | Resource | 1325 | Owner | 1326 | | 1327 +----------+ 1328 ^ 1329 | 1330 (B) 1331 +----|-----+ Client Identifier +---------------+ 1332 | -+----(A)-- & Redirection URI --->| | 1333 | User- | | Authorization | 1334 | Agent -|----(B)-- User authenticates -->| Server | 1335 | | | | 1336 | |<---(C)--- Redirection URI ----<| | 1337 | | with Access Token +---------------+ 1338 | | in Fragment 1339 | | +---------------+ 1340 | |----(D)--- Redirection URI ---->| Web-Hosted | 1341 | | without Fragment | Client | 1342 | | | Resource | 1343 | (F) |<---(E)------- Script ---------<| | 1344 | | +---------------+ 1345 +-|--------+ 1346 | | 1347 (A) (G) Access Token 1348 | | 1349 ^ v 1350 +---------+ 1351 | | 1352 | Client | 1353 | | 1354 +---------+ 1356 Note: The lines illustrating steps A and B are broken into two parts 1357 as they pass through the user-agent. 1359 Figure 4: Implicit Grant Flow 1361 The flow illustrated in Figure 4 includes the following steps: 1363 (A) The client initiates the flow by directing the resource owner's 1364 user-agent to the authorization endpoint. The client includes 1365 its client identifier, requested scope, local state, and a 1366 redirection URI to which the authorization server will send the 1367 user-agent back once access is granted (or denied). 1369 (B) The authorization server authenticates the resource owner (via 1370 the user-agent) and establishes whether the resource owner 1371 grants or denies the client's access request. 1372 (C) Assuming the resource owner grants access, the authorization 1373 server redirects the user-agent back to the client using the 1374 redirection URI provided earlier. The redirection URI includes 1375 the access token in the URI fragment. 1376 (D) The user-agent follows the redirection instructions by making a 1377 request to the web-hosted client resource (which does not 1378 include the fragment per [RFC2616]). The user-agent retains the 1379 fragment information locally. 1380 (E) The web-hosted client resource returns a web page (typically an 1381 HTML document with an embedded script) capable of accessing the 1382 full redirection URI including the fragment retained by the 1383 user-agent, and extracting the access token (and other 1384 parameters) contained in the fragment. 1385 (F) The user-agent executes the script provided by the web-hosted 1386 client resource locally, which extracts the access token and 1387 passes it to the client. 1389 4.2.1. Authorization Request 1391 The client constructs the request URI by adding the following 1392 parameters to the query component of the authorization endpoint URI 1393 using the "application/x-www-form-urlencoded" format: 1395 response_type 1396 REQUIRED. Value MUST be set to "token". 1397 client_id 1398 REQUIRED. The client identifier as described in Section 2.2. 1399 redirect_uri 1400 OPTIONAL. As described in Section 3.1.2. 1401 scope 1402 OPTIONAL. The scope of the access request as described by 1403 Section 3.3. 1404 state 1405 RECOMMENDED. An opaque value used by the client to maintain 1406 state between the request and callback. The authorization 1407 server includes this value when redirecting the user-agent back 1408 to the client. The parameter SHOULD be used for preventing 1409 cross-site request forgery as described in Section 10.12. 1411 The client directs the resource owner to the constructed URI using an 1412 HTTP redirection response, or by other means available to it via the 1413 user-agent. 1415 For example, the client directs the user-agent to make the following 1416 HTTP request using TLS (extra line breaks are for display purposes 1417 only): 1419 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1420 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1421 Host: server.example.com 1423 The authorization server validates the request to ensure all required 1424 parameters are present and valid. The authorization server MUST 1425 verify that the redirection URI to which it will redirect the access 1426 token matches a redirection URI registered by the client as described 1427 in Section 3.1.2. 1429 If the request is valid, the authorization server authenticates the 1430 resource owner and obtains an authorization decision (by asking the 1431 resource owner or by establishing approval via other means). 1433 When a decision is established, the authorization server directs the 1434 user-agent to the provided client redirection URI using an HTTP 1435 redirection response, or by other means available to it via the user- 1436 agent. 1438 4.2.2. Access Token Response 1440 If the resource owner grants the access request, the authorization 1441 server issues an access token and delivers it to the client by adding 1442 the following parameters to the fragment component of the redirection 1443 URI using the "application/x-www-form-urlencoded" format: 1445 access_token 1446 REQUIRED. The access token issued by the authorization server. 1447 token_type 1448 REQUIRED. The type of the token issued as described in 1449 Section 7.1. Value is case insensitive. 1450 expires_in 1451 RECOMMENDED. The lifetime in seconds of the access token. For 1452 example, the value "3600" denotes that the access token will 1453 expire in one hour from the time the response was generated. 1454 If omitted, the authorization server SHOULD provide the 1455 expiration time via other means or document the default value. 1456 scope 1457 OPTIONAL, if identical to the scope requested by the client, 1458 otherwise REQUIRED. The scope of the access token as described 1459 by Section 3.3. 1461 state 1462 REQUIRED if the "state" parameter was present in the client 1463 authorization request. The exact value received from the 1464 client. 1466 The authorization server MUST NOT issue a refresh token. 1468 For example, the authorization server redirects the user-agent by 1469 sending the following HTTP response (URI extra line breaks are for 1470 display purposes only): 1472 HTTP/1.1 302 Found 1473 Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1474 &state=xyz&token_type=example&expires_in=3600 1476 Developers should note that some user-agents do not support the 1477 inclusion of a fragment component in the HTTP "Location" response 1478 header field. Such clients will require using other methods for 1479 redirecting the client than a 3xx redirection response. For example, 1480 returning an HTML page which includes a 'continue' button with an 1481 action linked to the redirection URI. 1483 The client MUST ignore unrecognized response parameters. The access 1484 token string size is left undefined by this specification. The 1485 client should avoid making assumptions about value sizes. The 1486 authorization server SHOULD document the size of any value it issues. 1488 4.2.2.1. Error Response 1490 If the request fails due to a missing, invalid, or mismatching 1491 redirection URI, or if the client identifier is missing or invalid, 1492 the authorization server SHOULD inform the resource owner of the 1493 error, and MUST NOT automatically redirect the user-agent to the 1494 invalid redirection URI. 1496 If the resource owner denies the access request or if the request 1497 fails for reasons other than a missing or invalid redirection URI, 1498 the authorization server informs the client by adding the following 1499 parameters to the fragment component of the redirection URI using the 1500 "application/x-www-form-urlencoded" format: 1502 error 1503 REQUIRED. A single ASCII [USASCII] error code from the 1504 following: 1506 invalid_request 1507 The request is missing a required parameter, includes an 1508 invalid parameter value, includes a parameter more than 1509 once, or is otherwise malformed. 1510 unauthorized_client 1511 The client is not authorized to request an access token 1512 using this method. 1513 access_denied 1514 The resource owner or authorization server denied the 1515 request. 1516 unsupported_response_type 1517 The authorization server does not support obtaining an 1518 access token using this method. 1519 invalid_scope 1520 The requested scope is invalid, unknown, or malformed. 1521 server_error 1522 The authorization server encountered an unexpected 1523 condition which prevented it from fulfilling the request. 1524 temporarily_unavailable 1525 The authorization server is currently unable to handle 1526 the request due to a temporary overloading or maintenance 1527 of the server. 1528 Values for the "error" parameter MUST NOT include characters 1529 outside the set %x20-21 / %x23-5B / %x5D-7E. 1530 error_description 1531 OPTIONAL. A human-readable ASCII [USASCII] text providing 1532 additional information, used to assist the client developer in 1533 understanding the error that occurred. 1534 Values for the "error_description" parameter MUST NOT include 1535 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1536 error_uri 1537 OPTIONAL. A URI identifying a human-readable web page with 1538 information about the error, used to provide the client 1539 developer with additional information about the error. 1540 Values for the "error_uri" parameter MUST conform to the URI- 1541 Reference syntax, and thus MUST NOT include characters outside 1542 the set %x21 / %x23-5B / %x5D-7E. 1543 state 1544 REQUIRED if a "state" parameter was present in the client 1545 authorization request. The exact value received from the 1546 client. 1548 For example, the authorization server redirects the user-agent by 1549 sending the following HTTP response: 1551 HTTP/1.1 302 Found 1552 Location: https://client.example.com/cb#error=access_denied&state=xyz 1554 4.3. Resource Owner Password Credentials Grant 1556 The resource owner password credentials grant type is suitable in 1557 cases where the resource owner has a trust relationship with the 1558 client, such as the device operating system or a highly privileged 1559 application. The authorization server should take special care when 1560 enabling this grant type, and only allow it when other flows are not 1561 viable. 1563 The grant type is suitable for clients capable of obtaining the 1564 resource owner's credentials (username and password, typically using 1565 an interactive form). It is also used to migrate existing clients 1566 using direct authentication schemes such as HTTP Basic or Digest 1567 authentication to OAuth by converting the stored credentials to an 1568 access token. 1570 +----------+ 1571 | Resource | 1572 | Owner | 1573 | | 1574 +----------+ 1575 v 1576 | Resource Owner 1577 (A) Password Credentials 1578 | 1579 v 1580 +---------+ +---------------+ 1581 | |>--(B)---- Resource Owner ------->| | 1582 | | Password Credentials | Authorization | 1583 | Client | | Server | 1584 | |<--(C)---- Access Token ---------<| | 1585 | | (w/ Optional Refresh Token) | | 1586 +---------+ +---------------+ 1588 Figure 5: Resource Owner Password Credentials Flow 1590 The flow illustrated in Figure 5 includes the following steps: 1592 (A) The resource owner provides the client with its username and 1593 password. 1594 (B) The client requests an access token from the authorization 1595 server's token endpoint by including the credentials received 1596 from the resource owner. When making the request, the client 1597 authenticates with the authorization server. 1599 (C) The authorization server authenticates the client and validates 1600 the resource owner credentials, and if valid issues an access 1601 token. 1603 4.3.1. Authorization Request and Response 1605 The method through which the client obtains the resource owner 1606 credentials is beyond the scope of this specification. The client 1607 MUST discard the credentials once an access token has been obtained. 1609 4.3.2. Access Token Request 1611 The client makes a request to the token endpoint by adding the 1612 following parameters using the "application/x-www-form-urlencoded" 1613 format in the HTTP request entity-body: 1615 grant_type 1616 REQUIRED. Value MUST be set to "password". 1617 username 1618 REQUIRED. The resource owner username, encoded as UTF-8. 1619 password 1620 REQUIRED. The resource owner password, encoded as UTF-8. 1621 scope 1622 OPTIONAL. The scope of the access request as described by 1623 Section 3.3. 1625 If the client type is confidential or the client was issued client 1626 credentials (or assigned other authentication requirements), the 1627 client MUST authenticate with the authorization server as described 1628 in Section 3.2.1. 1630 For example, the client makes the following HTTP request using 1631 transport-layer security (extra line breaks are for display purposes 1632 only): 1634 POST /token HTTP/1.1 1635 Host: server.example.com 1636 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1637 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1639 grant_type=password&username=johndoe&password=A3ddj3w 1641 The authorization server MUST: 1643 o require client authentication for confidential clients or for any 1644 client that was issued client credentials (or with other 1645 authentication requirements), 1646 o authenticate the client if client authentication is included, and 1647 o validate the resource owner password credentials using its 1648 existing password validation algorithm. 1650 Since this access token request utilizes the resource owner's 1651 password, the authorization server MUST protect the endpoint against 1652 brute force attacks (e.g. using rate-limitation or generating 1653 alerts). 1655 4.3.3. Access Token Response 1657 If the access token request is valid and authorized, the 1658 authorization server issues an access token and optional refresh 1659 token as described in Section 5.1. If the request failed client 1660 authentication or is invalid, the authorization server returns an 1661 error response as described in Section 5.2. 1663 An example successful response: 1665 HTTP/1.1 200 OK 1666 Content-Type: application/json;charset=UTF-8 1667 Cache-Control: no-store 1668 Pragma: no-cache 1670 { 1671 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1672 "token_type":"example", 1673 "expires_in":3600, 1674 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1675 "example_parameter":"example_value" 1676 } 1678 4.4. Client Credentials Grant 1680 The client can request an access token using only its client 1681 credentials (or other supported means of authentication) when the 1682 client is requesting access to the protected resources under its 1683 control, or those of another resource owner which has been previously 1684 arranged with the authorization server (the method of which is beyond 1685 the scope of this specification). 1687 The client credentials grant type MUST only be used by confidential 1688 clients. 1690 +---------+ +---------------+ 1691 | | | | 1692 | |>--(A)- Client Authentication --->| Authorization | 1693 | Client | | Server | 1694 | |<--(B)---- Access Token ---------<| | 1695 | | | | 1696 +---------+ +---------------+ 1698 Figure 6: Client Credentials Flow 1700 The flow illustrated in Figure 6 includes the following steps: 1702 (A) The client authenticates with the authorization server and 1703 requests an access token from the token endpoint. 1704 (B) The authorization server authenticates the client, and if valid 1705 issues an access token. 1707 4.4.1. Authorization Request and Response 1709 Since the client authentication is used as the authorization grant, 1710 no additional authorization request is needed. 1712 4.4.2. Access Token Request 1714 The client makes a request to the token endpoint by adding the 1715 following parameters using the "application/x-www-form-urlencoded" 1716 format in the HTTP request entity-body: 1718 grant_type 1719 REQUIRED. Value MUST be set to "client_credentials". 1720 scope 1721 OPTIONAL. The scope of the access request as described by 1722 Section 3.3. 1724 The client MUST authenticate with the authorization server as 1725 described in Section 3.2.1. 1727 For example, the client makes the following HTTP request using 1728 transport-layer security (extra line breaks are for display purposes 1729 only): 1731 POST /token HTTP/1.1 1732 Host: server.example.com 1733 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1734 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1735 grant_type=client_credentials 1737 The authorization server MUST authenticate the client. 1739 4.4.3. Access Token Response 1741 If the access token request is valid and authorized, the 1742 authorization server issues an access token as described in 1743 Section 5.1. A refresh token SHOULD NOT be included. If the request 1744 failed client authentication or is invalid, the authorization server 1745 returns an error response as described in Section 5.2. 1747 An example successful response: 1749 HTTP/1.1 200 OK 1750 Content-Type: application/json;charset=UTF-8 1751 Cache-Control: no-store 1752 Pragma: no-cache 1754 { 1755 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1756 "token_type":"example", 1757 "expires_in":3600, 1758 "example_parameter":"example_value" 1759 } 1761 4.5. Extension Grants 1763 The client uses an extension grant type by specifying the grant type 1764 using an absolute URI (defined by the authorization server) as the 1765 value of the "grant_type" parameter of the token endpoint, and by 1766 adding any additional parameters necessary. 1768 For example, to request an access token using a SAML 2.0 assertion 1769 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1770 makes the following HTTP request using TLS (line breaks are for 1771 display purposes only): 1773 POST /token HTTP/1.1 1774 Host: server.example.com 1775 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1777 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1778 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1780 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1782 If the access token request is valid and authorized, the 1783 authorization server issues an access token and optional refresh 1784 token as described in Section 5.1. If the request failed client 1785 authentication or is invalid, the authorization server returns an 1786 error response as described in Section 5.2. 1788 5. Issuing an Access Token 1790 If the access token request is valid and authorized, the 1791 authorization server issues an access token and optional refresh 1792 token as described in Section 5.1. If the request failed client 1793 authentication or is invalid, the authorization server returns an 1794 error response as described in Section 5.2. 1796 5.1. Successful Response 1798 The authorization server issues an access token and optional refresh 1799 token, and constructs the response by adding the following parameters 1800 to the entity body of the HTTP response with a 200 (OK) status code: 1802 access_token 1803 REQUIRED. The access token issued by the authorization server. 1804 token_type 1805 REQUIRED. The type of the token issued as described in 1806 Section 7.1. Value is case insensitive. 1807 expires_in 1808 RECOMMENDED. The lifetime in seconds of the access token. For 1809 example, the value "3600" denotes that the access token will 1810 expire in one hour from the time the response was generated. 1811 If omitted, the authorization server SHOULD provide the 1812 expiration time via other means or document the default value. 1813 refresh_token 1814 OPTIONAL. The refresh token which can be used to obtain new 1815 access tokens using the same authorization grant as described 1816 in Section 6. 1817 scope 1818 OPTIONAL, if identical to the scope requested by the client, 1819 otherwise REQUIRED. The scope of the access token as described 1820 by Section 3.3. 1822 The parameters are included in the entity body of the HTTP response 1823 using the "application/json" media type as defined by [RFC4627]. The 1824 parameters are serialized into a JSON structure by adding each 1825 parameter at the highest structure level. Parameter names and string 1826 values are included as JSON strings. Numerical values are included 1827 as JSON numbers. The order of parameters does not matter and can 1828 vary. 1830 The authorization server MUST include the HTTP "Cache-Control" 1831 response header field [RFC2616] with a value of "no-store" in any 1832 response containing tokens, credentials, or other sensitive 1833 information, as well as the "Pragma" response header field [RFC2616] 1834 with a value of "no-cache". 1836 For example: 1838 HTTP/1.1 200 OK 1839 Content-Type: application/json;charset=UTF-8 1840 Cache-Control: no-store 1841 Pragma: no-cache 1843 { 1844 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1845 "token_type":"example", 1846 "expires_in":3600, 1847 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1848 "example_parameter":"example_value" 1849 } 1851 The client MUST ignore unrecognized value names in the response. The 1852 sizes of tokens and other values received from the authorization 1853 server are left undefined. The client should avoid making 1854 assumptions about value sizes. The authorization server SHOULD 1855 document the size of any value it issues. 1857 5.2. Error Response 1859 The authorization server responds with an HTTP 400 (Bad Request) 1860 status code (unless specified otherwise) and includes the following 1861 parameters with the response: 1863 error 1864 REQUIRED. A single ASCII [USASCII] error code from the 1865 following: 1866 invalid_request 1867 The request is missing a required parameter, includes an 1868 unsupported parameter value (other than grant type), 1869 repeats a parameter, includes multiple credentials, 1870 utilizes more than one mechanism for authenticating the 1871 client, or is otherwise malformed. 1873 invalid_client 1874 Client authentication failed (e.g. unknown client, no 1875 client authentication included, or unsupported 1876 authentication method). The authorization server MAY 1877 return an HTTP 401 (Unauthorized) status code to indicate 1878 which HTTP authentication schemes are supported. If the 1879 client attempted to authenticate via the "Authorization" 1880 request header field, the authorization server MUST 1881 respond with an HTTP 401 (Unauthorized) status code, and 1882 include the "WWW-Authenticate" response header field 1883 matching the authentication scheme used by the client. 1884 invalid_grant 1885 The provided authorization grant (e.g. authorization 1886 code, resource owner credentials) or refresh token is 1887 invalid, expired, revoked, does not match the redirection 1888 URI used in the authorization request, or was issued to 1889 another client. 1890 unauthorized_client 1891 The authenticated client is not authorized to use this 1892 authorization grant type. 1893 unsupported_grant_type 1894 The authorization grant type is not supported by the 1895 authorization server. 1896 invalid_scope 1897 The requested scope is invalid, unknown, malformed, or 1898 exceeds the scope granted by the resource owner. 1899 Values for the "error" parameter MUST NOT include characters 1900 outside the set %x20-21 / %x23-5B / %x5D-7E. 1901 error_description 1902 OPTIONAL. A human-readable ASCII [USASCII] text providing 1903 additional information, used to assist the client developer in 1904 understanding the error that occurred. 1905 Values for the "error_description" parameter MUST NOT include 1906 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1907 error_uri 1908 OPTIONAL. A URI identifying a human-readable web page with 1909 information about the error, used to provide the client 1910 developer with additional information about the error. 1911 Values for the "error_uri" parameter MUST conform to the URI- 1912 Reference syntax, and thus MUST NOT include characters outside 1913 the set %x21 / %x23-5B / %x5D-7E. 1915 The parameters are included in the entity body of the HTTP response 1916 using the "application/json" media type as defined by [RFC4627]. The 1917 parameters are serialized into a JSON structure by adding each 1918 parameter at the highest structure level. Parameter names and string 1919 values are included as JSON strings. Numerical values are included 1920 as JSON numbers. The order of parameters does not matter and can 1921 vary. 1923 For example: 1925 HTTP/1.1 400 Bad Request 1926 Content-Type: application/json;charset=UTF-8 1927 Cache-Control: no-store 1928 Pragma: no-cache 1930 { 1931 "error":"invalid_request" 1932 } 1934 6. Refreshing an Access Token 1936 If the authorization server issued a refresh token to the client, the 1937 client makes a refresh request to the token endpoint by adding the 1938 following parameters using the "application/x-www-form-urlencoded" 1939 format in the HTTP request entity-body: 1941 grant_type 1942 REQUIRED. Value MUST be set to "refresh_token". 1943 refresh_token 1944 REQUIRED. The refresh token issued to the client. 1945 scope 1946 OPTIONAL. The scope of the access request as described by 1947 Section 3.3. The requested scope MUST NOT include any scope 1948 not originally granted by the resource owner, and if omitted is 1949 treated as equal to the scope originally granted by the 1950 resource owner. 1952 Because refresh tokens are typically long-lasting credentials used to 1953 request additional access tokens, the refresh token is bound to the 1954 client which it was issued. If the client type is confidential or 1955 the client was issued client credentials (or assigned other 1956 authentication requirements), the client MUST authenticate with the 1957 authorization server as described in Section 3.2.1. 1959 For example, the client makes the following HTTP request using 1960 transport-layer security (extra line breaks are for display purposes 1961 only): 1963 POST /token HTTP/1.1 1964 Host: server.example.com 1965 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1966 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1968 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1970 The authorization server MUST: 1972 o require client authentication for confidential clients or for any 1973 client that was issued client credentials (or with other 1974 authentication requirements), 1975 o authenticate the client if client authentication is included and 1976 ensure the refresh token was issued to the authenticated client, 1977 and 1978 o validate the refresh token. 1980 If valid and authorized, the authorization server issues an access 1981 token as described in Section 5.1. If the request failed 1982 verification or is invalid, the authorization server returns an error 1983 response as described in Section 5.2. 1985 The authorization server MAY issue a new refresh token, in which case 1986 the client MUST discard the old refresh token and replace it with the 1987 new refresh token. The authorization server MAY revoke the old 1988 refresh token after issuing a new refresh token to the client. If a 1989 new refresh token is issued, the refresh token scope MUST be 1990 identical to that of the refresh token included by the client in the 1991 request. 1993 7. Accessing Protected Resources 1995 The client accesses protected resources by presenting the access 1996 token to the resource server. The resource server MUST validate the 1997 access token and ensure it has not expired and that its scope covers 1998 the requested resource. The methods used by the resource server to 1999 validate the access token (as well as any error responses) are beyond 2000 the scope of this specification, but generally involve an interaction 2001 or coordination between the resource server and the authorization 2002 server. 2004 The method in which the client utilizes the access token to 2005 authenticate with the resource server depends on the type of access 2006 token issued by the authorization server. Typically, it involves 2007 using the HTTP "Authorization" request header field [RFC2617] with an 2008 authentication scheme defined by the access token type specification. 2010 7.1. Access Token Types 2012 The access token type provides the client with the information 2013 required to successfully utilize the access token to make a protected 2014 resource request (along with type-specific attributes). The client 2015 MUST NOT use an access token if it does not understand the token 2016 type. 2018 For example, the "bearer" token type defined in 2019 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 2020 token string in the request: 2022 GET /resource/1 HTTP/1.1 2023 Host: example.com 2024 Authorization: Bearer mF_9.B5f-4.1JqM 2026 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 2027 utilized by issuing a MAC key together with the access token which is 2028 used to sign certain components of the HTTP requests: 2030 GET /resource/1 HTTP/1.1 2031 Host: example.com 2032 Authorization: MAC id="h480djs93hd8", 2033 nonce="274312:dj83hs9s", 2034 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 2036 The above examples are provided for illustration purposes only. 2037 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 2038 [I-D.ietf-oauth-v2-http-mac] specifications before use. 2040 Each access token type definition specifies the additional attributes 2041 (if any) sent to the client together with the "access_token" response 2042 parameter. It also defines the HTTP authentication method used to 2043 include the access token when making a protected resource request. 2045 7.2. Error Response 2047 If a resource access request fails, the resource server SHOULD inform 2048 the client of the error. While the specific error responses possible 2049 and methods for transmitting those errors when using any particular 2050 access token type are beyond the scope of this specification, any 2051 "error" code values defined for use with OAuth resource access 2052 methods MUST be registered (following the procedures in 2053 Section 11.4). 2055 Specifically, when the OAuth resource access method uses an "error" 2056 result parameter to return an error code value that indicates the 2057 resource access error encountered, then these error code values MUST 2058 be registered. Values for these "error" codes MUST NOT include 2059 characters outside the set %x20-21 / %x23-5B / %x5D-7E. When an 2060 "error" code value is registered for use by an OAuth resource access 2061 method, should that same code already be registered for use by 2062 another OAuth resource access method or at a different OAuth error 2063 usage location, then the meaning of that error code value in in the 2064 new registration MUST be consistent with the its meaning in prior 2065 registrations. 2067 The OAuth resource access error registration requirement applies only 2068 to "error" code values and not to other means of returning error 2069 indications, including HTTP status codes, or other error-related 2070 result parameters, such as "error_description", "error_uri", or other 2071 kinds of error status return methods that may be employed by the 2072 resource access method. There is no requirement that OAuth resource 2073 access methods employ an "error" parameter. 2075 8. Extensibility 2077 8.1. Defining Access Token Types 2079 Access token types can be defined in one of two ways: registered in 2080 the access token type registry (following the procedures in 2081 Section 11.1), or by using a unique absolute URI as its name. 2083 Types utilizing a URI name SHOULD be limited to vendor-specific 2084 implementations that are not commonly applicable, and are specific to 2085 the implementation details of the resource server where they are 2086 used. 2088 All other types MUST be registered. Type names MUST conform to the 2089 type-name ABNF. If the type definition includes a new HTTP 2090 authentication scheme, the type name SHOULD be identical to the HTTP 2091 authentication scheme name (as defined by [RFC2617]). The token type 2092 "example" is reserved for use in examples. 2094 type-name = 1*name-char 2095 name-char = "-" / "." / "_" / DIGIT / ALPHA 2097 8.2. Defining New Endpoint Parameters 2099 New request or response parameters for use with the authorization 2100 endpoint or the token endpoint are defined and registered in the 2101 parameters registry following the procedure in Section 11.2. 2103 Parameter names MUST conform to the param-name ABNF and parameter 2104 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2105 to the syntax of an existing parameter). 2107 param-name = 1*name-char 2108 name-char = "-" / "." / "_" / DIGIT / ALPHA 2110 Unregistered vendor-specific parameter extensions that are not 2111 commonly applicable, and are specific to the implementation details 2112 of the authorization server where they are used SHOULD utilize a 2113 vendor-specific prefix that is not likely to conflict with other 2114 registered values (e.g. begin with 'companyname_'). 2116 8.3. Defining New Authorization Grant Types 2118 New authorization grant types can be defined by assigning them a 2119 unique absolute URI for use with the "grant_type" parameter. If the 2120 extension grant type requires additional token endpoint parameters, 2121 they MUST be registered in the OAuth parameters registry as described 2122 by Section 11.2. 2124 8.4. Defining New Authorization Endpoint Response Types 2126 New response types for use with the authorization endpoint are 2127 defined and registered in the authorization endpoint response type 2128 registry following the procedure in Section 11.3. Response type 2129 names MUST conform to the response-type ABNF. 2131 response-type = response-name *( SP response-name ) 2132 response-name = 1*response-char 2133 response-char = "_" / DIGIT / ALPHA 2135 If a response type contains one or more space characters (%x20), it 2136 is compared as a space-delimited list of values in which the order of 2137 values does not matter. Only one order of values can be registered, 2138 which covers all other arrangements of the same set of values. 2140 For example, the response type "token code" is left undefined by this 2141 specification. However, an extension can define and register the 2142 "token code" response type. Once registered, the same combination 2143 cannot be registered as "code token", but both values can be used to 2144 denote the same response type. 2146 8.5. Defining Additional Error Codes 2148 In cases where protocol extensions (i.e. access token types, 2149 extension parameters, or extension grant types) require additional 2150 error codes to be used with the authorization code grant error 2151 response (Section 4.1.2.1), the implicit grant error response 2152 (Section 4.2.2.1), the token error response (Section 5.2), or the 2153 resource access error response (Section 7.2), such error codes MAY be 2154 defined. 2156 Extension error codes MUST be registered (following the procedures in 2157 Section 11.4) if the extension they are used in conjunction with is a 2158 registered access token type, a registered endpoint parameter, or an 2159 extension grant type. Error codes used with unregistered extensions 2160 MAY be registered. 2162 Error codes MUST conform to the error ABNF, and SHOULD be prefixed by 2163 an identifying name when possible. For example, an error identifying 2164 an invalid value set to the extension parameter "example" SHOULD be 2165 named "example_invalid". 2167 error = 1*error-char 2168 error-char = %x20-21 / %x23-5B / %x5D-7E 2170 9. Native Applications 2172 Native applications are clients installed and executed on the device 2173 used by the resource owner (i.e. desktop application, native mobile 2174 application). Native applications require special consideration 2175 related to security, platform capabilities, and overall end-user 2176 experience. 2178 The authorization endpoint requires interaction between the client 2179 and the resource owner's user-agent. Native applications can invoke 2180 an external user-agent or embed a user-agent within the application. 2181 For example: 2183 o External user-agent - the native application can capture the 2184 response from the authorization server using a redirection URI 2185 with a scheme registered with the operating system to invoke the 2186 client as the handler, manual copy-and-paste of the credentials, 2187 running a local web server, installing a user-agent extension, or 2188 by providing a redirection URI identifying a server-hosted 2189 resource under the client's control, which in turn makes the 2190 response available to the native application. 2191 o Embedded user-agent - the native application obtains the response 2192 by directly communicating with the embedded user-agent by 2193 monitoring state changes emitted during the resource load, or 2194 accessing the user-agent's cookies storage. 2196 When choosing between an external or embedded user-agent, developers 2197 should consider: 2199 o An External user-agent may improve completion rate as the resource 2200 owner may already have an active session with the authorization 2201 server removing the need to re-authenticate. It provides a 2202 familiar end-user experience and functionality. The resource 2203 owner may also rely on user-agent features or extensions to assist 2204 with authentication (e.g. password manager, 2-factor device 2205 reader). 2206 o An embedded user-agent may offer improved usability, as it removes 2207 the need to switch context and open new windows. 2208 o An embedded user-agent poses a security challenge because resource 2209 owners are authenticating in an unidentified window without access 2210 to the visual protections found in most external user-agents. An 2211 embedded user-agent educates end-users to trust unidentified 2212 requests for authentication (making phishing attacks easier to 2213 execute). 2215 When choosing between the implicit grant type and the authorization 2216 code grant type, the following should be considered: 2218 o Native applications that use the authorization code grant type 2219 SHOULD do so without using client credentials, due to the native 2220 application's inability to keep client credentials confidential. 2221 o When using the implicit grant type flow a refresh token is not 2222 returned which requires repeating the authorization process once 2223 the access token expires. 2225 10. Security Considerations 2227 As a flexible and extensible framework, OAuth's security 2228 considerations depend on many factors. The following sections 2229 provide implementers with security guidelines focused on the three 2230 client profiles described in Section 2.1: web application, user- 2231 agent-based application, and native application. 2233 A comprehensive OAuth security model and analysis, as well as 2234 background for the protocol design is provided by 2235 [I-D.ietf-oauth-v2-threatmodel]. 2237 10.1. Client Authentication 2239 The authorization server establishes client credentials with web 2240 application clients for the purpose of client authentication. The 2241 authorization server is encouraged to consider stronger client 2242 authentication means than a client password. Web application clients 2243 MUST ensure confidentiality of client passwords and other client 2244 credentials. 2246 The authorization server MUST NOT issue client passwords or other 2247 client credentials to native application or user-agent-based 2248 application clients for the purpose of client authentication. The 2249 authorization server MAY issue a client password or other credentials 2250 for a specific installation of a native application client on a 2251 specific device. 2253 When client authentication is not possible, the authorization server 2254 SHOULD employ other means to validate the client's identity. For 2255 example, by requiring the registration of the client redirection URI 2256 or enlisting the resource owner to confirm identity. A valid 2257 redirection URI is not sufficient to verify the client's identity 2258 when asking for resource owner authorization, but can be used to 2259 prevent delivering credentials to a counterfeit client after 2260 obtaining resource owner authorization. 2262 The authorization server must consider the security implications of 2263 interacting with unauthenticated clients and take measures to limit 2264 the potential exposure of other credentials (e.g. refresh tokens) 2265 issued to such clients. 2267 10.2. Client Impersonation 2269 A malicious client can impersonate another client and obtain access 2270 to protected resources, if the impersonated client fails to, or is 2271 unable to, keep its client credentials confidential. 2273 The authorization server MUST authenticate the client whenever 2274 possible. If the authorization server cannot authenticate the client 2275 due to the client's nature, the authorization server MUST require the 2276 registration of any redirection URI used for receiving authorization 2277 responses, and SHOULD utilize other means to protect resource owners 2278 from such potentially malicious clients. For example, the 2279 authorization server can engage the resource owner to assist in 2280 identifying the client and its origin. 2282 The authorization server SHOULD enforce explicit resource owner 2283 authentication and provide the resource owner with information about 2284 the client and the requested authorization scope and lifetime. It is 2285 up to the resource owner to review the information in the context of 2286 the current client, and authorize or deny the request. 2288 The authorization server SHOULD NOT process repeated authorization 2289 requests automatically (without active resource owner interaction) 2290 without authenticating the client or relying on other measures to 2291 ensure the repeated request comes from the original client and not an 2292 impersonator. 2294 10.3. Access Tokens 2296 Access token credentials (as well as any confidential access token 2297 attributes) MUST be kept confidential in transit and storage, and 2298 only shared among the authorization server, the resource servers the 2299 access token is valid for, and the client to whom the access token is 2300 issued. Access token credentials MUST only be transmitted using TLS 2301 as described in Section 1.6 with server authentication as defined by 2302 [RFC2818]. 2304 When using the implicit grant type, the access token is transmitted 2305 in the URI fragment, which can expose it to unauthorized parties. 2307 The authorization server MUST ensure that access tokens cannot be 2308 generated, modified, or guessed to produce valid access tokens by 2309 unauthorized parties. 2311 The client SHOULD request access tokens with the minimal scope 2312 necessary. The authorization server SHOULD take the client identity 2313 into account when choosing how to honor the requested scope, and MAY 2314 issue an access token with a less rights than requested. 2316 This specification does not provide any methods for the resource 2317 server to ensure that an access token presented to it by a given 2318 client was issued to that client by the authorization server. 2320 10.4. Refresh Tokens 2322 Authorization servers MAY issue refresh tokens to web application 2323 clients and native application clients. 2325 Refresh tokens MUST be kept confidential in transit and storage, and 2326 shared only among the authorization server and the client to whom the 2327 refresh tokens were issued. The authorization server MUST maintain 2328 the binding between a refresh token and the client to whom it was 2329 issued. Refresh tokens MUST only be transmitted using TLS as 2330 described in Section 1.6 with server authentication as defined by 2331 [RFC2818]. 2333 The authorization server MUST verify the binding between the refresh 2334 token and client identity whenever the client identity can be 2335 authenticated. When client authentication is not possible, the 2336 authorization server SHOULD deploy other means to detect refresh 2337 token abuse. 2339 For example, the authorization server could employ refresh token 2340 rotation in which a new refresh token is issued with every access 2341 token refresh response. The previous refresh token is invalidated 2342 but retained by the authorization server. If a refresh token is 2343 compromised and subsequently used by both the attacker and the 2344 legitimate client, one of them will present an invalidated refresh 2345 token which will inform the authorization server of the breach. 2347 The authorization server MUST ensure that refresh tokens cannot be 2348 generated, modified, or guessed to produce valid refresh tokens by 2349 unauthorized parties. 2351 10.5. Authorization Codes 2353 The transmission of authorization codes SHOULD be made over a secure 2354 channel, and the client SHOULD require the use of TLS with its 2355 redirection URI if the URI identifies a network resource. Since 2356 authorization codes are transmitted via user-agent redirections, they 2357 could potentially be disclosed through user-agent history and HTTP 2358 referrer headers. 2360 Authorization codes operate as plaintext bearer credentials, used to 2361 verify that the resource owner who granted authorization at the 2362 authorization server is the same resource owner returning to the 2363 client to complete the process. Therefore, if the client relies on 2364 the authorization code for its own resource owner authentication, the 2365 client redirection endpoint MUST require the use of TLS. 2367 Authorization codes MUST be short lived and single use. If the 2368 authorization server observes multiple attempts to exchange an 2369 authorization code for an access token, the authorization server 2370 SHOULD attempt to revoke all access tokens already granted based on 2371 the compromised authorization code. 2373 If the client can be authenticated, the authorization servers MUST 2374 authenticate the client and ensure that the authorization code was 2375 issued to the same client. 2377 10.6. Authorization Code Redirection URI Manipulation 2379 When requesting authorization using the authorization code grant 2380 type, the client can specify a redirection URI via the "redirect_uri" 2381 parameter. If an attacker can manipulate the value of the 2382 redirection URI, it can cause the authorization server to redirect 2383 the resource owner user-agent to a URI under the control of the 2384 attacker with the authorization code. 2386 An attacker can create an account at a legitimate client and initiate 2387 the authorization flow. When the attacker's user-agent is sent to 2388 the authorization server to grant access, the attacker grabs the 2389 authorization URI provided by the legitimate client, and replaces the 2390 client's redirection URI with a URI under the control of the 2391 attacker. The attacker then tricks the victim into following the 2392 manipulated link to authorize access to the legitimate client. 2394 Once at the authorization server, the victim is prompted with a 2395 normal, valid request on behalf of a legitimate and trusted client, 2396 and authorizes the request. The victim is then redirected to an 2397 endpoint under the control of the attacker with the authorization 2398 code. The attacker completes the authorization flow by sending the 2399 authorization code to the client using the original redirection URI 2400 provided by the client. The client exchanges the authorization code 2401 with an access token and links it to the attacker's client account 2402 which can now gain access to the protected resources authorized by 2403 the victim (via the client). 2405 In order to prevent such an attack, the authorization server MUST 2406 ensure that the redirection URI used to obtain the authorization code 2407 is identical to the redirection URI provided when exchanging the 2408 authorization code for an access token. The authorization server 2409 MUST require public clients and SHOULD require confidential clients 2410 to register their redirection URIs. If a redirection URI is provided 2411 in the request, the authorization server MUST validate it against the 2412 registered value. 2414 10.7. Resource Owner Password Credentials 2416 The resource owner password credentials grant type is often used for 2417 legacy or migration reasons. It reduces the overall risk of storing 2418 username and password by the client, but does not eliminate the need 2419 to expose highly privileged credentials to the client. 2421 This grant type carries a higher risk than other grant types because 2422 it maintains the password anti-pattern this protocol seeks to avoid. 2423 The client could abuse the password or the password could 2424 unintentionally be disclosed to an attacker (e.g. via log files or 2425 other records kept by the client). 2427 Additionally, because the resource owner does not have control over 2428 the authorization process (the resource owner involvement ends when 2429 it hands over its credentials to the client), the client can obtain 2430 access tokens with a broader scope than desired by the resource 2431 owner. The authorization server should consider the scope and 2432 lifetime of access tokens issued via this grant type. 2434 The authorization server and client SHOULD minimize use of this grant 2435 type and utilize other grant types whenever possible. 2437 10.8. Request Confidentiality 2439 Access tokens, refresh tokens, resource owner passwords, and client 2440 credentials MUST NOT be transmitted in the clear. Authorization 2441 codes SHOULD NOT be transmitted in the clear. 2443 The "state" and "scope" parameters SHOULD NOT include sensitive 2444 client or resource owner information in plain text as they can be 2445 transmitted over insecure channels or stored insecurely. 2447 10.9. Endpoints Authenticity 2449 In order to prevent man-in-the-middle attacks, the authorization 2450 server MUST require the use of TLS with server authentication as 2451 defined by [RFC2818] for any request sent to the authorization and 2452 token endpoints. The client MUST validate the authorization server's 2453 TLS certificate as defined by [RFC6125], and in accordance with its 2454 requirements for server identity authentication. 2456 10.10. Credentials Guessing Attacks 2458 The authorization server MUST prevent attackers from guessing access 2459 tokens, authorization codes, refresh tokens, resource owner 2460 passwords, and client credentials. 2462 The probability of an attacker guessing generated tokens (and other 2463 credentials not intended for handling by end-users) MUST be less than 2464 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2466 The authorization server MUST utilize other means to protect 2467 credentials intended for end-user usage. 2469 10.11. Phishing Attacks 2471 Wide deployment of this and similar protocols may cause end-users to 2472 become inured to the practice of being redirected to websites where 2473 they are asked to enter their passwords. If end-users are not 2474 careful to verify the authenticity of these websites before entering 2475 their credentials, it will be possible for attackers to exploit this 2476 practice to steal resource owners' passwords. 2478 Service providers should attempt to educate end-users about the risks 2479 phishing attacks pose, and should provide mechanisms that make it 2480 easy for end-users to confirm the authenticity of their sites. 2481 Client developers should consider the security implications of how 2482 they interact with the user-agent (e.g., external, embedded), and the 2483 ability of the end-user to verify the authenticity of the 2484 authorization server. 2486 To reduce the risk of phishing attacks, the authorization servers 2487 MUST require the use of TLS on every endpoint used for end-user 2488 interaction. 2490 10.12. Cross-Site Request Forgery 2492 Cross-site request forgery (CSRF) is an exploit in which an attacker 2493 causes the user-agent of a victim end-user to follow a malicious URI 2494 (e.g. provided to the user-agent as a misleading link, image, or 2495 redirection) to a trusting server (usually established via the 2496 presence of a valid session cookie). 2498 A CSRF attack against the client's redirection URI allows an attacker 2499 to inject their own authorization code or access token, which can 2500 result in the client using an access token associated with the 2501 attacker's protected resources rather than the victim's (e.g. save 2502 the victim's bank account information to a protected resource 2503 controlled by the attacker). 2505 The client MUST implement CSRF protection for its redirection URI. 2506 This is typically accomplished by requiring any request sent to the 2507 redirection URI endpoint to include a value that binds the request to 2508 the user-agent's authenticated state (e.g. a hash of the session 2509 cookie used to authenticate the user-agent). The client SHOULD 2510 utilize the "state" request parameter to deliver this value to the 2511 authorization server when making an authorization request. 2513 Once authorization has been obtained from the end-user, the 2514 authorization server redirects the end-user's user-agent back to the 2515 client with the required binding value contained in the "state" 2516 parameter. The binding value enables the client to verify the 2517 validity of the request by matching the binding value to the user- 2518 agent's authenticated state. The binding value used for CSRF 2519 protection MUST contain a non-guessable value (as described in 2520 Section 10.10), and the user-agent's authenticated state (e.g. 2521 session cookie, HTML5 local storage) MUST be kept in a location 2522 accessible only to the client and the user-agent (i.e., protected by 2523 same-origin policy). 2525 A CSRF attack against the authorization server's authorization 2526 endpoint can result in an attacker obtaining end-user authorization 2527 for a malicious client without involving or alerting the end-user. 2529 The authorization server MUST implement CSRF protection for its 2530 authorization endpoint, and ensure that a malicious client cannot 2531 obtain authorization without the awareness and explicit consent of 2532 the resource owner. 2534 10.13. Clickjacking 2536 In a clickjacking attack, an attacker registers a legitimate client 2537 and then constructs a malicious site in which it loads the 2538 authorization server's authorization endpoint web page in a 2539 transparent iframe overlaid on top of a set of dummy buttons which 2540 are carefully constructed to be placed directly under important 2541 buttons on the authorization page. When an end-user clicks a 2542 misleading visible button, the end-user is actually clicking an 2543 invisible button on the authorization page (such as an "Authorize" 2544 button). This allows an attacker to trick a resource owner into 2545 granting its client access without their knowledge. 2547 To prevent this form of attack, native applications SHOULD use 2548 external browsers instead of embedding browsers within the 2549 application when requesting end-user authorization. For most newer 2550 browsers, avoidance of iframes can be enforced by the authorization 2551 server using the (non-standard) "x-frame-options" header. This 2552 header can have two values, "deny" and "sameorigin", which will block 2553 any framing, or framing by sites with a different origin, 2554 respectively. For older browsers, JavaScript framebusting techniques 2555 can be used but may not be effective in all browsers. 2557 10.14. Code Injection and Input Validation 2559 A code injection attack occurs when an input or otherwise external 2560 variable is used by an application unsanitized and causes 2561 modification to the application logic. This may allow an attacker to 2562 gain access to the application device or its data, cause denial of 2563 service, or a wide range of malicious side-effects. 2565 The Authorization server and client MUST sanitize (and validate when 2566 possible) any value received, in particular, the value of the "state" 2567 and "redirect_uri" parameters. 2569 10.15. Open Redirectors 2571 The authorization server authorization endpoint and the client 2572 redirection endpoint can be improperly configured and operate as open 2573 redirectors. An open redirector is an endpoint using a parameter to 2574 automatically redirect a user-agent to the location specified by the 2575 parameter value without any validation. 2577 Open redirectors can be used in phishing attacks, or by an attacker 2578 to get end-users to visit malicious sites by making the URI's 2579 authority look like a familiar and trusted destination. In addition, 2580 if the authorization server allows the client to register only part 2581 of the redirection URI, an attacker can use an open redirector 2582 operated by the client to construct a redirection URI that will pass 2583 the authorization server validation but will send the authorization 2584 code or access token to an endpoint under the control of the 2585 attacker. 2587 11. IANA Considerations 2589 11.1. The OAuth Access Token Type Registry 2591 This specification establishes the OAuth access token type registry. 2593 Access token types are registered with a Specification Required 2594 ([RFC5226]) after a two week review period on the [TBD]@ietf.org 2595 mailing list, on the advice of one or more Designated Experts. 2596 However, to allow for the allocation of values prior to publication, 2597 the Designated Expert(s) may approve registration once they are 2598 satisfied that such a specification will be published. 2600 Registration requests must be sent to the [TBD]@ietf.org mailing list 2601 for review and comment, with an appropriate subject (e.g., "Request 2602 for access token type: example"). [[ Note to RFC-EDITOR: The name of 2603 the mailing list should be determined in consultation with the IESG 2604 and IANA. Suggested name: oauth-ext-review. ]] 2606 Within the review period, the Designated Expert(s) will either 2607 approve or deny the registration request, communicating this decision 2608 to the review list and IANA. Denials should include an explanation 2609 and, if applicable, suggestions as to how to make the request 2610 successful. 2612 IANA must only accept registry updates from the Designated Expert(s), 2613 and should direct all requests for registration to the review mailing 2614 list. 2616 11.1.1. Registration Template 2618 Type name: 2619 The name requested (e.g., "example"). 2620 Additional Token Endpoint Response Parameters: 2621 Additional response parameters returned together with the 2622 "access_token" parameter. New parameters MUST be separately 2623 registered in the OAuth parameters registry as described by 2624 Section 11.2. 2625 HTTP Authentication Scheme(s): 2626 The HTTP authentication scheme name(s), if any, used to 2627 authenticate protected resources requests using access tokens of 2628 this type. 2629 Change controller: 2630 For standards-track RFCs, state "IETF". For others, give the name 2631 of the responsible party. Other details (e.g., postal address, 2632 e-mail address, home page URI) may also be included. 2633 Specification document(s): 2634 Reference to the document that specifies the parameter, preferably 2635 including a URI that can be used to retrieve a copy of the 2636 document. An indication of the relevant sections may also be 2637 included, but is not required. 2639 11.2. The OAuth Parameters Registry 2641 This specification establishes the OAuth parameters registry. 2643 Additional parameters for inclusion in the authorization endpoint 2644 request, the authorization endpoint response, the token endpoint 2645 request, or the token endpoint response are registered with a 2646 Specification Required ([RFC5226]) after a two week review period on 2647 the [TBD]@ietf.org mailing list, on the advice of one or more 2648 Designated Experts. However, to allow for the allocation of values 2649 prior to publication, the Designated Expert(s) may approve 2650 registration once they are satisfied that such a specification will 2651 be published. 2653 Registration requests must be sent to the [TBD]@ietf.org mailing list 2654 for review and comment, with an appropriate subject (e.g., "Request 2655 for parameter: example"). [[ Note to RFC-EDITOR: The name of the 2656 mailing list should be determined in consultation with the IESG and 2657 IANA. Suggested name: oauth-ext-review. ]] 2659 Within the review period, the Designated Expert(s) will either 2660 approve or deny the registration request, communicating this decision 2661 to the review list and IANA. Denials should include an explanation 2662 and, if applicable, suggestions as to how to make the request 2663 successful. 2665 IANA must only accept registry updates from the Designated Expert(s), 2666 and should direct all requests for registration to the review mailing 2667 list. 2669 11.2.1. Registration Template 2671 Parameter name: 2672 The name requested (e.g., "example"). 2673 Parameter usage location: 2674 The location(s) where parameter can be used. The possible 2675 locations are: authorization request, authorization response, 2676 token request, or token response. 2677 Change controller: 2678 For standards-track RFCs, state "IETF". For others, give the name 2679 of the responsible party. Other details (e.g., postal address, 2680 e-mail address, home page URI) may also be included. 2681 Specification document(s): 2682 Reference to the document that specifies the parameter, preferably 2683 including a URI that can be used to retrieve a copy of the 2684 document. An indication of the relevant sections may also be 2685 included, but is not required. 2687 11.2.2. Initial Registry Contents 2689 The OAuth Parameters Registry's initial contents are: 2691 o Parameter name: client_id 2692 o Parameter usage location: authorization request, token request 2693 o Change controller: IETF 2694 o Specification document(s): [[ this document ]] 2696 o Parameter name: client_secret 2697 o Parameter usage location: token request 2698 o Change controller: IETF 2699 o Specification document(s): [[ this document ]] 2701 o Parameter name: response_type 2702 o Parameter usage location: authorization request 2703 o Change controller: IETF 2704 o Specification document(s): [[ this document ]] 2706 o Parameter name: redirect_uri 2707 o Parameter usage location: authorization request, token request 2708 o Change controller: IETF 2709 o Specification document(s): [[ this document ]] 2711 o Parameter name: scope 2712 o Parameter usage location: authorization request, authorization 2713 response, token request, token response 2714 o Change controller: IETF 2715 o Specification document(s): [[ this document ]] 2717 o Parameter name: state 2718 o Parameter usage location: authorization request, authorization 2719 response 2720 o Change controller: IETF 2721 o Specification document(s): [[ this document ]] 2723 o Parameter name: code 2724 o Parameter usage location: authorization response, token request 2725 o Change controller: IETF 2726 o Specification document(s): [[ this document ]] 2728 o Parameter name: error_description 2729 o Parameter usage location: authorization response, token response 2730 o Change controller: IETF 2731 o Specification document(s): [[ this document ]] 2733 o Parameter name: error_uri 2734 o Parameter usage location: authorization response, token response 2735 o Change controller: IETF 2736 o Specification document(s): [[ this document ]] 2738 o Parameter name: grant_type 2739 o Parameter usage location: token request 2740 o Change controller: IETF 2741 o Specification document(s): [[ this document ]] 2743 o Parameter name: access_token 2744 o Parameter usage location: authorization response, token response 2745 o Change controller: IETF 2746 o Specification document(s): [[ this document ]] 2748 o Parameter name: token_type 2749 o Parameter usage location: authorization response, token response 2750 o Change controller: IETF 2751 o Specification document(s): [[ this document ]] 2753 o Parameter name: expires_in 2754 o Parameter usage location: authorization response, token response 2755 o Change controller: IETF 2756 o Specification document(s): [[ this document ]] 2758 o Parameter name: username 2759 o Parameter usage location: token request 2760 o Change controller: IETF 2761 o Specification document(s): [[ this document ]] 2763 o Parameter name: password 2764 o Parameter usage location: token request 2765 o Change controller: IETF 2766 o Specification document(s): [[ this document ]] 2768 o Parameter name: refresh_token 2769 o Parameter usage location: token request, token response 2770 o Change controller: IETF 2771 o Specification document(s): [[ this document ]] 2773 11.3. The OAuth Authorization Endpoint Response Type Registry 2775 This specification establishes the OAuth authorization endpoint 2776 response type registry. 2778 Additional response type for use with the authorization endpoint are 2779 registered with a Specification Required ([RFC5226]) after a two week 2780 review period on the [TBD]@ietf.org mailing list, on the advice of 2781 one or more Designated Experts. However, to allow for the allocation 2782 of values prior to publication, the Designated Expert(s) may approve 2783 registration once they are satisfied that such a specification will 2784 be published. 2786 Registration requests must be sent to the [TBD]@ietf.org mailing list 2787 for review and comment, with an appropriate subject (e.g., "Request 2788 for response type: example"). [[ Note to RFC-EDITOR: The name of the 2789 mailing list should be determined in consultation with the IESG and 2790 IANA. Suggested name: oauth-ext-review. ]] 2792 Within the review period, the Designated Expert(s) will either 2793 approve or deny the registration request, communicating this decision 2794 to the review list and IANA. Denials should include an explanation 2795 and, if applicable, suggestions as to how to make the request 2796 successful. 2798 IANA must only accept registry updates from the Designated Expert(s), 2799 and should direct all requests for registration to the review mailing 2800 list. 2802 11.3.1. Registration Template 2804 Response type name: 2805 The name requested (e.g., "example"). 2806 Change controller: 2807 For standards-track RFCs, state "IETF". For others, give the name 2808 of the responsible party. Other details (e.g., postal address, 2809 e-mail address, home page URI) may also be included. 2810 Specification document(s): 2811 Reference to the document that specifies the type, preferably 2812 including a URI that can be used to retrieve a copy of the 2813 document. An indication of the relevant sections may also be 2814 included, but is not required. 2816 11.3.2. Initial Registry Contents 2818 The OAuth Authorization Endpoint Response Type Registry's initial 2819 contents are: 2821 o Response type name: code 2822 o Change controller: IETF 2823 o Specification document(s): [[ this document ]] 2825 o Response type name: token 2826 o Change controller: IETF 2827 o Specification document(s): [[ this document ]] 2829 11.4. The OAuth Extensions Error Registry 2831 This specification establishes the OAuth extensions error registry. 2833 Additional error codes used together with other protocol extensions 2834 (i.e. extension grant types, access token types, or extension 2835 parameters) are registered with a Specification Required ([RFC5226]) 2836 after a two week review period on the [TBD]@ietf.org mailing list, on 2837 the advice of one or more Designated Experts. However, to allow for 2838 the allocation of values prior to publication, the Designated 2839 Expert(s) may approve registration once they are satisfied that such 2840 a specification will be published. 2842 Registration requests must be sent to the [TBD]@ietf.org mailing list 2843 for review and comment, with an appropriate subject (e.g., "Request 2844 for error code: example"). [[ Note to RFC-EDITOR: The name of the 2845 mailing list should be determined in consultation with the IESG and 2846 IANA. Suggested name: oauth-ext-review. ]] 2848 Within the review period, the Designated Expert(s) will either 2849 approve or deny the registration request, communicating this decision 2850 to the review list and IANA. Denials should include an explanation 2851 and, if applicable, suggestions as to how to make the request 2852 successful. 2854 IANA must only accept registry updates from the Designated Expert(s), 2855 and should direct all requests for registration to the review mailing 2856 list. 2858 11.4.1. Registration Template 2860 Error name: 2861 The name requested (e.g., "example"). 2862 Error usage location: 2863 The location(s) where the error can be used. The possible 2864 locations are: authorization code grant error response 2865 (Section 4.1.2.1), implicit grant error response 2866 (Section 4.2.2.1), token error response (Section 5.2), or resource 2867 access error response (Section 7.2). 2868 Related protocol extension: 2869 The name of the extension grant type, access token type, or 2870 extension parameter, the error code is used in conjunction with. 2871 Change controller: 2872 For standards-track RFCs, state "IETF". For others, give the name 2873 of the responsible party. Other details (e.g., postal address, 2874 e-mail address, home page URI) may also be included. 2875 Specification document(s): 2876 Reference to the document that specifies the error code, 2877 preferably including a URI that can be used to retrieve a copy of 2878 the document. An indication of the relevant sections may also be 2879 included, but is not required. 2881 12. References 2883 12.1. Normative References 2885 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2886 Requirement Levels", BCP 14, RFC 2119, March 1997. 2888 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2889 RFC 2246, January 1999. 2891 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2892 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2893 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2895 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2896 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2897 Authentication: Basic and Digest Access Authentication", 2898 RFC 2617, June 1999. 2900 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2902 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2903 Resource Identifier (URI): Generic Syntax", STD 66, 2904 RFC 3986, January 2005. 2906 [RFC4627] Crockford, D., "The application/json Media Type for 2907 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2909 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2910 RFC 4949, August 2007. 2912 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2913 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2914 May 2008. 2916 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2917 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2919 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2920 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2922 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2923 Verification of Domain-Based Application Service Identity 2924 within Internet Public Key Infrastructure Using X.509 2925 (PKIX) Certificates in the Context of Transport Layer 2926 Security (TLS)", RFC 6125, March 2011. 2928 [USASCII] American National Standards Institute, "Coded Character 2929 Set -- 7-bit American Standard Code for Information 2930 Interchange", ANSI X3.4, 1986. 2932 [W3C.REC-html401-19991224] 2933 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 2934 Specification", World Wide Web Consortium 2935 Recommendation REC-html401-19991224, December 1999, 2936 . 2938 12.2. Informative References 2940 [I-D.draft-hardt-oauth-01] 2941 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2942 Web Resource Authorization Profiles", January 2010. 2944 [I-D.ietf-httpbis-p7-auth] 2945 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 2946 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 2947 progress), March 2012. 2949 [I-D.ietf-oauth-saml2-bearer] 2950 Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for 2951 OAuth 2.0", draft-ietf-oauth-saml2-bearer-12 (work in 2952 progress), May 2012. 2954 [I-D.ietf-oauth-v2-bearer] 2955 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2956 Authorization Protocol: Bearer Tokens", 2957 draft-ietf-oauth-v2-bearer-19 (work in progress), 2958 April 2012. 2960 [I-D.ietf-oauth-v2-http-mac] 2961 Hammer-Lahav, E., "HTTP Authentication: MAC Access 2962 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 2963 progress), February 2012. 2965 [I-D.ietf-oauth-v2-threatmodel] 2966 McGloin, M., Hunt, P., and T. Lodderstedt, "OAuth 2.0 2967 Threat Model and Security Considerations", 2968 draft-ietf-oauth-v2-threatmodel-02 (work in progress), 2969 February 2012. 2971 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2972 April 2010. 2974 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 2976 This section provides Augmented Backus-Naur Form (ABNF) syntax 2977 descriptions for the elements defined in this specification using the 2978 notation of [RFC5234]. Elements are presented in the order first 2979 defined. 2981 Some of the definitions that follow use the "URI-reference" 2982 definition from [RFC3986]. 2984 Some of the definitions that follow use these common definitions: 2986 VSCHAR = %20-7E 2987 NQCHAR = %x21 / %x23-5B / %x5D-7E 2988 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 2990 A.1. "client_id" Syntax 2992 The "client_id" element is defined in Section 2.3.1: 2994 client-id = *VSCHAR 2996 (This matches the "userid" definition in the HTTP Basic 2997 Authentication Scheme [RFC2617].) 2999 A.2. "client_secret" Syntax 3001 The "client_secret" element is defined in Section 2.3.1: 3003 client-secret = *VSCHAR 3005 (This matches the "password" definition in the HTTP Basic 3006 Authentication Scheme [RFC2617].) 3008 A.3. "response_type" Syntax 3010 The "response_type" element is defined in Section 3.1.1 and 3011 Section 8.4: 3013 response-type = response-name *( SP response-name ) 3014 response-name = 1*response-char 3015 response-char = "_" / DIGIT / ALPHA 3017 A.4. "scope" Syntax 3019 The "scope" element is defined in Section 3.3: 3021 scope = scope-token *( SP scope-token ) 3022 scope-token = 1*NQCHAR 3024 A.5. "state" Syntax 3026 The "state" element is defined in Section 4.1.1, Section 4.1.2, 3027 Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1: 3029 state = 1*VSCHAR 3031 A.6. "redirect_uri" Syntax 3033 The "redirect_uri" element is defined in Section 4.1.1, 3034 Section 4.1.3, and Section 4.2.1: 3036 redirect-uri = URI-reference 3038 A.7. "error" Syntax 3040 The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1, 3041 Section 5.2, Section 7.2, and Section 8.5: 3043 error = 1*NQSCHAR 3045 A.8. "error_description" Syntax 3047 The "error_description" element is defined in Section 4.1.2.1, 3048 Section 4.2.2.1, Section 5.2, and Section 7.2: 3050 error-description = 1*NQSCHAR 3052 A.9. "error_uri" Syntax 3054 The "error_uri" element is defined in Section 4.1.2.1, 3055 Section 4.2.2.1, Section 5.2, and Section 7.2: 3057 error-uri = URI-reference 3059 A.10. "grant_type" Syntax 3061 The "grant_type" element is defined in Section 4.1.3, Section 4.3.2, 3062 Section 4.4.2, Section 6, and Section 4.5: 3064 grant-type = grant-name / URI-reference 3065 grant-name = 1*name-char 3066 name-char = "-" / "." / "_" / DIGIT / ALPHA 3068 A.11. "code" Syntax 3070 The "code" element is defined in Section 4.1.3: 3072 code = 1*VSCHAR 3074 A.12. "access_token" Syntax 3076 The "access_token" element is defined in Section 4.2.2 and 3077 Section 5.1: 3079 access-token = 1*VSCHAR 3081 A.13. "token_type" Syntax 3083 The "token_type" element is defined in Section 4.2.2, Section 5.1, 3084 and Section 8.1: 3086 token-type = type-name / URI-reference 3087 type-name = 1*name-char 3088 name-char = "-" / "." / "_" / DIGIT / ALPHA 3090 A.14. "expires_in" Syntax 3092 The "expires_in" element is defined in Section 4.2.2 and Section 5.1: 3094 expires-in = 1*DIGIT 3096 A.15. "username" Syntax 3098 The "username" element is defined in Section 4.3.2: 3100 username = *( %x20-39 / %x3B-7E ) 3102 (This allowed character set is VSCHAR excluding ":". This is 3103 compatible with the "userid" definition in the HTTP Basic 3104 Authentication Scheme [RFC2617].) 3106 A.16. "password" Syntax 3108 The "password" element is defined in Section 4.3.2: 3110 password = *VSCHAR 3112 (This matches the "password" definition in the HTTP Basic 3113 Authentication Scheme [RFC2617].) 3115 A.17. "refresh_token" Syntax 3117 The "refresh_token" element is defined in Section 5.1 and Section 6: 3119 refresh-token = 1*VSCHAR 3121 A.18. Endpoint Parameter Syntax 3123 The syntax for new endpoint parameters is defined in Section 8.2: 3125 param-name = 1*name-char 3126 name-char = "-" / "." / "_" / DIGIT / ALPHA 3128 Appendix B. Acknowledgements 3130 The initial OAuth 2.0 protocol specification was edited by David 3131 Recordon, based on two previous publications: the OAuth 1.0 community 3132 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 3133 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 3134 Considerations section was drafted by Torsten Lodderstedt, Mark 3135 McGloin, Phil Hunt, and Anthony Nadalin. The ABNF section was 3136 drafted by Michael B. Jones. 3138 The OAuth 1.0 community specification was edited by Eran Hammer and 3139 authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 3140 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 3141 Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 3142 Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 3143 Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 3145 The OAuth WRAP specification was edited by Dick Hardt and authored by 3146 Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. 3148 This specification is the work of the OAuth Working Group which 3149 includes dozens of active and dedicated participants. In particular, 3150 the following individuals contributed ideas, feedback, and wording 3151 which shaped and formed the final specification: 3153 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 3154 Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres, 3155 Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill 3156 de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin, 3157 Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan 3158 Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Justin 3159 Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. Jones, Terry 3160 Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, Rasmus 3161 Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul Madsen, 3162 Alastair Mair, Eve Maler, James Manger, Mark McGloin, Laurence Miao, 3163 William Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 3164 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 3165 Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, Justin Smith, 3166 Haibin Song, Niv Steingarten, Christian Stubner, Jeremy Suriel, Paul 3167 Tarjan, Christopher Thomas, Henry S. Thompson, Allen Tom, Franklin 3168 Tse, Nick Walker, Shane Weeden, and Skylar Woodward. 3170 This document was produced under the chairmanship of Blaine Cook, 3171 Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. 3172 The area directors included Lisa Dusseault, Peter Saint-Andre, and 3173 Stephen Farrell. 3175 Appendix C. Editor's Notes 3177 While many people contributed to this specification throughout its 3178 long journey, the editor would like to acknowledge and thank a few 3179 individuals for their outstanding and invaluable efforts leading up 3180 to the publication of this specification. 3182 David Recordon for continuously being one of OAuth's most valuable 3183 assets, bringing pragmatism and urgency to the work, and helping 3184 shape it from its very beginning, as well as being one of the best 3185 collaborators I had the pleasure of working with. 3187 James Manger for his creative ideas and always insightful feedback. 3188 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 3189 Marius Scurtescu, and Luke Shepard for their continued participation 3190 and valuable feedback. 3192 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 3193 support of this work for over three years. 3195 Authors' Addresses 3197 Eran Hammer (editor) 3199 Email: eran@hueniverse.com 3200 URI: http://hueniverse.com 3202 David Recordon 3203 Facebook 3205 Email: dr@fb.com 3206 URI: http://www.davidrecordon.com/ 3207 Dick Hardt 3208 Microsoft 3210 Email: dick.hardt@gmail.com 3211 URI: http://dickhardt.org/