idnits 2.17.1 draft-ietf-oauth-v2-28.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 19, 2012) is 4301 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 2592, but not defined == Unused Reference: 'I-D.ietf-httpbis-p7-auth' is defined on line 2941, 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-20 == 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-05 -- 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 21, 2012 D. Hardt 7 Microsoft 8 June 19, 2012 10 The OAuth 2.0 Authorization Framework 11 draft-ietf-oauth-v2-28 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 21, 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 . . . . . . . . . . . . . . . . . . . 49 118 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 50 119 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 50 120 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 51 121 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 51 122 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 52 123 10.6. Authorization Code Redirection URI Manipulation . . . . . 53 124 10.7. Resource Owner Password Credentials . . . . . . . . . . . 53 125 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 54 126 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 54 127 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 54 128 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 54 129 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 55 130 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 56 131 10.14. Code Injection and Input Validation . . . . . . . . . . . 56 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 . . . . . . . . . . . . . . . . 61 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 . . . . . . . . . . . . . . . . . 64 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 . . . . . . . . . . . . . . . . . . 66 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 . . . . . . . . . . . . . . . . . . 67 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 . . . . . . . . . . . . . . . . 68 167 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 68 168 Appendix C. Editor's Notes . . . . . . . . . . . . . . . . . . . 69 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 encoded using the 682 "application/x-www-form-urlencoded" content-type encoding method 683 defined by HTML 4.01 [W3C.REC-html401-19991224] and the encoded value 684 is used as the username; the client password is used as the password. 685 The authorization server MUST support the HTTP Basic authentication 686 scheme for authenticating clients that were issued a client password. 688 For example (extra line breaks are for display purposes only): 690 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 692 Alternatively, the authorization server MAY support including the 693 client credentials in the request body using the following 694 parameters: 696 client_id 697 REQUIRED. The client identifier issued to the client during 698 the registration process described by Section 2.2. 699 client_secret 700 REQUIRED. The client secret. The client MAY omit the 701 parameter if the client secret is an empty string. 703 Including the client credentials in the request body using the two 704 parameters is NOT RECOMMENDED, and SHOULD be limited to clients 705 unable to directly utilize the HTTP Basic authentication scheme (or 706 other password-based HTTP authentication schemes). The parameters 707 can only be transmitted in the request body and MUST NOT be included 708 in the request URI. 710 For example, requesting to refresh an access token (Section 6) using 711 the body parameters (extra line breaks are for display purposes 712 only): 714 POST /token HTTP/1.1 715 Host: server.example.com 716 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 718 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 719 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 721 The authorization server MUST require the use of TLS as described in 722 Section 1.6 when sending requests using password authentication. 724 Since this client authentication method involves a password, the 725 authorization server MUST protect any endpoint utilizing it against 726 brute force attacks. 728 2.3.2. Other Authentication Methods 730 The authorization server MAY support any suitable HTTP authentication 731 scheme matching its security requirements. When using other 732 authentication methods, the authorization server MUST define a 733 mapping between the client identifier (registration record) and 734 authentication scheme. 736 2.4. Unregistered Clients 738 This specification does not exclude the use of unregistered clients. 739 However, the use with such clients is beyond the scope of this 740 specification, and requires additional security analysis and review 741 of its interoperability impact. 743 3. Protocol Endpoints 745 The authorization process utilizes two authorization server endpoints 746 (HTTP resources): 748 o Authorization endpoint - used by the client to obtain 749 authorization from the resource owner via user-agent redirection. 750 o Token endpoint - used by the client to exchange an authorization 751 grant for an access token, typically with client authentication. 753 As well as one client endpoint: 755 o Redirection endpoint - used by the authorization server to return 756 authorization credentials responses to the client via the resource 757 owner user-agent. 759 Not every authorization grant type utilizes both endpoints. 760 Extension grant types MAY define additional endpoints as needed. 762 3.1. Authorization Endpoint 764 The authorization endpoint is used to interact with the resource 765 owner and obtain an authorization grant. The authorization server 766 MUST first verify the identity of the resource owner. The way in 767 which the authorization server authenticates the resource owner (e.g. 769 username and password login, session cookies) is beyond the scope of 770 this specification. 772 The means through which the client obtains the location of the 773 authorization endpoint are beyond the scope of this specification, 774 but the location is typically provided in the service documentation. 776 The endpoint URI MAY include an "application/x-www-form-urlencoded" 777 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 778 section 3.4), which MUST be retained when adding additional query 779 parameters. The endpoint URI MUST NOT include a fragment component. 781 Since requests to the authorization endpoint result in user 782 authentication and the transmission of clear-text credentials (in the 783 HTTP response), the authorization server MUST require the use of TLS 784 as described in Section 1.6 when sending requests to the 785 authorization endpoint. 787 The authorization server MUST support the use of the HTTP "GET" 788 method [RFC2616] for the authorization endpoint, and MAY support the 789 use of the "POST" method as well. 791 Parameters sent without a value MUST be treated as if they were 792 omitted from the request. The authorization server MUST ignore 793 unrecognized request parameters. Request and response parameters 794 MUST NOT be included more than once. 796 3.1.1. Response Type 798 The authorization endpoint is used by the authorization code grant 799 type and implicit grant type flows. The client informs the 800 authorization server of the desired grant type using the following 801 parameter: 803 response_type 804 REQUIRED. The value MUST be one of "code" for requesting an 805 authorization code as described by Section 4.1.1, "token" for 806 requesting an access token (implicit grant) as described by 807 Section 4.2.1, or a registered extension value as described by 808 Section 8.4. 810 Extension response types MAY contain a space-delimited (%x20) list of 811 values, where the order of values does not matter (e.g. response type 812 "a b" is the same as "b a"). The meaning of such composite response 813 types is defined by their respective specifications. 815 If an authorization request is missing the "response_type" parameter, 816 or if the response type is not understood, the authorization server 817 MUST return an error response as described in Section 4.1.2.1. 819 3.1.2. Redirection Endpoint 821 After completing its interaction with the resource owner, the 822 authorization server directs the resource owner's user-agent back to 823 the client. The authorization server redirects the user-agent to the 824 client's redirection endpoint previously established with the 825 authorization server during the client registration process or when 826 making the authorization request. 828 The redirection endpoint URI MUST be an absolute URI as defined by 829 [RFC3986] section 4.3. The endpoint URI MAY include an 830 "application/x-www-form-urlencoded" formatted 831 ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), 832 which MUST be retained when adding additional query parameters. The 833 endpoint URI MUST NOT include a fragment component. 835 3.1.2.1. Endpoint Request Confidentiality 837 The redirection endpoint SHOULD require the use of TLS as described 838 in Section 1.6 when the requested response type is "code" or "token", 839 or when the redirection request will result in the transmission of 840 sensitive credentials over an open network. This specification does 841 not mandate the use of TLS because at the time of this writing, 842 requiring clients to deploy TLS is a significant hurdle for many 843 client developers. If TLS is not available, the authorization server 844 SHOULD warn the resource owner about the insecure endpoint prior to 845 redirection (e.g. display a message during the authorization 846 request). 848 Lack of transport-layer security can have a severe impact on the 849 security of the client and the protected resources it is authorized 850 to access. The use of transport-layer security is particularly 851 critical when the authorization process is used as a form of 852 delegated end-user authentication by the client (e.g. third-party 853 sign-in service). 855 3.1.2.2. Registration Requirements 857 The authorization server MUST require the following clients to 858 register their redirection endpoint: 860 o Public clients. 861 o Confidential clients utilizing the implicit grant type. 863 The authorization server SHOULD require all clients to register their 864 redirection endpoint prior to utilizing the authorization endpoint. 866 The authorization server SHOULD require the client to provide the 867 complete redirection URI (the client MAY use the "state" request 868 parameter to achieve per-request customization). If requiring the 869 registration of the complete redirection URI is not possible, the 870 authorization server SHOULD require the registration of the URI 871 scheme, authority, and path (allowing the client to dynamically vary 872 only the query component of the redirection URI when requesting 873 authorization). 875 The authorization server MAY allow the client to register multiple 876 redirection endpoints. 878 Lack of a redirection URI registration requirement can enable an 879 attacker to use the authorization endpoint as open redirector as 880 described in Section 10.15. 882 3.1.2.3. Dynamic Configuration 884 If multiple redirection URIs have been registered, if only part of 885 the redirection URI has been registered, or if no redirection URI has 886 been registered, the client MUST include a redirection URI with the 887 authorization request using the "redirect_uri" request parameter. 889 When a redirection URI is included in an authorization request, the 890 authorization server MUST compare and match the value received 891 against at least one of the registered redirection URIs (or URI 892 components) as defined in [RFC3986] section 6, if any redirection 893 URIs were registered. If the client registration included the full 894 redirection URI, the authorization server MUST compare the two URIs 895 using simple string comparison as defined in [RFC3986] section 6.2.1. 897 3.1.2.4. Invalid Endpoint 899 If an authorization request fails validation due to a missing, 900 invalid, or mismatching redirection URI, the authorization server 901 SHOULD inform the resource owner of the error, and MUST NOT 902 automatically redirect the user-agent to the invalid redirection URI. 904 3.1.2.5. Endpoint Content 906 The redirection request to the client's endpoint typically results in 907 an HTML document response, processed by the user-agent. If the HTML 908 response is served directly as the result of the redirection request, 909 any script included in the HTML document will execute with full 910 access to the redirection URI and the credentials it contains. 912 The client SHOULD NOT include any third-party scripts (e.g. third- 913 party analytics, social plug-ins, ad networks) in the redirection 914 endpoint response. Instead, it SHOULD extract the credentials from 915 the URI and redirect the user-agent again to another endpoint without 916 exposing the credentials (in the URI or elsewhere). If third-party 917 scripts are included, the client MUST ensure that its own scripts 918 (used to extract and remove the credentials from the URI) will 919 execute first. 921 3.2. Token Endpoint 923 The token endpoint is used by the client to obtain an access token by 924 presenting its authorization grant or refresh token. The token 925 endpoint is used with every authorization grant except for the 926 implicit grant type (since an access token is issued directly). 928 The means through which the client obtains the location of the token 929 endpoint are beyond the scope of this specification but is typically 930 provided in the service documentation. 932 The endpoint URI MAY include an "application/x-www-form-urlencoded" 933 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 934 section 3.4), which MUST be retained when adding additional query 935 parameters. The endpoint URI MUST NOT include a fragment component. 937 Since requests to the token endpoint result in the transmission of 938 clear-text credentials (in the HTTP request and response), the 939 authorization server MUST require the use of TLS as described in 940 Section 1.6 when sending requests to the token endpoint. 942 The client MUST use the HTTP "POST" method when making access token 943 requests. 945 Parameters sent without a value MUST be treated as if they were 946 omitted from the request. The authorization server MUST ignore 947 unrecognized request parameters. Request and response parameters 948 MUST NOT be included more than once. 950 3.2.1. Client Authentication 952 Confidential clients or other clients issued client credentials MUST 953 authenticate with the authorization server as described in 954 Section 2.3 when making requests to the token endpoint. Client 955 authentication is used for: 957 o Enforcing the binding of refresh tokens and authorization codes to 958 the client they were issued to. Client authentication is critical 959 when an authorization code is transmitted to the redirection 960 endpoint over an insecure channel, or when the redirection URI has 961 not been registered in full. 963 o Recovering from a compromised client by disabling the client or 964 changing its credentials, thus preventing an attacker from abusing 965 stolen refresh tokens. Changing a single set of client 966 credentials is significantly faster than revoking an entire set of 967 refresh tokens. 968 o Implementing authentication management best practices which 969 require periodic credential rotation. Rotation of an entire set 970 of refresh tokens can be challenging, while rotation of a single 971 set of client credentials is significantly easier. 973 A public client that was not issued a client password MAY use the 974 "client_id" request parameter to identify itself when sending 975 requests to the token endpoint (e.g. for the purpose of providing 976 end-user context, client usage statistics). 978 3.3. Access Token Scope 980 The authorization and token endpoints allow the client to specify the 981 scope of the access request using the "scope" request parameter. In 982 turn, the authorization server uses the "scope" response parameter to 983 inform the client of the scope of the access token issued. 985 The value of the scope parameter is expressed as a list of space- 986 delimited, case sensitive strings. The strings are defined by the 987 authorization server. If the value contains multiple space-delimited 988 strings, their order does not matter, and each string adds an 989 additional access range to the requested scope. 991 scope = scope-token *( SP scope-token ) 992 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 994 The authorization server MAY fully or partially ignore the scope 995 requested by the client based on the authorization server policy or 996 the resource owner's instructions. If the issued access token scope 997 is different from the one requested by the client, the authorization 998 server MUST include the "scope" response parameter to inform the 999 client of the actual scope granted. 1001 If the client omits the scope parameter when requesting 1002 authorization, the authorization server MUST either process the 1003 request using a pre-defined default value, or fail the request 1004 indicating an invalid scope. The authorization server SHOULD 1005 document its scope requirements and default value (if defined). 1007 4. Obtaining Authorization 1009 To request an access token, the client obtains authorization from the 1010 resource owner. The authorization is expressed in the form of an 1011 authorization grant which the client uses to request the access 1012 token. OAuth defines four grant types: authorization code, implicit, 1013 resource owner password credentials, and client credentials. It also 1014 provides an extension mechanism for defining additional grant types. 1016 4.1. Authorization Code Grant 1018 The authorization code grant type is used to obtain both access 1019 tokens and refresh tokens and is optimized for confidential clients. 1020 As a redirection-based flow, the client must be capable of 1021 interacting with the resource owner's user-agent (typically a web 1022 browser) and capable of receiving incoming requests (via redirection) 1023 from the authorization server. 1025 +----------+ 1026 | resource | 1027 | owner | 1028 | | 1029 +----------+ 1030 ^ 1031 | 1032 (B) 1033 +----|-----+ Client Identifier +---------------+ 1034 | -+----(A)-- & Redirection URI ---->| | 1035 | User- | | Authorization | 1036 | Agent -+----(B)-- User authenticates --->| Server | 1037 | | | | 1038 | -+----(C)-- Authorization Code ---<| | 1039 +-|----|---+ +---------------+ 1040 | | ^ v 1041 (A) (C) | | 1042 | | | | 1043 ^ v | | 1044 +---------+ | | 1045 | |>---(D)-- Authorization Code ---------' | 1046 | Client | & Redirection URI | 1047 | | | 1048 | |<---(E)----- Access Token -------------------' 1049 +---------+ (w/ Optional Refresh Token) 1051 Note: The lines illustrating steps A, B, and C are broken into two 1052 parts as they pass through the user-agent. 1054 Figure 3: Authorization Code Flow 1056 The flow illustrated in Figure 3 includes the following steps: 1058 (A) The client initiates the flow by directing the resource owner's 1059 user-agent to the authorization endpoint. The client includes 1060 its client identifier, requested scope, local state, and a 1061 redirection URI to which the authorization server will send the 1062 user-agent back once access is granted (or denied). 1063 (B) The authorization server authenticates the resource owner (via 1064 the user-agent) and establishes whether the resource owner 1065 grants or denies the client's access request. 1066 (C) Assuming the resource owner grants access, the authorization 1067 server redirects the user-agent back to the client using the 1068 redirection URI provided earlier (in the request or during 1069 client registration). The redirection URI includes an 1070 authorization code and any local state provided by the client 1071 earlier. 1072 (D) The client requests an access token from the authorization 1073 server's token endpoint by including the authorization code 1074 received in the previous step. When making the request, the 1075 client authenticates with the authorization server. The client 1076 includes the redirection URI used to obtain the authorization 1077 code for verification. 1078 (E) The authorization server authenticates the client, validates the 1079 authorization code, and ensures the redirection URI received 1080 matches the URI used to redirect the client in step (C). If 1081 valid, the authorization server responds back with an access 1082 token and optionally, a refresh token. 1084 4.1.1. Authorization Request 1086 The client constructs the request URI by adding the following 1087 parameters to the query component of the authorization endpoint URI 1088 using the "application/x-www-form-urlencoded" format as defined by 1089 [W3C.REC-html401-19991224]: 1091 response_type 1092 REQUIRED. Value MUST be set to "code". 1093 client_id 1094 REQUIRED. The client identifier as described in Section 2.2. 1095 redirect_uri 1096 OPTIONAL. As described in Section 3.1.2. 1097 scope 1098 OPTIONAL. The scope of the access request as described by 1099 Section 3.3. 1101 state 1102 RECOMMENDED. An opaque value used by the client to maintain 1103 state between the request and callback. The authorization 1104 server includes this value when redirecting the user-agent back 1105 to the client. The parameter SHOULD be used for preventing 1106 cross-site request forgery as described in Section 10.12. 1108 The client directs the resource owner to the constructed URI using an 1109 HTTP redirection response, or by other means available to it via the 1110 user-agent. 1112 For example, the client directs the user-agent to make the following 1113 HTTP request using TLS (extra line breaks are for display purposes 1114 only): 1116 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1117 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1118 Host: server.example.com 1120 The authorization server validates the request to ensure all required 1121 parameters are present and valid. If the request is valid, the 1122 authorization server authenticates the resource owner and obtains an 1123 authorization decision (by asking the resource owner or by 1124 establishing approval via other means). 1126 When a decision is established, the authorization server directs the 1127 user-agent to the provided client redirection URI using an HTTP 1128 redirection response, or by other means available to it via the user- 1129 agent. 1131 4.1.2. Authorization Response 1133 If the resource owner grants the access request, the authorization 1134 server issues an authorization code and delivers it to the client by 1135 adding the following parameters to the query component of the 1136 redirection URI using the "application/x-www-form-urlencoded" format: 1138 code 1139 REQUIRED. The authorization code generated by the 1140 authorization server. The authorization code MUST expire 1141 shortly after it is issued to mitigate the risk of leaks. A 1142 maximum authorization code lifetime of 10 minutes is 1143 RECOMMENDED. The client MUST NOT use the authorization code 1144 more than once. If an authorization code is used more than 1145 once, the authorization server MUST deny the request and SHOULD 1146 revoke (when possible) all tokens previously issued based on 1147 that authorization code. The authorization code is bound to 1148 the client identifier and redirection URI. 1149 state 1150 REQUIRED if the "state" parameter was present in the client 1151 authorization request. The exact value received from the 1152 client. 1154 For example, the authorization server redirects the user-agent by 1155 sending the following HTTP response: 1157 HTTP/1.1 302 Found 1158 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1159 &state=xyz 1161 The client MUST ignore unrecognized response parameters. The 1162 authorization code string size is left undefined by this 1163 specification. The client should avoid making assumptions about code 1164 value sizes. The authorization server SHOULD document the size of 1165 any value it issues. 1167 4.1.2.1. Error Response 1169 If the request fails due to a missing, invalid, or mismatching 1170 redirection URI, or if the client identifier is missing or invalid, 1171 the authorization server SHOULD inform the resource owner of the 1172 error, and MUST NOT automatically redirect the user-agent to the 1173 invalid redirection URI. 1175 If the resource owner denies the access request or if the request 1176 fails for reasons other than a missing or invalid redirection URI, 1177 the authorization server informs the client by adding the following 1178 parameters to the query component of the redirection URI using the 1179 "application/x-www-form-urlencoded" format: 1181 error 1182 REQUIRED. A single ASCII [USASCII] error code from the 1183 following: 1184 invalid_request 1185 The request is missing a required parameter, includes an 1186 invalid parameter value, includes a parameter more than 1187 once, or is otherwise malformed. 1188 unauthorized_client 1189 The client is not authorized to request an authorization 1190 code using this method. 1192 access_denied 1193 The resource owner or authorization server denied the 1194 request. 1195 unsupported_response_type 1196 The authorization server does not support obtaining an 1197 authorization code using this method. 1198 invalid_scope 1199 The requested scope is invalid, unknown, or malformed. 1200 server_error 1201 The authorization server encountered an unexpected 1202 condition which prevented it from fulfilling the request. 1203 temporarily_unavailable 1204 The authorization server is currently unable to handle 1205 the request due to a temporary overloading or maintenance 1206 of the server. 1207 Values for the "error" parameter MUST NOT include characters 1208 outside the set %x20-21 / %x23-5B / %x5D-7E. 1209 error_description 1210 OPTIONAL. A human-readable ASCII [USASCII] text providing 1211 additional information, used to assist the client developer in 1212 understanding the error that occurred. 1213 Values for the "error_description" parameter MUST NOT include 1214 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1215 error_uri 1216 OPTIONAL. A URI identifying a human-readable web page with 1217 information about the error, used to provide the client 1218 developer with additional information about the error. 1219 Values for the "error_uri" parameter MUST conform to the URI- 1220 Reference syntax, and thus MUST NOT include characters outside 1221 the set %x21 / %x23-5B / %x5D-7E. 1222 state 1223 REQUIRED if a "state" parameter was present in the client 1224 authorization request. The exact value received from the 1225 client. 1227 For example, the authorization server redirects the user-agent by 1228 sending the following HTTP response: 1230 HTTP/1.1 302 Found 1231 Location: https://client.example.com/cb?error=access_denied&state=xyz 1233 4.1.3. Access Token Request 1235 The client makes a request to the token endpoint by adding the 1236 following parameters using the "application/x-www-form-urlencoded" 1237 format in the HTTP request entity-body: 1239 grant_type 1240 REQUIRED. Value MUST be set to "authorization_code". 1241 code 1242 REQUIRED. The authorization code received from the 1243 authorization server. 1244 redirect_uri 1245 REQUIRED, if the "redirect_uri" parameter was included in the 1246 authorization request as described in Section 4.1.1, and their 1247 values MUST be identical. 1249 If the client type is confidential or the client was issued client 1250 credentials (or assigned other authentication requirements), the 1251 client MUST authenticate with the authorization server as described 1252 in Section 3.2.1. 1254 For example, the client makes the following HTTP request using TLS 1255 (extra line breaks are for display purposes only): 1257 POST /token HTTP/1.1 1258 Host: server.example.com 1259 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1260 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1262 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1263 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1265 The authorization server MUST: 1267 o require client authentication for confidential clients or for any 1268 client that was issued client credentials (or with other 1269 authentication requirements), 1270 o authenticate the client if client authentication is included and 1271 ensure the authorization code was issued to the authenticated 1272 client, 1273 o verify that the authorization code is valid, and 1274 o ensure that the "redirect_uri" parameter is present if the 1275 "redirect_uri" parameter was included in the initial authorization 1276 request as described in Section 4.1.1, and if included ensure 1277 their values are identical. 1279 4.1.4. Access Token Response 1281 If the access token request is valid and authorized, the 1282 authorization server issues an access token and optional refresh 1283 token as described in Section 5.1. If the request client 1284 authentication failed or is invalid, the authorization server returns 1285 an error response as described in Section 5.2. 1287 An example successful response: 1289 HTTP/1.1 200 OK 1290 Content-Type: application/json;charset=UTF-8 1291 Cache-Control: no-store 1292 Pragma: no-cache 1294 { 1295 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1296 "token_type":"example", 1297 "expires_in":3600, 1298 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1299 "example_parameter":"example_value" 1300 } 1302 4.2. Implicit Grant 1304 The implicit grant type is used to obtain access tokens (it does not 1305 support the issuance of refresh tokens) and is optimized for public 1306 clients known to operate a particular redirection URI. These clients 1307 are typically implemented in a browser using a scripting language 1308 such as JavaScript. 1310 As a redirection-based flow, the client must be capable of 1311 interacting with the resource owner's user-agent (typically a web 1312 browser) and capable of receiving incoming requests (via redirection) 1313 from the authorization server. 1315 Unlike the authorization code grant type in which the client makes 1316 separate requests for authorization and access token, the client 1317 receives the access token as the result of the authorization request. 1319 The implicit grant type does not include client authentication, and 1320 relies on the presence of the resource owner and the registration of 1321 the redirection URI. Because the access token is encoded into the 1322 redirection URI, it may be exposed to the resource owner and other 1323 applications residing on the same device. 1325 +----------+ 1326 | Resource | 1327 | Owner | 1328 | | 1329 +----------+ 1330 ^ 1331 | 1332 (B) 1333 +----|-----+ Client Identifier +---------------+ 1334 | -+----(A)-- & Redirection URI --->| | 1335 | User- | | Authorization | 1336 | Agent -|----(B)-- User authenticates -->| Server | 1337 | | | | 1338 | |<---(C)--- Redirection URI ----<| | 1339 | | with Access Token +---------------+ 1340 | | in Fragment 1341 | | +---------------+ 1342 | |----(D)--- Redirection URI ---->| Web-Hosted | 1343 | | without Fragment | Client | 1344 | | | Resource | 1345 | (F) |<---(E)------- Script ---------<| | 1346 | | +---------------+ 1347 +-|--------+ 1348 | | 1349 (A) (G) Access Token 1350 | | 1351 ^ v 1352 +---------+ 1353 | | 1354 | Client | 1355 | | 1356 +---------+ 1358 Note: The lines illustrating steps A and B are broken into two parts 1359 as they pass through the user-agent. 1361 Figure 4: Implicit Grant Flow 1363 The flow illustrated in Figure 4 includes the following steps: 1365 (A) The client initiates the flow by directing the resource owner's 1366 user-agent to the authorization endpoint. The client includes 1367 its client identifier, requested scope, local state, and a 1368 redirection URI to which the authorization server will send the 1369 user-agent back once access is granted (or denied). 1371 (B) The authorization server authenticates the resource owner (via 1372 the user-agent) and establishes whether the resource owner 1373 grants or denies the client's access request. 1374 (C) Assuming the resource owner grants access, the authorization 1375 server redirects the user-agent back to the client using the 1376 redirection URI provided earlier. The redirection URI includes 1377 the access token in the URI fragment. 1378 (D) The user-agent follows the redirection instructions by making a 1379 request to the web-hosted client resource (which does not 1380 include the fragment per [RFC2616]). The user-agent retains the 1381 fragment information locally. 1382 (E) The web-hosted client resource returns a web page (typically an 1383 HTML document with an embedded script) capable of accessing the 1384 full redirection URI including the fragment retained by the 1385 user-agent, and extracting the access token (and other 1386 parameters) contained in the fragment. 1387 (F) The user-agent executes the script provided by the web-hosted 1388 client resource locally, which extracts the access token and 1389 passes it to the client. 1391 4.2.1. Authorization Request 1393 The client constructs the request URI by adding the following 1394 parameters to the query component of the authorization endpoint URI 1395 using the "application/x-www-form-urlencoded" format: 1397 response_type 1398 REQUIRED. Value MUST be set to "token". 1399 client_id 1400 REQUIRED. The client identifier as described in Section 2.2. 1401 redirect_uri 1402 OPTIONAL. As described in Section 3.1.2. 1403 scope 1404 OPTIONAL. The scope of the access request as described by 1405 Section 3.3. 1406 state 1407 RECOMMENDED. An opaque value used by the client to maintain 1408 state between the request and callback. The authorization 1409 server includes this value when redirecting the user-agent back 1410 to the client. The parameter SHOULD be used for preventing 1411 cross-site request forgery as described in Section 10.12. 1413 The client directs the resource owner to the constructed URI using an 1414 HTTP redirection response, or by other means available to it via the 1415 user-agent. 1417 For example, the client directs the user-agent to make the following 1418 HTTP request using TLS (extra line breaks are for display purposes 1419 only): 1421 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1422 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1423 Host: server.example.com 1425 The authorization server validates the request to ensure all required 1426 parameters are present and valid. The authorization server MUST 1427 verify that the redirection URI to which it will redirect the access 1428 token matches a redirection URI registered by the client as described 1429 in Section 3.1.2. 1431 If the request is valid, the authorization server authenticates the 1432 resource owner and obtains an authorization decision (by asking the 1433 resource owner or by establishing approval via other means). 1435 When a decision is established, the authorization server directs the 1436 user-agent to the provided client redirection URI using an HTTP 1437 redirection response, or by other means available to it via the user- 1438 agent. 1440 4.2.2. Access Token Response 1442 If the resource owner grants the access request, the authorization 1443 server issues an access token and delivers it to the client by adding 1444 the following parameters to the fragment component of the redirection 1445 URI using the "application/x-www-form-urlencoded" format: 1447 access_token 1448 REQUIRED. The access token issued by the authorization server. 1449 token_type 1450 REQUIRED. The type of the token issued as described in 1451 Section 7.1. Value is case insensitive. 1452 expires_in 1453 RECOMMENDED. The lifetime in seconds of the access token. For 1454 example, the value "3600" denotes that the access token will 1455 expire in one hour from the time the response was generated. 1456 If omitted, the authorization server SHOULD provide the 1457 expiration time via other means or document the default value. 1458 scope 1459 OPTIONAL, if identical to the scope requested by the client, 1460 otherwise REQUIRED. The scope of the access token as described 1461 by Section 3.3. 1463 state 1464 REQUIRED if the "state" parameter was present in the client 1465 authorization request. The exact value received from the 1466 client. 1468 The authorization server MUST NOT issue a refresh token. 1470 For example, the authorization server redirects the user-agent by 1471 sending the following HTTP response (URI extra line breaks are for 1472 display purposes only): 1474 HTTP/1.1 302 Found 1475 Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1476 &state=xyz&token_type=example&expires_in=3600 1478 Developers should note that some user-agents do not support the 1479 inclusion of a fragment component in the HTTP "Location" response 1480 header field. Such clients will require using other methods for 1481 redirecting the client than a 3xx redirection response. For example, 1482 returning an HTML page which includes a 'continue' button with an 1483 action linked to the redirection URI. 1485 The client MUST ignore unrecognized response parameters. The access 1486 token string size is left undefined by this specification. The 1487 client should avoid making assumptions about value sizes. The 1488 authorization server SHOULD document the size of any value it issues. 1490 4.2.2.1. Error Response 1492 If the request fails due to a missing, invalid, or mismatching 1493 redirection URI, or if the client identifier is missing or invalid, 1494 the authorization server SHOULD inform the resource owner of the 1495 error, and MUST NOT automatically redirect the user-agent to the 1496 invalid redirection URI. 1498 If the resource owner denies the access request or if the request 1499 fails for reasons other than a missing or invalid redirection URI, 1500 the authorization server informs the client by adding the following 1501 parameters to the fragment component of the redirection URI using the 1502 "application/x-www-form-urlencoded" format: 1504 error 1505 REQUIRED. A single ASCII [USASCII] error code from the 1506 following: 1508 invalid_request 1509 The request is missing a required parameter, includes an 1510 invalid parameter value, includes a parameter more than 1511 once, or is otherwise malformed. 1512 unauthorized_client 1513 The client is not authorized to request an access token 1514 using this method. 1515 access_denied 1516 The resource owner or authorization server denied the 1517 request. 1518 unsupported_response_type 1519 The authorization server does not support obtaining an 1520 access token using this method. 1521 invalid_scope 1522 The requested scope is invalid, unknown, or malformed. 1523 server_error 1524 The authorization server encountered an unexpected 1525 condition which prevented it from fulfilling the request. 1526 temporarily_unavailable 1527 The authorization server is currently unable to handle 1528 the request due to a temporary overloading or maintenance 1529 of the server. 1530 Values for the "error" parameter MUST NOT include characters 1531 outside the set %x20-21 / %x23-5B / %x5D-7E. 1532 error_description 1533 OPTIONAL. A human-readable ASCII [USASCII] text providing 1534 additional information, used to assist the client developer in 1535 understanding the error that occurred. 1536 Values for the "error_description" parameter MUST NOT include 1537 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1538 error_uri 1539 OPTIONAL. A URI identifying a human-readable web page with 1540 information about the error, used to provide the client 1541 developer with additional information about the error. 1542 Values for the "error_uri" parameter MUST conform to the URI- 1543 Reference syntax, and thus MUST NOT include characters outside 1544 the set %x21 / %x23-5B / %x5D-7E. 1545 state 1546 REQUIRED if a "state" parameter was present in the client 1547 authorization request. The exact value received from the 1548 client. 1550 For example, the authorization server redirects the user-agent by 1551 sending the following HTTP response: 1553 HTTP/1.1 302 Found 1554 Location: https://client.example.com/cb#error=access_denied&state=xyz 1556 4.3. Resource Owner Password Credentials Grant 1558 The resource owner password credentials grant type is suitable in 1559 cases where the resource owner has a trust relationship with the 1560 client, such as the device operating system or a highly privileged 1561 application. The authorization server should take special care when 1562 enabling this grant type, and only allow it when other flows are not 1563 viable. 1565 The grant type is suitable for clients capable of obtaining the 1566 resource owner's credentials (username and password, typically using 1567 an interactive form). It is also used to migrate existing clients 1568 using direct authentication schemes such as HTTP Basic or Digest 1569 authentication to OAuth by converting the stored credentials to an 1570 access token. 1572 +----------+ 1573 | Resource | 1574 | Owner | 1575 | | 1576 +----------+ 1577 v 1578 | Resource Owner 1579 (A) Password Credentials 1580 | 1581 v 1582 +---------+ +---------------+ 1583 | |>--(B)---- Resource Owner ------->| | 1584 | | Password Credentials | Authorization | 1585 | Client | | Server | 1586 | |<--(C)---- Access Token ---------<| | 1587 | | (w/ Optional Refresh Token) | | 1588 +---------+ +---------------+ 1590 Figure 5: Resource Owner Password Credentials Flow 1592 The flow illustrated in Figure 5 includes the following steps: 1594 (A) The resource owner provides the client with its username and 1595 password. 1596 (B) The client requests an access token from the authorization 1597 server's token endpoint by including the credentials received 1598 from the resource owner. When making the request, the client 1599 authenticates with the authorization server. 1601 (C) The authorization server authenticates the client and validates 1602 the resource owner credentials, and if valid issues an access 1603 token. 1605 4.3.1. Authorization Request and Response 1607 The method through which the client obtains the resource owner 1608 credentials is beyond the scope of this specification. The client 1609 MUST discard the credentials once an access token has been obtained. 1611 4.3.2. Access Token Request 1613 The client makes a request to the token endpoint by adding the 1614 following parameters using the "application/x-www-form-urlencoded" 1615 format in the HTTP request entity-body: 1617 grant_type 1618 REQUIRED. Value MUST be set to "password". 1619 username 1620 REQUIRED. The resource owner username. 1621 password 1622 REQUIRED. The resource owner password. 1623 scope 1624 OPTIONAL. The scope of the access request as described by 1625 Section 3.3. 1627 If the client type is confidential or the client was issued client 1628 credentials (or assigned other authentication requirements), the 1629 client MUST authenticate with the authorization server as described 1630 in Section 3.2.1. 1632 For example, the client makes the following HTTP request using 1633 transport-layer security (extra line breaks are for display purposes 1634 only): 1636 POST /token HTTP/1.1 1637 Host: server.example.com 1638 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1639 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1641 grant_type=password&username=johndoe&password=A3ddj3w 1643 The authorization server MUST: 1645 o require client authentication for confidential clients or for any 1646 client that was issued client credentials (or with other 1647 authentication requirements), 1648 o authenticate the client if client authentication is included, and 1649 o validate the resource owner password credentials using its 1650 existing password validation algorithm. 1652 Since this access token request utilizes the resource owner's 1653 password, the authorization server MUST protect the endpoint against 1654 brute force attacks (e.g. using rate-limitation or generating 1655 alerts). 1657 4.3.3. Access Token Response 1659 If the access token request is valid and authorized, the 1660 authorization server issues an access token and optional refresh 1661 token as described in Section 5.1. If the request failed client 1662 authentication or is invalid, the authorization server returns an 1663 error response as described in Section 5.2. 1665 An example successful response: 1667 HTTP/1.1 200 OK 1668 Content-Type: application/json;charset=UTF-8 1669 Cache-Control: no-store 1670 Pragma: no-cache 1672 { 1673 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1674 "token_type":"example", 1675 "expires_in":3600, 1676 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1677 "example_parameter":"example_value" 1678 } 1680 4.4. Client Credentials Grant 1682 The client can request an access token using only its client 1683 credentials (or other supported means of authentication) when the 1684 client is requesting access to the protected resources under its 1685 control, or those of another resource owner which has been previously 1686 arranged with the authorization server (the method of which is beyond 1687 the scope of this specification). 1689 The client credentials grant type MUST only be used by confidential 1690 clients. 1692 +---------+ +---------------+ 1693 | | | | 1694 | |>--(A)- Client Authentication --->| Authorization | 1695 | Client | | Server | 1696 | |<--(B)---- Access Token ---------<| | 1697 | | | | 1698 +---------+ +---------------+ 1700 Figure 6: Client Credentials Flow 1702 The flow illustrated in Figure 6 includes the following steps: 1704 (A) The client authenticates with the authorization server and 1705 requests an access token from the token endpoint. 1706 (B) The authorization server authenticates the client, and if valid 1707 issues an access token. 1709 4.4.1. Authorization Request and Response 1711 Since the client authentication is used as the authorization grant, 1712 no additional authorization request is needed. 1714 4.4.2. Access Token Request 1716 The client makes a request to the token endpoint by adding the 1717 following parameters using the "application/x-www-form-urlencoded" 1718 format in the HTTP request entity-body: 1720 grant_type 1721 REQUIRED. Value MUST be set to "client_credentials". 1722 scope 1723 OPTIONAL. The scope of the access request as described by 1724 Section 3.3. 1726 The client MUST authenticate with the authorization server as 1727 described in Section 3.2.1. 1729 For example, the client makes the following HTTP request using 1730 transport-layer security (extra line breaks are for display purposes 1731 only): 1733 POST /token HTTP/1.1 1734 Host: server.example.com 1735 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1736 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1737 grant_type=client_credentials 1739 The authorization server MUST authenticate the client. 1741 4.4.3. Access Token Response 1743 If the access token request is valid and authorized, the 1744 authorization server issues an access token as described in 1745 Section 5.1. A refresh token SHOULD NOT be included. If the request 1746 failed client authentication or is invalid, the authorization server 1747 returns an error response as described in Section 5.2. 1749 An example successful response: 1751 HTTP/1.1 200 OK 1752 Content-Type: application/json;charset=UTF-8 1753 Cache-Control: no-store 1754 Pragma: no-cache 1756 { 1757 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1758 "token_type":"example", 1759 "expires_in":3600, 1760 "example_parameter":"example_value" 1761 } 1763 4.5. Extension Grants 1765 The client uses an extension grant type by specifying the grant type 1766 using an absolute URI (defined by the authorization server) as the 1767 value of the "grant_type" parameter of the token endpoint, and by 1768 adding any additional parameters necessary. 1770 For example, to request an access token using a SAML 2.0 assertion 1771 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1772 makes the following HTTP request using TLS (line breaks are for 1773 display purposes only): 1775 POST /token HTTP/1.1 1776 Host: server.example.com 1777 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1779 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1780 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1782 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1784 If the access token request is valid and authorized, the 1785 authorization server issues an access token and optional refresh 1786 token as described in Section 5.1. If the request failed client 1787 authentication or is invalid, the authorization server returns an 1788 error response as described in Section 5.2. 1790 5. Issuing an Access Token 1792 If the access token request is valid and authorized, the 1793 authorization server issues an access token and optional refresh 1794 token as described in Section 5.1. If the request failed client 1795 authentication or is invalid, the authorization server returns an 1796 error response as described in Section 5.2. 1798 5.1. Successful Response 1800 The authorization server issues an access token and optional refresh 1801 token, and constructs the response by adding the following parameters 1802 to the entity body of the HTTP response with a 200 (OK) status code: 1804 access_token 1805 REQUIRED. The access token issued by the authorization server. 1806 token_type 1807 REQUIRED. The type of the token issued as described in 1808 Section 7.1. Value is case insensitive. 1809 expires_in 1810 RECOMMENDED. The lifetime in seconds of the access token. For 1811 example, the value "3600" denotes that the access token will 1812 expire in one hour from the time the response was generated. 1813 If omitted, the authorization server SHOULD provide the 1814 expiration time via other means or document the default value. 1815 refresh_token 1816 OPTIONAL. The refresh token which can be used to obtain new 1817 access tokens using the same authorization grant as described 1818 in Section 6. 1819 scope 1820 OPTIONAL, if identical to the scope requested by the client, 1821 otherwise REQUIRED. The scope of the access token as described 1822 by Section 3.3. 1824 The parameters are included in the entity body of the HTTP response 1825 using the "application/json" media type as defined by [RFC4627]. The 1826 parameters are serialized into a JSON structure by adding each 1827 parameter at the highest structure level. Parameter names and string 1828 values are included as JSON strings. Numerical values are included 1829 as JSON numbers. The order of parameters does not matter and can 1830 vary. 1832 The authorization server MUST include the HTTP "Cache-Control" 1833 response header field [RFC2616] with a value of "no-store" in any 1834 response containing tokens, credentials, or other sensitive 1835 information, as well as the "Pragma" response header field [RFC2616] 1836 with a value of "no-cache". 1838 For example: 1840 HTTP/1.1 200 OK 1841 Content-Type: application/json;charset=UTF-8 1842 Cache-Control: no-store 1843 Pragma: no-cache 1845 { 1846 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1847 "token_type":"example", 1848 "expires_in":3600, 1849 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1850 "example_parameter":"example_value" 1851 } 1853 The client MUST ignore unrecognized value names in the response. The 1854 sizes of tokens and other values received from the authorization 1855 server are left undefined. The client should avoid making 1856 assumptions about value sizes. The authorization server SHOULD 1857 document the size of any value it issues. 1859 5.2. Error Response 1861 The authorization server responds with an HTTP 400 (Bad Request) 1862 status code (unless specified otherwise) and includes the following 1863 parameters with the response: 1865 error 1866 REQUIRED. A single ASCII [USASCII] error code from the 1867 following: 1868 invalid_request 1869 The request is missing a required parameter, includes an 1870 unsupported parameter value (other than grant type), 1871 repeats a parameter, includes multiple credentials, 1872 utilizes more than one mechanism for authenticating the 1873 client, or is otherwise malformed. 1875 invalid_client 1876 Client authentication failed (e.g. unknown client, no 1877 client authentication included, or unsupported 1878 authentication method). The authorization server MAY 1879 return an HTTP 401 (Unauthorized) status code to indicate 1880 which HTTP authentication schemes are supported. If the 1881 client attempted to authenticate via the "Authorization" 1882 request header field, the authorization server MUST 1883 respond with an HTTP 401 (Unauthorized) status code, and 1884 include the "WWW-Authenticate" response header field 1885 matching the authentication scheme used by the client. 1886 invalid_grant 1887 The provided authorization grant (e.g. authorization 1888 code, resource owner credentials) or refresh token is 1889 invalid, expired, revoked, does not match the redirection 1890 URI used in the authorization request, or was issued to 1891 another client. 1892 unauthorized_client 1893 The authenticated client is not authorized to use this 1894 authorization grant type. 1895 unsupported_grant_type 1896 The authorization grant type is not supported by the 1897 authorization server. 1898 invalid_scope 1899 The requested scope is invalid, unknown, malformed, or 1900 exceeds the scope granted by the resource owner. 1901 Values for the "error" parameter MUST NOT include characters 1902 outside the set %x20-21 / %x23-5B / %x5D-7E. 1903 error_description 1904 OPTIONAL. A human-readable ASCII [USASCII] text providing 1905 additional information, used to assist the client developer in 1906 understanding the error that occurred. 1907 Values for the "error_description" parameter MUST NOT include 1908 characters outside the set %x20-21 / %x23-5B / %x5D-7E. 1909 error_uri 1910 OPTIONAL. A URI identifying a human-readable web page with 1911 information about the error, used to provide the client 1912 developer with additional information about the error. 1913 Values for the "error_uri" parameter MUST conform to the URI- 1914 Reference syntax, and thus MUST NOT include characters outside 1915 the set %x21 / %x23-5B / %x5D-7E. 1917 The parameters are included in the entity body of the HTTP response 1918 using the "application/json" media type as defined by [RFC4627]. The 1919 parameters are serialized into a JSON structure by adding each 1920 parameter at the highest structure level. Parameter names and string 1921 values are included as JSON strings. Numerical values are included 1922 as JSON numbers. The order of parameters does not matter and can 1923 vary. 1925 For example: 1927 HTTP/1.1 400 Bad Request 1928 Content-Type: application/json;charset=UTF-8 1929 Cache-Control: no-store 1930 Pragma: no-cache 1932 { 1933 "error":"invalid_request" 1934 } 1936 6. Refreshing an Access Token 1938 If the authorization server issued a refresh token to the client, the 1939 client makes a refresh request to the token endpoint by adding the 1940 following parameters using the "application/x-www-form-urlencoded" 1941 format in the HTTP request entity-body: 1943 grant_type 1944 REQUIRED. Value MUST be set to "refresh_token". 1945 refresh_token 1946 REQUIRED. The refresh token issued to the client. 1947 scope 1948 OPTIONAL. The scope of the access request as described by 1949 Section 3.3. The requested scope MUST NOT include any scope 1950 not originally granted by the resource owner, and if omitted is 1951 treated as equal to the scope originally granted by the 1952 resource owner. 1954 Because refresh tokens are typically long-lasting credentials used to 1955 request additional access tokens, the refresh token is bound to the 1956 client to which it was issued. If the client type is confidential or 1957 the client was issued client credentials (or assigned other 1958 authentication requirements), the client MUST authenticate with the 1959 authorization server as described in Section 3.2.1. 1961 For example, the client makes the following HTTP request using 1962 transport-layer security (extra line breaks are for display purposes 1963 only): 1965 POST /token HTTP/1.1 1966 Host: server.example.com 1967 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1968 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1970 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1972 The authorization server MUST: 1974 o require client authentication for confidential clients or for any 1975 client that was issued client credentials (or with other 1976 authentication requirements), 1977 o authenticate the client if client authentication is included and 1978 ensure the refresh token was issued to the authenticated client, 1979 and 1980 o validate the refresh token. 1982 If valid and authorized, the authorization server issues an access 1983 token as described in Section 5.1. If the request failed 1984 verification or is invalid, the authorization server returns an error 1985 response as described in Section 5.2. 1987 The authorization server MAY issue a new refresh token, in which case 1988 the client MUST discard the old refresh token and replace it with the 1989 new refresh token. The authorization server MAY revoke the old 1990 refresh token after issuing a new refresh token to the client. If a 1991 new refresh token is issued, the refresh token scope MUST be 1992 identical to that of the refresh token included by the client in the 1993 request. 1995 7. Accessing Protected Resources 1997 The client accesses protected resources by presenting the access 1998 token to the resource server. The resource server MUST validate the 1999 access token and ensure it has not expired and that its scope covers 2000 the requested resource. The methods used by the resource server to 2001 validate the access token (as well as any error responses) are beyond 2002 the scope of this specification, but generally involve an interaction 2003 or coordination between the resource server and the authorization 2004 server. 2006 The method in which the client utilizes the access token to 2007 authenticate with the resource server depends on the type of access 2008 token issued by the authorization server. Typically, it involves 2009 using the HTTP "Authorization" request header field [RFC2617] with an 2010 authentication scheme defined by the access token type specification. 2012 7.1. Access Token Types 2014 The access token type provides the client with the information 2015 required to successfully utilize the access token to make a protected 2016 resource request (along with type-specific attributes). The client 2017 MUST NOT use an access token if it does not understand the token 2018 type. 2020 For example, the "bearer" token type defined in 2021 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 2022 token string in the request: 2024 GET /resource/1 HTTP/1.1 2025 Host: example.com 2026 Authorization: Bearer mF_9.B5f-4.1JqM 2028 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 2029 utilized by issuing a MAC key together with the access token which is 2030 used to sign certain components of the HTTP requests: 2032 GET /resource/1 HTTP/1.1 2033 Host: example.com 2034 Authorization: MAC id="h480djs93hd8", 2035 nonce="274312:dj83hs9s", 2036 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 2038 The above examples are provided for illustration purposes only. 2039 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 2040 [I-D.ietf-oauth-v2-http-mac] specifications before use. 2042 Each access token type definition specifies the additional attributes 2043 (if any) sent to the client together with the "access_token" response 2044 parameter. It also defines the HTTP authentication method used to 2045 include the access token when making a protected resource request. 2047 7.2. Error Response 2049 If a resource access request fails, the resource server SHOULD inform 2050 the client of the error. While the specifics of such error responses 2051 are beyond the scope of this specification, this documents 2052 establishes a common registry in Section 11.4 for error values to be 2053 shared among OAuth token authentication schemes. 2055 New authentication schemes designed primarily for OAuth token 2056 authentication SHOULD define a mechanism for providing an error 2057 status code to the client, in which the error values allowed are 2058 registered in the error registry established by this specification. 2059 Such schemes MAY limit the set of valid error codes to a subset of 2060 the registered values. If the error code is returned using a named 2061 parameter, the parameter name SHOULD be "error". 2063 Other schemes capable of being used for OAuth token authentication, 2064 but not primarily designed for that purpose, MAY bind their error 2065 values to the registry in the same manner. 2067 New authentication schemes MAY choose to also specify the use of the 2068 "error_description" and "error_uri" parameters to return error 2069 information in a manner parallel to their usage in this 2070 specification. 2072 8. Extensibility 2074 8.1. Defining Access Token Types 2076 Access token types can be defined in one of two ways: registered in 2077 the access token type registry (following the procedures in 2078 Section 11.1), or by using a unique absolute URI as its name. 2080 Types utilizing a URI name SHOULD be limited to vendor-specific 2081 implementations that are not commonly applicable, and are specific to 2082 the implementation details of the resource server where they are 2083 used. 2085 All other types MUST be registered. Type names MUST conform to the 2086 type-name ABNF. If the type definition includes a new HTTP 2087 authentication scheme, the type name SHOULD be identical to the HTTP 2088 authentication scheme name (as defined by [RFC2617]). The token type 2089 "example" is reserved for use in examples. 2091 type-name = 1*name-char 2092 name-char = "-" / "." / "_" / DIGIT / ALPHA 2094 8.2. Defining New Endpoint Parameters 2096 New request or response parameters for use with the authorization 2097 endpoint or the token endpoint are defined and registered in the 2098 parameters registry following the procedure in Section 11.2. 2100 Parameter names MUST conform to the param-name ABNF and parameter 2101 values syntax MUST be well-defined (e.g., using ABNF, or a reference 2102 to the syntax of an existing parameter). 2104 param-name = 1*name-char 2105 name-char = "-" / "." / "_" / DIGIT / ALPHA 2107 Unregistered vendor-specific parameter extensions that are not 2108 commonly applicable, and are specific to the implementation details 2109 of the authorization server where they are used SHOULD utilize a 2110 vendor-specific prefix that is not likely to conflict with other 2111 registered values (e.g. begin with 'companyname_'). 2113 8.3. Defining New Authorization Grant Types 2115 New authorization grant types can be defined by assigning them a 2116 unique absolute URI for use with the "grant_type" parameter. If the 2117 extension grant type requires additional token endpoint parameters, 2118 they MUST be registered in the OAuth parameters registry as described 2119 by Section 11.2. 2121 8.4. Defining New Authorization Endpoint Response Types 2123 New response types for use with the authorization endpoint are 2124 defined and registered in the authorization endpoint response type 2125 registry following the procedure in Section 11.3. Response type 2126 names MUST conform to the response-type ABNF. 2128 response-type = response-name *( SP response-name ) 2129 response-name = 1*response-char 2130 response-char = "_" / DIGIT / ALPHA 2132 If a response type contains one or more space characters (%x20), it 2133 is compared as a space-delimited list of values in which the order of 2134 values does not matter. Only one order of values can be registered, 2135 which covers all other arrangements of the same set of values. 2137 For example, the response type "token code" is left undefined by this 2138 specification. However, an extension can define and register the 2139 "token code" response type. Once registered, the same combination 2140 cannot be registered as "code token", but both values can be used to 2141 denote the same response type. 2143 8.5. Defining Additional Error Codes 2145 In cases where protocol extensions (i.e. access token types, 2146 extension parameters, or extension grant types) require additional 2147 error codes to be used with the authorization code grant error 2148 response (Section 4.1.2.1), the implicit grant error response 2149 (Section 4.2.2.1), the token error response (Section 5.2), or the 2150 resource access error response (Section 7.2), such error codes MAY be 2151 defined. 2153 Extension error codes MUST be registered (following the procedures in 2154 Section 11.4) if the extension they are used in conjunction with is a 2155 registered access token type, a registered endpoint parameter, or an 2156 extension grant type. Error codes used with unregistered extensions 2157 MAY be registered. 2159 Error codes MUST conform to the error ABNF, and SHOULD be prefixed by 2160 an identifying name when possible. For example, an error identifying 2161 an invalid value set to the extension parameter "example" SHOULD be 2162 named "example_invalid". 2164 error = 1*error-char 2165 error-char = %x20-21 / %x23-5B / %x5D-7E 2167 9. Native Applications 2169 Native applications are clients installed and executed on the device 2170 used by the resource owner (i.e. desktop application, native mobile 2171 application). Native applications require special consideration 2172 related to security, platform capabilities, and overall end-user 2173 experience. 2175 The authorization endpoint requires interaction between the client 2176 and the resource owner's user-agent. Native applications can invoke 2177 an external user-agent or embed a user-agent within the application. 2178 For example: 2180 o External user-agent - the native application can capture the 2181 response from the authorization server using a redirection URI 2182 with a scheme registered with the operating system to invoke the 2183 client as the handler, manual copy-and-paste of the credentials, 2184 running a local web server, installing a user-agent extension, or 2185 by providing a redirection URI identifying a server-hosted 2186 resource under the client's control, which in turn makes the 2187 response available to the native application. 2188 o Embedded user-agent - the native application obtains the response 2189 by directly communicating with the embedded user-agent by 2190 monitoring state changes emitted during the resource load, or 2191 accessing the user-agent's cookies storage. 2193 When choosing between an external or embedded user-agent, developers 2194 should consider: 2196 o An External user-agent may improve completion rate as the resource 2197 owner may already have an active session with the authorization 2198 server removing the need to re-authenticate. It provides a 2199 familiar end-user experience and functionality. The resource 2200 owner may also rely on user-agent features or extensions to assist 2201 with authentication (e.g. password manager, 2-factor device 2202 reader). 2203 o An embedded user-agent may offer improved usability, as it removes 2204 the need to switch context and open new windows. 2205 o An embedded user-agent poses a security challenge because resource 2206 owners are authenticating in an unidentified window without access 2207 to the visual protections found in most external user-agents. An 2208 embedded user-agent educates end-users to trust unidentified 2209 requests for authentication (making phishing attacks easier to 2210 execute). 2212 When choosing between the implicit grant type and the authorization 2213 code grant type, the following should be considered: 2215 o Native applications that use the authorization code grant type 2216 SHOULD do so without using client credentials, due to the native 2217 application's inability to keep client credentials confidential. 2218 o When using the implicit grant type flow a refresh token is not 2219 returned which requires repeating the authorization process once 2220 the access token expires. 2222 10. Security Considerations 2224 As a flexible and extensible framework, OAuth's security 2225 considerations depend on many factors. The following sections 2226 provide implementers with security guidelines focused on the three 2227 client profiles described in Section 2.1: web application, user- 2228 agent-based application, and native application. 2230 A comprehensive OAuth security model and analysis, as well as 2231 background for the protocol design, is provided by 2232 [I-D.ietf-oauth-v2-threatmodel]. 2234 10.1. Client Authentication 2236 The authorization server establishes client credentials with web 2237 application clients for the purpose of client authentication. The 2238 authorization server is encouraged to consider stronger client 2239 authentication means than a client password. Web application clients 2240 MUST ensure confidentiality of client passwords and other client 2241 credentials. 2243 The authorization server MUST NOT issue client passwords or other 2244 client credentials to native application or user-agent-based 2245 application clients for the purpose of client authentication. The 2246 authorization server MAY issue a client password or other credentials 2247 for a specific installation of a native application client on a 2248 specific device. 2250 When client authentication is not possible, the authorization server 2251 SHOULD employ other means to validate the client's identity. For 2252 example, by requiring the registration of the client redirection URI 2253 or enlisting the resource owner to confirm identity. A valid 2254 redirection URI is not sufficient to verify the client's identity 2255 when asking for resource owner authorization, but can be used to 2256 prevent delivering credentials to a counterfeit client after 2257 obtaining resource owner authorization. 2259 The authorization server must consider the security implications of 2260 interacting with unauthenticated clients and take measures to limit 2261 the potential exposure of other credentials (e.g. refresh tokens) 2262 issued to such clients. 2264 10.2. Client Impersonation 2266 A malicious client can impersonate another client and obtain access 2267 to protected resources, if the impersonated client fails to, or is 2268 unable to, keep its client credentials confidential. 2270 The authorization server MUST authenticate the client whenever 2271 possible. If the authorization server cannot authenticate the client 2272 due to the client's nature, the authorization server MUST require the 2273 registration of any redirection URI used for receiving authorization 2274 responses, and SHOULD utilize other means to protect resource owners 2275 from such potentially malicious clients. For example, the 2276 authorization server can engage the resource owner to assist in 2277 identifying the client and its origin. 2279 The authorization server SHOULD enforce explicit resource owner 2280 authentication and provide the resource owner with information about 2281 the client and the requested authorization scope and lifetime. It is 2282 up to the resource owner to review the information in the context of 2283 the current client, and authorize or deny the request. 2285 The authorization server SHOULD NOT process repeated authorization 2286 requests automatically (without active resource owner interaction) 2287 without authenticating the client or relying on other measures to 2288 ensure the repeated request comes from the original client and not an 2289 impersonator. 2291 10.3. Access Tokens 2293 Access token credentials (as well as any confidential access token 2294 attributes) MUST be kept confidential in transit and storage, and 2295 only shared among the authorization server, the resource servers the 2296 access token is valid for, and the client to whom the access token is 2297 issued. Access token credentials MUST only be transmitted using TLS 2298 as described in Section 1.6 with server authentication as defined by 2299 [RFC2818]. 2301 When using the implicit grant type, the access token is transmitted 2302 in the URI fragment, which can expose it to unauthorized parties. 2304 The authorization server MUST ensure that access tokens cannot be 2305 generated, modified, or guessed to produce valid access tokens by 2306 unauthorized parties. 2308 The client SHOULD request access tokens with the minimal scope 2309 necessary. The authorization server SHOULD take the client identity 2310 into account when choosing how to honor the requested scope, and MAY 2311 issue an access token with a less rights than requested. 2313 This specification does not provide any methods for the resource 2314 server to ensure that an access token presented to it by a given 2315 client was issued to that client by the authorization server. 2317 10.4. Refresh Tokens 2319 Authorization servers MAY issue refresh tokens to web application 2320 clients and native application clients. 2322 Refresh tokens MUST be kept confidential in transit and storage, and 2323 shared only among the authorization server and the client to whom the 2324 refresh tokens were issued. The authorization server MUST maintain 2325 the binding between a refresh token and the client to whom it was 2326 issued. Refresh tokens MUST only be transmitted using TLS as 2327 described in Section 1.6 with server authentication as defined by 2328 [RFC2818]. 2330 The authorization server MUST verify the binding between the refresh 2331 token and client identity whenever the client identity can be 2332 authenticated. When client authentication is not possible, the 2333 authorization server SHOULD deploy other means to detect refresh 2334 token abuse. 2336 For example, the authorization server could employ refresh token 2337 rotation in which a new refresh token is issued with every access 2338 token refresh response. The previous refresh token is invalidated 2339 but retained by the authorization server. If a refresh token is 2340 compromised and subsequently used by both the attacker and the 2341 legitimate client, one of them will present an invalidated refresh 2342 token which will inform the authorization server of the breach. 2344 The authorization server MUST ensure that refresh tokens cannot be 2345 generated, modified, or guessed to produce valid refresh tokens by 2346 unauthorized parties. 2348 10.5. Authorization Codes 2350 The transmission of authorization codes SHOULD be made over a secure 2351 channel, and the client SHOULD require the use of TLS with its 2352 redirection URI if the URI identifies a network resource. Since 2353 authorization codes are transmitted via user-agent redirections, they 2354 could potentially be disclosed through user-agent history and HTTP 2355 referrer headers. 2357 Authorization codes operate as plaintext bearer credentials, used to 2358 verify that the resource owner who granted authorization at the 2359 authorization server is the same resource owner returning to the 2360 client to complete the process. Therefore, if the client relies on 2361 the authorization code for its own resource owner authentication, the 2362 client redirection endpoint MUST require the use of TLS. 2364 Authorization codes MUST be short lived and single use. If the 2365 authorization server observes multiple attempts to exchange an 2366 authorization code for an access token, the authorization server 2367 SHOULD attempt to revoke all access tokens already granted based on 2368 the compromised authorization code. 2370 If the client can be authenticated, the authorization servers MUST 2371 authenticate the client and ensure that the authorization code was 2372 issued to the same client. 2374 10.6. Authorization Code Redirection URI Manipulation 2376 When requesting authorization using the authorization code grant 2377 type, the client can specify a redirection URI via the "redirect_uri" 2378 parameter. If an attacker can manipulate the value of the 2379 redirection URI, it can cause the authorization server to redirect 2380 the resource owner user-agent to a URI under the control of the 2381 attacker with the authorization code. 2383 An attacker can create an account at a legitimate client and initiate 2384 the authorization flow. When the attacker's user-agent is sent to 2385 the authorization server to grant access, the attacker grabs the 2386 authorization URI provided by the legitimate client, and replaces the 2387 client's redirection URI with a URI under the control of the 2388 attacker. The attacker then tricks the victim into following the 2389 manipulated link to authorize access to the legitimate client. 2391 Once at the authorization server, the victim is prompted with a 2392 normal, valid request on behalf of a legitimate and trusted client, 2393 and authorizes the request. The victim is then redirected to an 2394 endpoint under the control of the attacker with the authorization 2395 code. The attacker completes the authorization flow by sending the 2396 authorization code to the client using the original redirection URI 2397 provided by the client. The client exchanges the authorization code 2398 with an access token and links it to the attacker's client account 2399 which can now gain access to the protected resources authorized by 2400 the victim (via the client). 2402 In order to prevent such an attack, the authorization server MUST 2403 ensure that the redirection URI used to obtain the authorization code 2404 is identical to the redirection URI provided when exchanging the 2405 authorization code for an access token. The authorization server 2406 MUST require public clients and SHOULD require confidential clients 2407 to register their redirection URIs. If a redirection URI is provided 2408 in the request, the authorization server MUST validate it against the 2409 registered value. 2411 10.7. Resource Owner Password Credentials 2413 The resource owner password credentials grant type is often used for 2414 legacy or migration reasons. It reduces the overall risk of storing 2415 username and password by the client, but does not eliminate the need 2416 to expose highly privileged credentials to the client. 2418 This grant type carries a higher risk than other grant types because 2419 it maintains the password anti-pattern this protocol seeks to avoid. 2420 The client could abuse the password or the password could 2421 unintentionally be disclosed to an attacker (e.g. via log files or 2422 other records kept by the client). 2424 Additionally, because the resource owner does not have control over 2425 the authorization process (the resource owner involvement ends when 2426 it hands over its credentials to the client), the client can obtain 2427 access tokens with a broader scope than desired by the resource 2428 owner. The authorization server should consider the scope and 2429 lifetime of access tokens issued via this grant type. 2431 The authorization server and client SHOULD minimize use of this grant 2432 type and utilize other grant types whenever possible. 2434 10.8. Request Confidentiality 2436 Access tokens, refresh tokens, resource owner passwords, and client 2437 credentials MUST NOT be transmitted in the clear. Authorization 2438 codes SHOULD NOT be transmitted in the clear. 2440 The "state" and "scope" parameters SHOULD NOT include sensitive 2441 client or resource owner information in plain text as they can be 2442 transmitted over insecure channels or stored insecurely. 2444 10.9. Endpoints Authenticity 2446 In order to prevent man-in-the-middle attacks, the authorization 2447 server MUST require the use of TLS with server authentication as 2448 defined by [RFC2818] for any request sent to the authorization and 2449 token endpoints. The client MUST validate the authorization server's 2450 TLS certificate as defined by [RFC6125], and in accordance with its 2451 requirements for server identity authentication. 2453 10.10. Credentials Guessing Attacks 2455 The authorization server MUST prevent attackers from guessing access 2456 tokens, authorization codes, refresh tokens, resource owner 2457 passwords, and client credentials. 2459 The probability of an attacker guessing generated tokens (and other 2460 credentials not intended for handling by end-users) MUST be less than 2461 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2463 The authorization server MUST utilize other means to protect 2464 credentials intended for end-user usage. 2466 10.11. Phishing Attacks 2468 Wide deployment of this and similar protocols may cause end-users to 2469 become inured to the practice of being redirected to websites where 2470 they are asked to enter their passwords. If end-users are not 2471 careful to verify the authenticity of these websites before entering 2472 their credentials, it will be possible for attackers to exploit this 2473 practice to steal resource owners' passwords. 2475 Service providers should attempt to educate end-users about the risks 2476 phishing attacks pose, and should provide mechanisms that make it 2477 easy for end-users to confirm the authenticity of their sites. 2478 Client developers should consider the security implications of how 2479 they interact with the user-agent (e.g., external, embedded), and the 2480 ability of the end-user to verify the authenticity of the 2481 authorization server. 2483 To reduce the risk of phishing attacks, the authorization servers 2484 MUST require the use of TLS on every endpoint used for end-user 2485 interaction. 2487 10.12. Cross-Site Request Forgery 2489 Cross-site request forgery (CSRF) is an exploit in which an attacker 2490 causes the user-agent of a victim end-user to follow a malicious URI 2491 (e.g. provided to the user-agent as a misleading link, image, or 2492 redirection) to a trusting server (usually established via the 2493 presence of a valid session cookie). 2495 A CSRF attack against the client's redirection URI allows an attacker 2496 to inject their own authorization code or access token, which can 2497 result in the client using an access token associated with the 2498 attacker's protected resources rather than the victim's (e.g. save 2499 the victim's bank account information to a protected resource 2500 controlled by the attacker). 2502 The client MUST implement CSRF protection for its redirection URI. 2503 This is typically accomplished by requiring any request sent to the 2504 redirection URI endpoint to include a value that binds the request to 2505 the user-agent's authenticated state (e.g. a hash of the session 2506 cookie used to authenticate the user-agent). The client SHOULD 2507 utilize the "state" request parameter to deliver this value to the 2508 authorization server when making an authorization request. 2510 Once authorization has been obtained from the end-user, the 2511 authorization server redirects the end-user's user-agent back to the 2512 client with the required binding value contained in the "state" 2513 parameter. The binding value enables the client to verify the 2514 validity of the request by matching the binding value to the user- 2515 agent's authenticated state. The binding value used for CSRF 2516 protection MUST contain a non-guessable value (as described in 2517 Section 10.10), and the user-agent's authenticated state (e.g. 2519 session cookie, HTML5 local storage) MUST be kept in a location 2520 accessible only to the client and the user-agent (i.e., protected by 2521 same-origin policy). 2523 A CSRF attack against the authorization server's authorization 2524 endpoint can result in an attacker obtaining end-user authorization 2525 for a malicious client without involving or alerting the end-user. 2527 The authorization server MUST implement CSRF protection for its 2528 authorization endpoint, and ensure that a malicious client cannot 2529 obtain authorization without the awareness and explicit consent of 2530 the resource owner. 2532 10.13. Clickjacking 2534 In a clickjacking attack, an attacker registers a legitimate client 2535 and then constructs a malicious site in which it loads the 2536 authorization server's authorization endpoint web page in a 2537 transparent iframe overlaid on top of a set of dummy buttons which 2538 are carefully constructed to be placed directly under important 2539 buttons on the authorization page. When an end-user clicks a 2540 misleading visible button, the end-user is actually clicking an 2541 invisible button on the authorization page (such as an "Authorize" 2542 button). This allows an attacker to trick a resource owner into 2543 granting its client access without their knowledge. 2545 To prevent this form of attack, native applications SHOULD use 2546 external browsers instead of embedding browsers within the 2547 application when requesting end-user authorization. For most newer 2548 browsers, avoidance of iframes can be enforced by the authorization 2549 server using the (non-standard) "x-frame-options" header. This 2550 header can have two values, "deny" and "sameorigin", which will block 2551 any framing, or framing by sites with a different origin, 2552 respectively. For older browsers, JavaScript framebusting techniques 2553 can be used but may not be effective in all browsers. 2555 10.14. Code Injection and Input Validation 2557 A code injection attack occurs when an input or otherwise external 2558 variable is used by an application unsanitized and causes 2559 modification to the application logic. This may allow an attacker to 2560 gain access to the application device or its data, cause denial of 2561 service, or a wide range of malicious side-effects. 2563 The Authorization server and client MUST sanitize (and validate when 2564 possible) any value received, in particular, the value of the "state" 2565 and "redirect_uri" parameters. 2567 10.15. Open Redirectors 2569 The authorization server authorization endpoint and the client 2570 redirection endpoint can be improperly configured and operate as open 2571 redirectors. An open redirector is an endpoint using a parameter to 2572 automatically redirect a user-agent to the location specified by the 2573 parameter value without any validation. 2575 Open redirectors can be used in phishing attacks, or by an attacker 2576 to get end-users to visit malicious sites by making the URI's 2577 authority look like a familiar and trusted destination. In addition, 2578 if the authorization server allows the client to register only part 2579 of the redirection URI, an attacker can use an open redirector 2580 operated by the client to construct a redirection URI that will pass 2581 the authorization server validation but will send the authorization 2582 code or access token to an endpoint under the control of the 2583 attacker. 2585 11. IANA Considerations 2587 11.1. The OAuth Access Token Type Registry 2589 This specification establishes the OAuth access token type registry. 2591 Access token types are registered with a Specification Required 2592 ([RFC5226]) after a two week review period on the [TBD]@ietf.org 2593 mailing list, on the advice of one or more Designated Experts. 2594 However, to allow for the allocation of values prior to publication, 2595 the Designated Expert(s) may approve registration once they are 2596 satisfied that such a specification will be published. 2598 Registration requests must be sent to the [TBD]@ietf.org mailing list 2599 for review and comment, with an appropriate subject (e.g., "Request 2600 for access token type: example"). [[ Note to RFC-EDITOR: The name of 2601 the mailing list should be determined in consultation with the IESG 2602 and IANA. Suggested name: oauth-ext-review. ]] 2604 Within the review period, the Designated Expert(s) will either 2605 approve or deny the registration request, communicating this decision 2606 to the review list and IANA. Denials should include an explanation 2607 and, if applicable, suggestions as to how to make the request 2608 successful. 2610 IANA must only accept registry updates from the Designated Expert(s), 2611 and should direct all requests for registration to the review mailing 2612 list. 2614 11.1.1. Registration Template 2616 Type name: 2617 The name requested (e.g., "example"). 2618 Additional Token Endpoint Response Parameters: 2619 Additional response parameters returned together with the 2620 "access_token" parameter. New parameters MUST be separately 2621 registered in the OAuth parameters registry as described by 2622 Section 11.2. 2623 HTTP Authentication Scheme(s): 2624 The HTTP authentication scheme name(s), if any, used to 2625 authenticate protected resources requests using access tokens of 2626 this type. 2627 Change controller: 2628 For standards-track RFCs, state "IETF". For others, give the name 2629 of the responsible party. Other details (e.g., postal address, 2630 e-mail address, home page URI) may also be included. 2631 Specification document(s): 2632 Reference to the document that specifies the parameter, preferably 2633 including a URI that can be used to retrieve a copy of the 2634 document. An indication of the relevant sections may also be 2635 included, but is not required. 2637 11.2. The OAuth Parameters Registry 2639 This specification establishes the OAuth parameters registry. 2641 Additional parameters for inclusion in the authorization endpoint 2642 request, the authorization endpoint response, the token endpoint 2643 request, or the token endpoint response are registered with a 2644 Specification Required ([RFC5226]) after a two week review period on 2645 the [TBD]@ietf.org mailing list, on the advice of one or more 2646 Designated Experts. However, to allow for the allocation of values 2647 prior to publication, the Designated Expert(s) may approve 2648 registration once they are satisfied that such a specification will 2649 be published. 2651 Registration requests must be sent to the [TBD]@ietf.org mailing list 2652 for review and comment, with an appropriate subject (e.g., "Request 2653 for parameter: example"). [[ Note to RFC-EDITOR: The name of the 2654 mailing list should be determined in consultation with the IESG and 2655 IANA. Suggested name: oauth-ext-review. ]] 2657 Within the review period, the Designated Expert(s) will either 2658 approve or deny the registration request, communicating this decision 2659 to the review list and IANA. Denials should include an explanation 2660 and, if applicable, suggestions as to how to make the request 2661 successful. 2663 IANA must only accept registry updates from the Designated Expert(s), 2664 and should direct all requests for registration to the review mailing 2665 list. 2667 11.2.1. Registration Template 2669 Parameter name: 2670 The name requested (e.g., "example"). 2671 Parameter usage location: 2672 The location(s) where parameter can be used. The possible 2673 locations are: authorization request, authorization response, 2674 token request, or token response. 2675 Change controller: 2676 For standards-track RFCs, state "IETF". For others, give the name 2677 of the responsible party. Other details (e.g., postal address, 2678 e-mail address, home page URI) may also be included. 2679 Specification document(s): 2680 Reference to the document that specifies the parameter, preferably 2681 including a URI that can be used to retrieve a copy of the 2682 document. An indication of the relevant sections may also be 2683 included, but is not required. 2685 11.2.2. Initial Registry Contents 2687 The OAuth Parameters Registry's initial contents are: 2689 o Parameter name: client_id 2690 o Parameter usage location: authorization request, token request 2691 o Change controller: IETF 2692 o Specification document(s): [[ this document ]] 2694 o Parameter name: client_secret 2695 o Parameter usage location: token request 2696 o Change controller: IETF 2697 o Specification document(s): [[ this document ]] 2699 o Parameter name: response_type 2700 o Parameter usage location: authorization request 2701 o Change controller: IETF 2702 o Specification document(s): [[ this document ]] 2704 o Parameter name: redirect_uri 2705 o Parameter usage location: authorization request, token request 2706 o Change controller: IETF 2707 o Specification document(s): [[ this document ]] 2708 o Parameter name: scope 2709 o Parameter usage location: authorization request, authorization 2710 response, token request, token response 2711 o Change controller: IETF 2712 o Specification document(s): [[ this document ]] 2714 o Parameter name: state 2715 o Parameter usage location: authorization request, authorization 2716 response 2717 o Change controller: IETF 2718 o Specification document(s): [[ this document ]] 2720 o Parameter name: code 2721 o Parameter usage location: authorization response, token request 2722 o Change controller: IETF 2723 o Specification document(s): [[ this document ]] 2725 o Parameter name: error_description 2726 o Parameter usage location: authorization response, token response 2727 o Change controller: IETF 2728 o Specification document(s): [[ this document ]] 2730 o Parameter name: error_uri 2731 o Parameter usage location: authorization response, token response 2732 o Change controller: IETF 2733 o Specification document(s): [[ this document ]] 2735 o Parameter name: grant_type 2736 o Parameter usage location: token request 2737 o Change controller: IETF 2738 o Specification document(s): [[ this document ]] 2740 o Parameter name: access_token 2741 o Parameter usage location: authorization response, token response 2742 o Change controller: IETF 2743 o Specification document(s): [[ this document ]] 2745 o Parameter name: token_type 2746 o Parameter usage location: authorization response, token response 2747 o Change controller: IETF 2748 o Specification document(s): [[ this document ]] 2750 o Parameter name: expires_in 2751 o Parameter usage location: authorization response, token response 2752 o Change controller: IETF 2753 o Specification document(s): [[ this document ]] 2754 o Parameter name: username 2755 o Parameter usage location: token request 2756 o Change controller: IETF 2757 o Specification document(s): [[ this document ]] 2759 o Parameter name: password 2760 o Parameter usage location: token request 2761 o Change controller: IETF 2762 o Specification document(s): [[ this document ]] 2764 o Parameter name: refresh_token 2765 o Parameter usage location: token request, token response 2766 o Change controller: IETF 2767 o Specification document(s): [[ this document ]] 2769 11.3. The OAuth Authorization Endpoint Response Type Registry 2771 This specification establishes the OAuth authorization endpoint 2772 response type registry. 2774 Additional response type for use with the authorization endpoint are 2775 registered with a Specification Required ([RFC5226]) after a two week 2776 review period on the [TBD]@ietf.org mailing list, on the advice of 2777 one or more Designated Experts. However, to allow for the allocation 2778 of values prior to publication, the Designated Expert(s) may approve 2779 registration once they are satisfied that such a specification will 2780 be published. 2782 Registration requests must be sent to the [TBD]@ietf.org mailing list 2783 for review and comment, with an appropriate subject (e.g., "Request 2784 for response type: example"). [[ Note to RFC-EDITOR: The name of the 2785 mailing list should be determined in consultation with the IESG and 2786 IANA. Suggested name: oauth-ext-review. ]] 2788 Within the review period, the Designated Expert(s) will either 2789 approve or deny the registration request, communicating this decision 2790 to the review list and IANA. Denials should include an explanation 2791 and, if applicable, suggestions as to how to make the request 2792 successful. 2794 IANA must only accept registry updates from the Designated Expert(s), 2795 and should direct all requests for registration to the review mailing 2796 list. 2798 11.3.1. Registration Template 2799 Response type name: 2800 The name requested (e.g., "example"). 2801 Change controller: 2802 For standards-track RFCs, state "IETF". For others, give the name 2803 of the responsible party. Other details (e.g., postal address, 2804 e-mail address, home page URI) may also be included. 2805 Specification document(s): 2806 Reference to the document that specifies the type, preferably 2807 including a URI that can be used to retrieve a copy of the 2808 document. An indication of the relevant sections may also be 2809 included, but is not required. 2811 11.3.2. Initial Registry Contents 2813 The OAuth Authorization Endpoint Response Type Registry's initial 2814 contents are: 2816 o Response type name: code 2817 o Change controller: IETF 2818 o Specification document(s): [[ this document ]] 2820 o Response type name: token 2821 o Change controller: IETF 2822 o Specification document(s): [[ this document ]] 2824 11.4. The OAuth Extensions Error Registry 2826 This specification establishes the OAuth extensions error registry. 2828 Additional error codes used together with other protocol extensions 2829 (i.e. extension grant types, access token types, or extension 2830 parameters) are registered with a Specification Required ([RFC5226]) 2831 after a two week review period on the [TBD]@ietf.org mailing list, on 2832 the advice of one or more Designated Experts. However, to allow for 2833 the allocation of values prior to publication, the Designated 2834 Expert(s) may approve registration once they are satisfied that such 2835 a specification will be published. 2837 Registration requests must be sent to the [TBD]@ietf.org mailing list 2838 for review and comment, with an appropriate subject (e.g., "Request 2839 for error code: example"). [[ Note to RFC-EDITOR: The name of the 2840 mailing list should be determined in consultation with the IESG and 2841 IANA. Suggested name: oauth-ext-review. ]] 2843 Within the review period, the Designated Expert(s) will either 2844 approve or deny the registration request, communicating this decision 2845 to the review list and IANA. Denials should include an explanation 2846 and, if applicable, suggestions as to how to make the request 2847 successful. 2849 IANA must only accept registry updates from the Designated Expert(s), 2850 and should direct all requests for registration to the review mailing 2851 list. 2853 11.4.1. Registration Template 2855 Error name: 2856 The name requested (e.g., "example"). Values for the error name 2857 MUST NOT include characters outside the set %x20-21 / %x23-5B / 2858 %x5D-7E. 2859 Error usage location: 2860 The location(s) where the error can be used. The possible 2861 locations are: authorization code grant error response 2862 (Section 4.1.2.1), implicit grant error response 2863 (Section 4.2.2.1), token error response (Section 5.2), or resource 2864 access error response (Section 7.2). 2865 Related protocol extension: 2866 The name of the extension grant type, access token type, or 2867 extension parameter, the error code is used in conjunction with. 2868 Change controller: 2869 For standards-track RFCs, state "IETF". For others, give the name 2870 of the responsible party. Other details (e.g., postal address, 2871 e-mail address, home page URI) may also be included. 2872 Specification document(s): 2873 Reference to the document that specifies the error code, 2874 preferably including a URI that can be used to retrieve a copy of 2875 the document. An indication of the relevant sections may also be 2876 included, but is not required. 2878 12. References 2880 12.1. Normative References 2882 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2883 Requirement Levels", BCP 14, RFC 2119, March 1997. 2885 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2886 RFC 2246, January 1999. 2888 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2889 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2890 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2892 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2893 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2894 Authentication: Basic and Digest Access Authentication", 2895 RFC 2617, June 1999. 2897 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2899 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2900 Resource Identifier (URI): Generic Syntax", STD 66, 2901 RFC 3986, January 2005. 2903 [RFC4627] Crockford, D., "The application/json Media Type for 2904 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2906 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2907 RFC 4949, August 2007. 2909 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2910 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2911 May 2008. 2913 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2914 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2916 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2917 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2919 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2920 Verification of Domain-Based Application Service Identity 2921 within Internet Public Key Infrastructure Using X.509 2922 (PKIX) Certificates in the Context of Transport Layer 2923 Security (TLS)", RFC 6125, March 2011. 2925 [USASCII] American National Standards Institute, "Coded Character 2926 Set -- 7-bit American Standard Code for Information 2927 Interchange", ANSI X3.4, 1986. 2929 [W3C.REC-html401-19991224] 2930 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 2931 Specification", World Wide Web Consortium 2932 Recommendation REC-html401-19991224, December 1999, 2933 . 2935 12.2. Informative References 2937 [I-D.draft-hardt-oauth-01] 2938 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2939 Web Resource Authorization Profiles", January 2010. 2941 [I-D.ietf-httpbis-p7-auth] 2942 Fielding, R., Lafon, Y., and J. Reschke, "HTTP/1.1, part 2943 7: Authentication", draft-ietf-httpbis-p7-auth-19 (work in 2944 progress), March 2012. 2946 [I-D.ietf-oauth-saml2-bearer] 2947 Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for 2948 OAuth 2.0", draft-ietf-oauth-saml2-bearer-12 (work in 2949 progress), May 2012. 2951 [I-D.ietf-oauth-v2-bearer] 2952 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2953 Authorization Framework: Bearer Token Usage", 2954 draft-ietf-oauth-v2-bearer-20 (work in progress), 2955 June 2012. 2957 [I-D.ietf-oauth-v2-http-mac] 2958 Hammer-Lahav, E., "HTTP Authentication: MAC Access 2959 Authentication", draft-ietf-oauth-v2-http-mac-01 (work in 2960 progress), February 2012. 2962 [I-D.ietf-oauth-v2-threatmodel] 2963 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2964 Threat Model and Security Considerations", 2965 draft-ietf-oauth-v2-threatmodel-05 (work in progress), 2966 May 2012. 2968 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2969 April 2010. 2971 Appendix A. Augmented Backus-Naur Form (ABNF) Syntax 2973 This section provides Augmented Backus-Naur Form (ABNF) syntax 2974 descriptions for the elements defined in this specification using the 2975 notation of [RFC5234]. Elements are presented in the order first 2976 defined. 2978 Some of the definitions that follow use the "URI-reference" 2979 definition from [RFC3986]. 2981 Some of the definitions that follow use these common definitions: 2983 VSCHAR = %20-7E 2984 NQCHAR = %x21 / %x23-5B / %x5D-7E 2985 NQSCHAR = %x20-21 / %x23-5B / %x5D-7E 2986 UNICODENOCTRLCHAR = 2987 A.1. "client_id" Syntax 2989 The "client_id" element is defined in Section 2.3.1: 2991 client-id = *VSCHAR 2993 A.2. "client_secret" Syntax 2995 The "client_secret" element is defined in Section 2.3.1: 2997 client-secret = *VSCHAR 2999 A.3. "response_type" Syntax 3001 The "response_type" element is defined in Section 3.1.1 and 3002 Section 8.4: 3004 response-type = response-name *( SP response-name ) 3005 response-name = 1*response-char 3006 response-char = "_" / DIGIT / ALPHA 3008 A.4. "scope" Syntax 3010 The "scope" element is defined in Section 3.3: 3012 scope = scope-token *( SP scope-token ) 3013 scope-token = 1*NQCHAR 3015 A.5. "state" Syntax 3017 The "state" element is defined in Section 4.1.1, Section 4.1.2, 3018 Section 4.1.2.1, Section 4.2.1, Section 4.2.2, and Section 4.2.2.1: 3020 state = 1*VSCHAR 3022 A.6. "redirect_uri" Syntax 3024 The "redirect_uri" element is defined in Section 4.1.1, 3025 Section 4.1.3, and Section 4.2.1: 3027 redirect-uri = URI-reference 3029 A.7. "error" Syntax 3031 The "error" element is defined in Section 4.1.2.1, Section 4.2.2.1, 3032 Section 5.2, Section 7.2, and Section 8.5: 3034 error = 1*NQSCHAR 3036 A.8. "error_description" Syntax 3038 The "error_description" element is defined in Section 4.1.2.1, 3039 Section 4.2.2.1, Section 5.2, and Section 7.2: 3041 error-description = 1*NQSCHAR 3043 A.9. "error_uri" Syntax 3045 The "error_uri" element is defined in Section 4.1.2.1, 3046 Section 4.2.2.1, Section 5.2, and Section 7.2: 3048 error-uri = URI-reference 3050 A.10. "grant_type" Syntax 3052 The "grant_type" element is defined in Section 4.1.3, Section 4.3.2, 3053 Section 4.4.2, Section 6, and Section 4.5: 3055 grant-type = grant-name / URI-reference 3056 grant-name = 1*name-char 3057 name-char = "-" / "." / "_" / DIGIT / ALPHA 3059 A.11. "code" Syntax 3061 The "code" element is defined in Section 4.1.3: 3063 code = 1*VSCHAR 3065 A.12. "access_token" Syntax 3067 The "access_token" element is defined in Section 4.2.2 and 3068 Section 5.1: 3070 access-token = 1*VSCHAR 3072 A.13. "token_type" Syntax 3074 The "token_type" element is defined in Section 4.2.2, Section 5.1, 3075 and Section 8.1: 3077 token-type = type-name / URI-reference 3078 type-name = 1*name-char 3079 name-char = "-" / "." / "_" / DIGIT / ALPHA 3081 A.14. "expires_in" Syntax 3083 The "expires_in" element is defined in Section 4.2.2 and Section 5.1: 3085 expires-in = 1*DIGIT 3087 A.15. "username" Syntax 3089 The "username" element is defined in Section 4.3.2: 3091 username = *UNICODENOCTRLCHAR 3093 A.16. "password" Syntax 3095 The "password" element is defined in Section 4.3.2: 3097 password = *UNICODENOCTRLCHAR 3099 A.17. "refresh_token" Syntax 3101 The "refresh_token" element is defined in Section 5.1 and Section 6: 3103 refresh-token = 1*VSCHAR 3105 A.18. Endpoint Parameter Syntax 3107 The syntax for new endpoint parameters is defined in Section 8.2: 3109 param-name = 1*name-char 3110 name-char = "-" / "." / "_" / DIGIT / ALPHA 3112 Appendix B. Acknowledgements 3114 The initial OAuth 2.0 protocol specification was edited by David 3115 Recordon, based on two previous publications: the OAuth 1.0 community 3116 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 3117 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 3118 Considerations section was drafted by Torsten Lodderstedt, Mark 3119 McGloin, Phil Hunt, and Anthony Nadalin. The ABNF section was 3120 drafted by Michael B. Jones. 3122 The OAuth 1.0 community specification was edited by Eran Hammer and 3123 authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 3124 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 3125 Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 3126 Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 3127 Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 3129 The OAuth WRAP specification was edited by Dick Hardt and authored by 3130 Brian Eaton, Yaron Y. Goland, Dick Hardt, and Allen Tom. 3132 This specification is the work of the OAuth Working Group which 3133 includes dozens of active and dedicated participants. In particular, 3134 the following individuals contributed ideas, feedback, and wording 3135 which shaped and formed the final specification: 3137 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 3138 Bell, John Bradley, Brian Campbell, Scott Cantor, Marcos Caceres, 3139 Blaine Cook, Roger Crew, Brian Eaton, Wesley Eddy, Leah Culver, Bill 3140 de hOra, Andre DeMarre, Brian Eaton, Wolter Eldering, Brian Ellin, 3141 Igor Faynberg, George Fletcher, Tim Freeman, Luca Frosini, Evan 3142 Gilbert, Yaron Y. Goland, Brent Goldman, Kristoffer Gronowski, Justin 3143 Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. Jones, Terry 3144 Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, Rasmus 3145 Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul Madsen, 3146 Alastair Mair, Eve Maler, James Manger, Mark McGloin, Laurence Miao, 3147 William Mills, Chuck Mortimore, Anthony Nadalin, Julian Reschke, 3148 Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, Marius 3149 Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, Justin Smith, 3150 Haibin Song, Niv Steingarten, Christian Stuebner, Jeremy Suriel, Paul 3151 Tarjan, Christopher Thomas, Henry S. Thompson, Allen Tom, Franklin 3152 Tse, Nick Walker, Shane Weeden, and Skylar Woodward. 3154 This document was produced under the chairmanship of Blaine Cook, 3155 Peter Saint-Andre, Hannes Tschofenig, Barry Leiba, and Derek Atkins. 3156 The area directors included Lisa Dusseault, Peter Saint-Andre, and 3157 Stephen Farrell. 3159 Appendix C. Editor's Notes 3161 While many people contributed to this specification throughout its 3162 long journey, the editor would like to acknowledge and thank a few 3163 individuals for their outstanding and invaluable efforts leading up 3164 to the publication of this specification. 3166 David Recordon for continuously being one of OAuth's most valuable 3167 assets, bringing pragmatism and urgency to the work, and helping 3168 shape it from its very beginning, as well as being one of the best 3169 collaborators I had the pleasure of working with. 3171 James Manger for his creative ideas and always insightful feedback. 3172 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 3173 Marius Scurtescu, and Luke Shepard for their continued participation 3174 and valuable feedback. 3176 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 3177 support of this work for over three years. 3179 Authors' Addresses 3181 Eran Hammer (editor) 3183 Email: eran@hueniverse.com 3184 URI: http://hueniverse.com 3186 David Recordon 3187 Facebook 3189 Email: dr@fb.com 3190 URI: http://www.davidrecordon.com/ 3192 Dick Hardt 3193 Microsoft 3195 Email: dick.hardt@gmail.com 3196 URI: http://dickhardt.org/