idnits 2.17.1 draft-ietf-oauth-v2-24.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. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 8, 2012) is 4431 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) ** 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) == Outdated reference: A later version (-23) exists of draft-ietf-oauth-saml2-bearer-08 == Outdated reference: A later version (-23) exists of draft-ietf-oauth-v2-bearer-08 == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-00 == Outdated reference: A later version (-08) exists of draft-ietf-oauth-v2-threatmodel-00 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 9 errors (**), 0 flaws (~~), 6 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Hammer, Ed. 3 Internet-Draft 4 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: September 9, 2012 D. Hardt 7 Microsoft 8 March 8, 2012 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-24 13 Abstract 15 The OAuth 2.0 authorization protocol 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 September 9, 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 . . . . . . . . . . . . . . . . . . . . . . 6 60 1.3. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 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. Interoperability . . . . . . . . . . . . . . . . . . . . 12 69 1.8. Notational Conventions . . . . . . . . . . . . . . . . . 12 70 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 13 71 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 13 72 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 15 73 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 15 74 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 15 75 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 16 76 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 16 77 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 17 78 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 17 79 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 18 80 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 18 81 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 20 82 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 21 83 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 21 84 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 22 85 4.1. Authorization Code Grant . . . . . . . . . . . . . . . . 22 86 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 24 87 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 25 88 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 27 89 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 28 90 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 28 91 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 30 92 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 31 93 4.3. Resource Owner Password Credentials Grant . . . . . . . . 34 94 4.3.1. Authorization Request and Response . . . . . . . . . . 35 95 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 35 96 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 36 97 4.4. Client Credentials Grant . . . . . . . . . . . . . . . . 36 98 4.4.1. Authorization Request and Response . . . . . . . . . . 37 99 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 37 100 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 38 101 4.5. Extension Grants . . . . . . . . . . . . . . . . . . . . 38 102 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 39 103 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 39 104 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 41 105 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 42 106 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 43 107 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 44 108 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 45 109 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 45 110 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 45 111 8.3. Defining New Authorization Grant Types . . . . . . . . . 46 112 8.4. Defining New Authorization Endpoint Response Types . . . 46 113 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 46 114 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 47 115 10. Security Considerations . . . . . . . . . . . . . . . . . . . 48 116 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 48 117 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 49 118 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 49 119 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 50 120 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 51 121 10.6. Authorization Code Redirection URI Manipulation . . . . . 51 122 10.7. Resource Owner Password Credentials . . . . . . . . . . . 52 123 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 52 124 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 53 125 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 53 126 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 53 127 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 53 128 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 54 129 10.14. Code Injection and Input Validation . . . . . . . . . . . 55 130 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 55 131 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 132 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 56 133 11.1.1. Registration Template . . . . . . . . . . . . . . . . 56 134 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 57 135 11.2.1. Registration Template . . . . . . . . . . . . . . . . 58 136 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 58 137 11.3. The OAuth Authorization Endpoint Response Type 138 Registry . . . . . . . . . . . . . . . . . . . . . . . . 60 139 11.3.1. Registration Template . . . . . . . . . . . . . . . . 61 140 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 61 141 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 61 142 11.4.1. Registration Template . . . . . . . . . . . . . . . . 62 143 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 62 144 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 63 145 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 64 146 13.1. Normative References . . . . . . . . . . . . . . . . . . 64 147 13.2. Informative References . . . . . . . . . . . . . . . . . 65 148 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 66 150 1. Introduction 152 In the traditional client-server authentication model, the client 153 requests an access restricted resource (protected resource) on the 154 server by authenticating with the server using the resource owner's 155 credentials. In order to provide third-party applications access to 156 restricted resources, the resource owner shares its credentials with 157 the third-party. This creates several problems and limitations: 159 o Third-party applications are required to store the resource 160 owner's credentials for future use, typically a password in clear- 161 text. 162 o Servers are required to support password authentication, despite 163 the security weaknesses created by passwords. 164 o Third-party applications gain overly broad access to the resource 165 owner's protected resources, leaving resource owners without any 166 ability to restrict duration or access to a limited subset of 167 resources. 168 o Resource owners cannot revoke access to an individual third-party 169 without revoking access to all third-parties, and must do so by 170 changing their password. 171 o Compromise of any third-party application results in compromise of 172 the end-user's password and all of the data protected by that 173 password. 175 OAuth addresses these issues by introducing an authorization layer 176 and separating the role of the client from that of the resource 177 owner. In OAuth, the client requests access to resources controlled 178 by the resource owner and hosted by the resource server, and is 179 issued a different set of credentials than those of the resource 180 owner. 182 Instead of using the resource owner's credentials to access protected 183 resources, the client obtains an access token - a string denoting a 184 specific scope, lifetime, and other access attributes. Access tokens 185 are issued to third-party clients by an authorization server with the 186 approval of the resource owner. The client uses the access token to 187 access the protected resources hosted by the resource server. 189 For example, an end-user (resource owner) can grant a printing 190 service (client) access to her protected photos stored at a photo 191 sharing service (resource server), without sharing her username and 192 password with the printing service. Instead, she authenticates 193 directly with a server trusted by the photo sharing service 194 (authorization server) which issues the printing service delegation- 195 specific credentials (access token). 197 This specification is designed for use with HTTP [RFC2616]. The use 198 of OAuth with any transport protocol other than HTTP is undefined. 200 1.1. Roles 202 OAuth defines four roles: 204 resource owner 205 An entity capable of granting access to a protected resource. 206 When the resource owner is a person, it is refered to as an end- 207 user. 208 resource server 209 The server hosting the protected resources, capable of accepting 210 and responding to protected resource requests using access tokens. 211 client 212 An application making protected resource requests on behalf of the 213 resource owner and with its authorization. The term client does 214 not imply any particular implementation characteristics (e.g. 215 whether the application executes on a server, a desktop, or other 216 devices). 217 authorization server 218 The server issuing access tokens to the client after successfully 219 authenticating the resource owner and obtaining authorization. 221 The interaction between the authorization server and resource server 222 is beyond the scope of this specification. The authorization server 223 may be the same server as the resource server or a separate entity. 224 A single authorization server may issue access tokens accepted by 225 multiple resource servers. 227 1.2. Protocol Flow 228 +--------+ +---------------+ 229 | |--(A)- Authorization Request ->| Resource | 230 | | | Owner | 231 | |<-(B)-- Authorization Grant ---| | 232 | | +---------------+ 233 | | 234 | | +---------------+ 235 | |--(C)-- Authorization Grant -->| Authorization | 236 | Client | | Server | 237 | |<-(D)----- Access Token -------| | 238 | | +---------------+ 239 | | 240 | | +---------------+ 241 | |--(E)----- Access Token ------>| Resource | 242 | | | Server | 243 | |<-(F)--- Protected Resource ---| | 244 +--------+ +---------------+ 246 Figure 1: Abstract Protocol Flow 248 The abstract flow illustrated in Figure 1 describes the interaction 249 between the four roles and includes the following steps: 251 (A) The client requests authorization from the resource owner. The 252 authorization request can be made directly to the resource owner 253 (as shown), or preferably indirectly via the authorization 254 server as an intermediary. 255 (B) The client receives an authorization grant which is a credential 256 representing the resource owner's authorization, expressed using 257 one of four grant types defined in this specification or using 258 an extension grant type. The authorization grant type depends 259 on the method used by the client to request authorization and 260 the types supported by the authorization server. 261 (C) The client requests an access token by authenticating with the 262 authorization server and presenting the authorization grant. 263 (D) The authorization server authenticates the client and validates 264 the authorization grant, and if valid issues an access token. 265 (E) The client requests the protected resource from the resource 266 server and authenticates by presenting the access token. 267 (F) The resource server validates the access token, and if valid, 268 serves the request. 270 1.3. Authorization Grant 272 An authorization grant is a credential representing the resource 273 owner's authorization (to access its protected resources) used by the 274 client to obtain an access token. This specification defines four 275 grant types: authorization code, implicit, resource owner password 276 credentials, and client credentials, as well as an extensibility 277 mechanism for defining additional types. 279 1.3.1. Authorization Code 281 The authorization code is obtained by using an authorization server 282 as an intermediary between the client and resource owner. Instead of 283 requesting authorization directly from the resource owner, the client 284 directs the resource owner to an authorization server (via its user- 285 agent as defined in [RFC2616]), which in turn directs the resource 286 owner back to the client with the authorization code. 288 Before directing the resource owner back to the client with the 289 authorization code, the authorization server authenticates the 290 resource owner and obtains authorization. Because the resource owner 291 only authenticates with the authorization server, the resource 292 owner's credentials are never shared with the client. 294 The authorization code provides a few important security benefits 295 such as the ability to authenticate the client, and the transmission 296 of the access token directly to the client without passing it through 297 the resource owner's user-agent, potentially exposing it to others, 298 including the resource owner. 300 1.3.2. Implicit 302 The implicit grant is a simplified authorization code flow optimized 303 for clients implemented in a browser using a scripting language such 304 as JavaScript. In the implicit flow, instead of issuing the client 305 an authorization code, the client is issued an access token directly 306 (as the result of the resource owner authorization). The grant type 307 is implicit as no intermediate credentials (such as an authorization 308 code) are issued (and later used to obtain an access token). 310 When issuing an access token during the implicit grant flow, the 311 authorization server does not authenticate the client. In some 312 cases, the client identity can be verified via the redirection URI 313 used to deliver the access token to the client. The access token may 314 be exposed to the resource owner or other applications with access to 315 the resource owner's user-agent. 317 Implicit grants improve the responsiveness and efficiency of some 318 clients (such as a client implemented as an in-browser application) 319 since it reduces the number of round trips required to obtain an 320 access token. However, this convenience should be weighed against 321 the security implications of using implicit grants, especially when 322 the authorization code grant type is available. 324 1.3.3. Resource Owner Password Credentials 326 The resource owner password credentials (i.e. username and password) 327 can be used directly as an authorization grant to obtain an access 328 token. The credentials should only be used when there is a high 329 degree of trust between the resource owner and the client (e.g. the 330 client is part of the device operating system or a highly privileged 331 application), and when other authorization grant types are not 332 available (such as an authorization code). 334 Even though this grant type requires direct client access to the 335 resource owner credentials, the resource owner credentials are used 336 for a single request and are exchanged for an access token. This 337 grant type can eliminate the need for the client to store the 338 resource owner credentials for future use, by exchanging the 339 credentials with a long-lived access token or refresh token. 341 1.3.4. Client Credentials 343 The client credentials (or other forms of client authentication) can 344 be used as an authorization grant when the authorization scope is 345 limited to the protected resources under the control of the client, 346 or to protected resources previously arranged with the authorization 347 server. Client credentials are used as an authorization grant 348 typically when the client is acting on its own behalf (the client is 349 also the resource owner), or is requesting access to protected 350 resources based on an authorization previously arranged with the 351 authorization server. 353 1.4. Access Token 355 Access tokens are credentials used to access protected resources. An 356 access token is a string representing an authorization issued to the 357 client. The string is usually opaque to the client. Tokens 358 represent specific scopes and durations of access, granted by the 359 resource owner, and enforced by the resource server and authorization 360 server. 362 The token may denote an identifier used to retrieve the authorization 363 information, or self-contain the authorization information in a 364 verifiable manner (i.e. a token string consisting of some data and a 365 signature). Additional authentication credentials, which are beyond 366 the scope of this specification, may be required in order for the 367 client to use a token. 369 The access token provides an abstraction layer, replacing different 370 authorization constructs (e.g. username and password) with a single 371 token understood by the resource server. This abstraction enables 372 issuing access tokens more restrictive than the authorization grant 373 used to obtain them, as well as removing the resource server's need 374 to understand a wide range of authentication methods. 376 Access tokens can have different formats, structures, and methods of 377 utilization (e.g. cryptographic properties) based on the resource 378 server security requirements. Access token attributes and the 379 methods used to access protected resources are beyond the scope of 380 this specification and are defined by companion specifications. 382 1.5. Refresh Token 384 Refresh tokens are credentials used to obtain access tokens. Refresh 385 tokens are issued to the client by the authorization server and are 386 used to obtain a new access token when the current access token 387 becomes invalid or expires, or to obtain additional access tokens 388 with identical or narrower scope (access tokens may have a shorter 389 lifetime and fewer permissions than authorized by the resource 390 owner). Issuing a refresh token is optional at the discretion of the 391 authorization server. If the authorization server issues a refresh 392 token, it is included when issuing an access token. 394 A refresh token is a string representing the authorization granted to 395 the client by the resource owner. The string is usually opaque to 396 the client. The token denotes an identifier used to retrieve the 397 authorization information. Unlike access tokens, refresh tokens are 398 intended for use only with authorization servers and are never sent 399 to resource servers. 401 +--------+ +---------------+ 402 | |--(A)------- Authorization Grant --------->| | 403 | | | | 404 | |<-(B)----------- Access Token -------------| | 405 | | & Refresh Token | | 406 | | | | 407 | | +----------+ | | 408 | |--(C)---- Access Token ---->| | | | 409 | | | | | | 410 | |<-(D)- Protected Resource --| Resource | | Authorization | 411 | Client | | Server | | Server | 412 | |--(E)---- Access Token ---->| | | | 413 | | | | | | 414 | |<-(F)- Invalid Token Error -| | | | 415 | | +----------+ | | 416 | | | | 417 | |--(G)----------- Refresh Token ----------->| | 418 | | | | 419 | |<-(H)----------- Access Token -------------| | 420 +--------+ & Optional Refresh Token +---------------+ 422 Figure 2: Refreshing an Expired Access Token 424 The flow illustrated in Figure 2 includes the following steps: 426 (A) The client requests an access token by authenticating with the 427 authorization server, and presenting an authorization grant. 428 (B) The authorization server authenticates the client and validates 429 the authorization grant, and if valid issues an access token and 430 a refresh token. 431 (C) The client makes a protected resource request to the resource 432 server by presenting the access token. 433 (D) The resource server validates the access token, and if valid, 434 serves the request. 435 (E) Steps (C) and (D) repeat until the access token expires. If the 436 client knows the access token expired, it skips to step (G), 437 otherwise it makes another protected resource request. 438 (F) Since the access token is invalid, the resource server returns 439 an invalid token error. 440 (G) The client requests a new access token by authenticating with 441 the authorization server and presenting the refresh token. The 442 client authentication requirements are based on the client type 443 and on the authorization server policies. 445 (H) The authorization server authenticates the client and validates 446 the refresh token, and if valid issues a new access token (and 447 optionally, a new refresh token). 449 Steps C, D, E, and F are outside the scope of this specification as 450 described in Section 7. 452 1.6. TLS Version 454 Whenever TLS is required by this specification, the appropriate 455 version (or versions) of TLS will vary over time, based on the 456 widespread deployment and known security vulnerabilities. At the 457 time of this writing, TLS version 1.2 [RFC5246] is the most recent 458 version, but has a very limited deployment base and might not be 459 readily available for implementation. TLS version 1.0 [RFC2246] is 460 the most widely deployed version, and will provide the broadest 461 interoperability. 463 Implementations MAY also support additional transport-layer 464 mechanisms that meet their security requirements. 466 1.7. Interoperability 468 OAuth 2.0 provides a rich authorization framework with well-defined 469 security properties. However, as a rich and highly extensible 470 framework with many optional components, on its own, this 471 specification is likely to produce a wide range of non-interoperable 472 implementations. In addition, this specification leaves a few 473 required components partially or fully undefined (e.g. client 474 registration, authorization server capabilities, endpoint discovery). 476 This protocol was designed with the clear expectation that future 477 work will define prescriptive profiles and extensions necessary to 478 achieve full web-scale interoperability. 480 1.8. Notational Conventions 482 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 483 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 484 specification are to be interpreted as described in [RFC2119]. 486 This specification uses the Augmented Backus-Naur Form (ABNF) 487 notation of [RFC5234]. 489 Certain security-related terms are to be understood in the sense 490 defined in [RFC4949]. These terms include, but are not limited to, 491 'attack', 'authentication', 'authorization', 'certificate', 492 'confidentiality', 'credential', 'encryption', 'identity', 'sign', 493 'signature', 'trust', 'validate', and 'verify'. 495 Unless otherwise noted, all the protocol parameter names and values 496 are case sensitive. 498 2. Client Registration 500 Before initiating the protocol, the client registers with the 501 authorization server. The means through which the client registers 502 with the authorization server are beyond the scope of this 503 specification, but typically involve end-user interaction with an 504 HTML registration form. 506 Client registration does not require a direct interaction between the 507 client and the authorization server. When supported by the 508 authorization server, registration can rely on other means for 509 establishing trust and obtaining the required client properties (e.g. 510 redirection URI, client type). For example, registration can be 511 accomplished using a self-issued or third-party-issued assertion, or 512 by the authorization server performing client discovery using a 513 trusted channel. 515 When registering a client, the client developer: 517 o specifies the client type as described in Section 2.1, 518 o provides its client redirection URIs as described in 519 Section 3.1.2, and 520 o includes any other information required by the authorization 521 server (e.g. application name, website, description, logo image, 522 the acceptance of legal terms). 524 2.1. Client Types 526 OAuth defines two client types, based on their ability to 527 authenticate securely with the authorization server (i.e. ability to 528 maintain the confidentiality of their client credentials): 530 confidential 531 Clients capable of maintaining the confidentiality of their 532 credentials (e.g. client implemented on a secure server with 533 restricted access to the client credentials), or capable of secure 534 client authentication using other means. 535 public 536 Clients incapable of maintaining the confidentiality of their 537 credentials (e.g. clients executing on the device used by the 538 resource owner such as an installed native application or a web 539 browser-based application), and incapable of secure client 540 authentication via any other means. 542 The client type designation is based on the authorization server's 543 definition of secure authentication and its acceptable exposure 544 levels of client credentials. 546 The authorization server SHOULD NOT make assumptions about the client 547 type, nor accept the type information provided by the client 548 developer without first establishing trust. 550 A client application consisting of multiple components, each with its 551 own client type (e.g. a distributed client with both a confidential 552 server-based component and a public browser-based component), MUST 553 register each component separately as a different client to ensure 554 proper handling by the authorization server. The authorization 555 server MAY provider tools to manage such complex clients through a 556 single administration interface. 558 This specification has been designed around the following client 559 profiles: 561 web application 562 A web application is a confidential client running on a web 563 server. Resource owners access the client via an HTML user 564 interface rendered in a user-agent on the device used by the 565 resource owner. The client credentials as well as any access 566 token issued to the client are stored on the web server and are 567 not exposed to or accessible by the resource owner. 568 user-agent-based application 569 A user-agent-based application is a public client in which the 570 client code is downloaded from a web server and executes within a 571 user-agent (e.g. web browser) on the device used by the resource 572 owner. Protocol data and credentials are easily accessible (and 573 often visible) to the resource owner. Since such applications 574 reside within the user-agent, they can make seamless use of the 575 user-agent capabilities when requesting authorization. 576 native application 577 A native application is a public client installed and executed on 578 the device used by the resource owner. Protocol data and 579 credentials are accessible to the resource owner. It is assumed 580 that any client authentication credentials included in the 581 application can be extracted. On the other hand, dynamically 582 issued credentials such as access tokens or refresh tokens can 583 receive an acceptable level of protection. At a minimum, these 584 credentials are protected from hostile servers with which the 585 application may interact with. On some platforms these 586 credentials might be protected from other applications residing on 587 the same device. 589 2.2. Client Identifier 591 The authorization server issues the registered client a client 592 identifier - a unique string representing the registration 593 information provided by the client. The client identifier is not a 594 secret, it is exposed to the resource owner, and MUST NOT be used 595 alone for client authentication. 597 2.3. Client Authentication 599 If the client type is confidential, the client and authorization 600 server establish a client authentication method suitable for the 601 security requirements of the authorization server. The authorization 602 server MAY accept any form of client authentication meeting its 603 security requirements. 605 Confidential clients are typically issued (or establish) a set of 606 client credentials used for authenticating with the authorization 607 server (e.g. password, public/private key pair). 609 The authorization server MAY establish a client authentication method 610 with public clients. However, the authorization server MUST NOT rely 611 on public client authentication for the purpose of identifying the 612 client. 614 The client MUST NOT use more than one authentication method in each 615 request. 617 2.3.1. Client Password 619 Clients in possession of a client password MAY use the HTTP Basic 620 authentication scheme as defined in [RFC2617] to authenticate with 621 the authorization server. The client identifier is used as the 622 username, and the client password is used as the password. The 623 authorization server MUST support the HTTP Basic authentication 624 scheme for authenticating clients which were issued a client 625 password. 627 For example (extra line breaks are for display purposes only): 629 Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 631 Alternatively, the authorization server MAY support including the 632 client credentials in the request body using the following 633 parameters: 635 client_id 636 REQUIRED. The client identifier issued to the client during 637 the registration process described by Section 2.2. 638 client_secret 639 REQUIRED. The client secret. The client MAY omit the 640 parameter if the client secret is an empty string. 642 Including the client credentials in the request body using the two 643 parameters is NOT RECOMMENDED, and should be limited to clients 644 unable to directly utilize the HTTP Basic authentication scheme (or 645 other password-based HTTP authentication schemes). The parameters 646 can only be transmitted in the request body and MUST NOT be included 647 in the request URI. 649 For example, requesting to refresh an access token (Section 6) using 650 the body parameters (extra line breaks are for display purposes 651 only): 653 POST /token HTTP/1.1 654 Host: server.example.com 655 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 657 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 658 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 660 The authorization server MUST require TLS as described in Section 1.6 661 when sending requests using password authentication. 663 Since this client authentication method involves a password, the 664 authorization server MUST protect any endpoint utilizing it against 665 brute force attacks. 667 2.3.2. Other Authentication Methods 669 The authorization server MAY support any suitable HTTP authentication 670 scheme matching its security requirements. When using other 671 authentication methods, the authorization server MUST define a 672 mapping between the client identifier (registration record) and 673 authentication scheme. 675 2.4. Unregistered Clients 677 This specification does not exclude the use of unregistered clients. 678 However, the use with such clients is beyond the scope of this 679 specification, and requires additional security analysis and review 680 of its interoperability impact. 682 3. Protocol Endpoints 684 The authorization process utilizes two authorization server endpoints 685 (HTTP resources): 687 o Authorization endpoint - used by the client to obtain 688 authorization from the resource owner via user-agent redirection. 689 o Token endpoint - used by the client to exchange an authorization 690 grant for an access token, typically with client authentication. 692 As well as one client endpoint: 694 o Redirection endpoint - used by the authorization server to return 695 authorization credentials responses to the client via the resource 696 owner user-agent. 698 Not every authorization grant type utilizes both endpoints. 699 Extension grant types MAY define additional endpoints as needed. 701 3.1. Authorization Endpoint 703 The authorization endpoint is used to interact with the resource 704 owner and obtain an authorization grant. The authorization server 705 MUST first verify the identity of the resource owner. The way in 706 which the authorization server authenticates the resource owner (e.g. 707 username and password login, session cookies) is beyond the scope of 708 this specification. 710 The means through which the client obtains the location of the 711 authorization endpoint are beyond the scope of this specification, 712 but the location is typically provided in the service documentation. 714 The endpoint URI MAY include an "application/x-www-form-urlencoded" 715 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 716 section 3.4), which MUST be retained when adding additional query 717 parameters. The endpoint URI MUST NOT include a fragment component. 719 Since requests to the authorization endpoint result in user 720 authentication and the transmission of clear-text credentials (in the 721 HTTP response), the authorization server MUST require TLS as 722 described in Section 1.6 when sending requests to the authorization 723 endpoint. 725 The authorization server MUST support the use of the HTTP "GET" 726 method [RFC2616] for the authorization endpoint, and MAY support the 727 use of the "POST" method as well. 729 Parameters sent without a value MUST be treated as if they were 730 omitted from the request. The authorization server MUST ignore 731 unrecognized request parameters. Request and response parameters 732 MUST NOT be included more than once. 734 3.1.1. Response Type 736 The authorization endpoint is used by the authorization code grant 737 type and implicit grant type flows. The client informs the 738 authorization server of the desired grant type using the following 739 parameter: 741 response_type 742 REQUIRED. The value MUST be one of "code" for requesting an 743 authorization code as described by Section 4.1.1, "token" for 744 requesting an access token (implicit grant) as described by 745 Section 4.2.1, or a registered extension value as described by 746 Section 8.4. 748 Extension response types MAY contain a space-delimited (%x20) list of 749 values, where the order of values does not matter (e.g. response type 750 "a b" is the same as "b a"). The meaning of such composite response 751 types is defined by their respective specifications. 753 If an authorization request is missing the "response_type" parameter, 754 or if the response type is not understood, the authorization server 755 MUST return an error response as described in Section 4.1.2.1. 757 3.1.2. Redirection Endpoint 759 After completing its interaction with the resource owner, the 760 authorization server directs the resource owner's user-agent back to 761 the client. The authorization server redirects the user-agent to the 762 client's redirection endpoint previously established with the 763 authorization server during the client registration process or when 764 making the authorization request. 766 The redirection endpoint URI MUST be an absolute URI as defined by 767 [RFC3986] section 4.3. The endpoint URI MAY include an 768 "application/x-www-form-urlencoded" formatted 769 ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), 770 which MUST be retained when adding additional query parameters. The 771 endpoint URI MUST NOT include a fragment component. 773 3.1.2.1. Endpoint Request Confidentiality 775 The redirection endpoint SHOULD require the use of TLS as described 776 in Section 1.6 when the requested response type is "code" or "token", 777 or when the redirection request will result in the transmission of 778 sensitive credentials over an open network. This specification does 779 not mandate the use of TLS because at the time of this writing, 780 requiring clients to deploy TLS is a significant hurdle for many 781 client developers. If TLS is not available, the authorization server 782 SHOULD warn the resource owner about the insecure endpoint prior to 783 redirection. 785 Lack of transport-layer security can have a severe impact on the 786 security of the client and the protected resources it is authorized 787 to access. The use of transport-layer security is particularly 788 critical when the authorization process is used as a form of 789 delegated end-user authentication by the client (e.g. third-party 790 sign-in service). 792 3.1.2.2. Registration Requirements 794 The authorization server MUST require the following clients to 795 register their redirection endpoint: 797 o Public clients. 798 o Confidential clients utilizing the implicit grant type. 800 The authorization server SHOULD require all clients to register their 801 redirection endpoint prior to utilizing the authorization endpoint 803 The authorization server SHOULD require the client to provide the 804 complete redirection URI (the client MAY use the "state" request 805 parameter to achieve per-request customization). If requiring the 806 registration of the complete redirection URI is not possible, the 807 authorization server SHOULD require the registration of the URI 808 scheme, authority, and path (allowing the client to dynamically vary 809 only the query component of the redirection URI when requesting 810 authorization). 812 The authorization server MAY allow the client to register multiple 813 redirection endpoints. 815 Lack of a redirection URI registration requirement can enable an 816 attacker to use the authorization endpoint as open redirector as 817 described in Section 10.15. 819 3.1.2.3. Dynamic Configuration 821 If multiple redirection URIs have been registered, if only part of 822 the redirection URI has been registered, or if no redirection URI has 823 been registered, the client MUST include a redirection URI with the 824 authorization request using the "redirect_uri" request parameter. 826 When a redirection URI is included in an authorization request, the 827 authorization server MUST compare and match the value received 828 against at least one of the registered redirection URIs (or URI 829 components) as defined in [RFC3986] section 6, if any redirection 830 URIs were registered. If the client registration included the full 831 redirection URI, the authorization server MUST compare the two URIs 832 using simple string comparison as defined in [RFC3986] section 6.2.1. 834 3.1.2.4. Invalid Endpoint 836 If an authorization request fails validation due to a missing, 837 invalid, or mismatching redirection URI, the authorization server 838 SHOULD inform the resource owner of the error, and MUST NOT 839 automatically redirect the user-agent to the invalid redirection URI. 841 3.1.2.5. Endpoint Content 843 The redirection request to the client's endpoint typically results in 844 an HTML document response, processed by the user-agent. If the HTML 845 response is served directly as the result of the redirection request, 846 any script included in the HTML document will execute with full 847 access to the redirection URI and the credentials it contains. 849 The client SHOULD NOT include any third-party scripts (e.g. third- 850 party analytics, social plug-ins, ad networks) in the redirection 851 endpoint response. Instead, it SHOULD extract the credentials from 852 the URI and redirect the user-agent again to another endpoint without 853 exposing the credentials (in the URI or elsewhere). If third-party 854 scripts are included, the client MUST NOT ensure that its own scripts 855 (used to extract and remove the credentials from the URI) will 856 execute first. 858 3.2. Token Endpoint 860 The token endpoint is used by the client to obtain an access token by 861 presenting its authorization grant or refresh token. The token 862 endpoint is used with every authorization grant except for the 863 implicit grant type (since an access token is issued directly). 865 The means through which the client obtains the location of the token 866 endpoint are beyond the scope of this specification but is typically 867 provided in the service documentation. 869 The endpoint URI MAY include an "application/x-www-form-urlencoded" 870 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 871 section 3.4), which MUST be retained when adding additional query 872 parameters. The endpoint URI MUST NOT include a fragment component. 874 Since requests to the token endpoint result in the transmission of 875 clear-text credentials (in the HTTP request and response), the 876 authorization server MUST require TLS as described in Section 1.6 877 when sending requests to the token endpoint. 879 The client MUST use the HTTP "POST" method when making access token 880 requests. 882 Parameters sent without a value MUST be treated as if they were 883 omitted from the request. The authorization server MUST ignore 884 unrecognized request parameters. Request and response parameters 885 MUST NOT be included more than once. 887 3.2.1. Client Authentication 889 Confidential clients or other clients issued client credentials MUST 890 authenticate with the authorization server as described in 891 Section 2.3 when making requests to the token endpoint. Client 892 authentication is used for: 894 o Enforcing the binding of refresh tokens and authorization codes to 895 the client they were issued to. Client authentication is critical 896 when an authorization code is transmitted to the redirection 897 endpoint over an insecure channel, or when the redirection URI has 898 not been registered in full. 899 o Recovering from a compromised client by disabling the client or 900 changing its credentials, thus preventing an attacker from abusing 901 stolen refresh tokens. Changing a single set of client 902 credentials is significantly faster than revoking an entire set of 903 refresh tokens. 904 o Implementing authentication management best practices which 905 require periodic credential rotation. Rotation of an entire set 906 of refresh tokens can be challenging, while rotation of a single 907 set of client credentials is significantly easier. 909 A public client that was not issued a client password MAY use the 910 "client_id" request parameter to identify itself when sending 911 requests to the token endpoint (e.g. for the purpose of providing 912 end-user context, client usage statistics). 914 3.3. Access Token Scope 916 The authorization and token endpoints allow the client to specify the 917 scope of the access request using the "scope" request parameter. In 918 turn, the authorization server uses the "scope" response parameter to 919 inform the client of the scope of the access token issued. 921 The value of the scope parameter is expressed as a list of space- 922 delimited, case sensitive strings. The strings are defined by the 923 authorization server. If the value contains multiple space-delimited 924 strings, their order does not matter, and each string adds an 925 additional access range to the requested scope. 927 scope = scope-token *( SP scope-token ) 928 scope-token = 1*( %x21 / %x23-5B / %x5D-7E ) 930 The authorization server MAY fully or partially ignore the scope 931 requested by the client based on the authorization server policy or 932 the resource owner's instructions. If the issued access token scope 933 is different from the one requested by the client, the authorization 934 server MUST include the "scope" response parameter to inform the 935 client of the actual scope granted. 937 If the client omits the scope parameter when requesting 938 authorization, the authorization server MUST either process the 939 request using a pre-defined default value, or fail the request 940 indicating an invalid scope. The authorization server SHOULD 941 document its scope requirements and default value (if defined). 943 4. Obtaining Authorization 945 To request an access token, the client obtains authorization from the 946 resource owner. The authorization is expressed in the form of an 947 authorization grant which the client uses to request the access 948 token. OAuth defines four grant types: authorization code, implicit, 949 resource owner password credentials, and client credentials. It also 950 provides an extension mechanism for defining additional grant types. 952 4.1. Authorization Code Grant 954 The authorization code grant type is used to obtain both access 955 tokens and refresh tokens and is optimized for confidential clients. 956 As a redirection-based flow, the client must be capable of 957 interacting with the resource owner's user-agent (typically a web 958 browser) and capable of receiving incoming requests (via redirection) 959 from the authorization server. 961 +----------+ 962 | resource | 963 | owner | 964 | | 965 +----------+ 966 ^ 967 | 968 (B) 969 +----|-----+ Client Identifier +---------------+ 970 | -+----(A)-- & Redirection URI ---->| | 971 | User- | | Authorization | 972 | Agent -+----(B)-- User authenticates --->| Server | 973 | | | | 974 | -+----(C)-- Authorization Code ---<| | 975 +-|----|---+ +---------------+ 976 | | ^ v 977 (A) (C) | | 978 | | | | 979 ^ v | | 980 +---------+ | | 981 | |>---(D)-- Authorization Code ---------' | 982 | Client | & Redirection URI | 983 | | | 984 | |<---(E)----- Access Token -------------------' 985 +---------+ (w/ Optional Refresh Token) 987 Note: The lines illustrating steps A, B, and C are broken into two 988 parts as they pass through the user-agent. 990 Figure 3: Authorization Code Flow 992 The flow illustrated in Figure 3 includes the following steps: 994 (A) The client initiates the flow by directing the resource owner's 995 user-agent to the authorization endpoint. The client includes 996 its client identifier, requested scope, local state, and a 997 redirection URI to which the authorization server will send the 998 user-agent back once access is granted (or denied). 999 (B) The authorization server authenticates the resource owner (via 1000 the user-agent) and establishes whether the resource owner 1001 grants or denies the client's access request. 1002 (C) Assuming the resource owner grants access, the authorization 1003 server redirects the user-agent back to the client using the 1004 redirection URI provided earlier (in the request or during 1005 client registration). The redirection URI includes an 1006 authorization code and any local state provided by the client 1007 earlier. 1009 (D) The client requests an access token from the authorization 1010 server's token endpoint by including the authorization code 1011 received in the previous step. When making the request, the 1012 client authenticates with the authorization server. The client 1013 includes the redirection URI used to obtain the authorization 1014 code for verification. 1015 (E) The authorization server authenticates the client, validates the 1016 authorization code, and ensures the redirection URI received 1017 matches the URI used to redirect the client in step (C). If 1018 valid, the authorization server responds back with an access 1019 token and optionally, a refresh token. 1021 4.1.1. Authorization Request 1023 The client constructs the request URI by adding the following 1024 parameters to the query component of the authorization endpoint URI 1025 using the "application/x-www-form-urlencoded" format as defined by 1026 [W3C.REC-html401-19991224]: 1028 response_type 1029 REQUIRED. Value MUST be set to "code". 1030 client_id 1031 REQUIRED. The client identifier as described in Section 2.2. 1032 redirect_uri 1033 OPTIONAL. As described in Section 3.1.2. 1034 scope 1035 OPTIONAL. The scope of the access request as described by 1036 Section 3.3. 1037 state 1038 RECOMMENDED. An opaque value used by the client to maintain 1039 state between the request and callback. The authorization 1040 server includes this value when redirecting the user-agent back 1041 to the client. The parameter SHOULD be used for preventing 1042 cross-site request forgery as described in Section 10.12. 1044 The client directs the resource owner to the constructed URI using an 1045 HTTP redirection response, or by other means available to it via the 1046 user-agent. 1048 For example, the client directs the user-agent to make the following 1049 HTTP request using TLS (extra line breaks are for display purposes 1050 only): 1052 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 1053 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1054 Host: server.example.com 1056 The authorization server validates the request to ensure all required 1057 parameters are present and valid. If the request is valid, the 1058 authorization server authenticates the resource owner and obtains an 1059 authorization decision (by asking the resource owner or by 1060 establishing approval via other means). 1062 When a decision is established, the authorization server directs the 1063 user-agent to the provided client redirection URI using an HTTP 1064 redirection response, or by other means available to it via the user- 1065 agent. 1067 4.1.2. Authorization Response 1069 If the resource owner grants the access request, the authorization 1070 server issues an authorization code and delivers it to the client by 1071 adding the following parameters to the query component of the 1072 redirection URI using the "application/x-www-form-urlencoded" format: 1074 code 1075 REQUIRED. The authorization code generated by the 1076 authorization server. The authorization code MUST expire 1077 shortly after it is issued to mitigate the risk of leaks. A 1078 maximum authorization code lifetime of 10 minutes is 1079 RECOMMENDED. The client MUST NOT use the authorization code 1080 more than once. If an authorization code is used more than 1081 once, the authorization server MUST deny the request and SHOULD 1082 revoke (when possible) all tokens previously issued based on 1083 that authorization code. The authorization code is bound to 1084 the client identifier and redirection URI. 1085 state 1086 REQUIRED if the "state" parameter was present in the client 1087 authorization request. The exact value received from the 1088 client. 1090 For example, the authorization server redirects the user-agent by 1091 sending the following HTTP response: 1093 HTTP/1.1 302 Found 1094 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1095 &state=xyz 1097 The client MUST ignore unrecognized response parameters. The 1098 authorization code string size is left undefined by this 1099 specification. The client should avoid making assumptions about code 1100 value sizes. The authorization server should document the size of 1101 any value it issues. 1103 4.1.2.1. Error Response 1105 If the request fails due to a missing, invalid, or mismatching 1106 redirection URI, or if the client identifier is missing or invalid, 1107 the authorization server SHOULD inform the resource owner of the 1108 error, and MUST NOT automatically redirect the user-agent to the 1109 invalid redirection URI. 1111 If the resource owner denies the access request or if the request 1112 fails for reasons other than a missing or invalid redirection URI, 1113 the authorization server informs the client by adding the following 1114 parameters to the query component of the redirection URI using the 1115 "application/x-www-form-urlencoded" format: 1117 error 1118 REQUIRED. A single error code from the following: 1119 invalid_request 1120 The request is missing a required parameter, includes an 1121 invalid parameter value, or is otherwise malformed. 1122 unauthorized_client 1123 The client is not authorized to request an authorization 1124 code using this method. 1125 access_denied 1126 The resource owner or authorization server denied the 1127 request. 1128 unsupported_response_type 1129 The authorization server does not support obtaining an 1130 authorization code using this method. 1131 invalid_scope 1132 The requested scope is invalid, unknown, or malformed. 1133 server_error 1134 The authorization server encountered an unexpected 1135 condition which prevented it from fulfilling the request. 1136 temporarily_unavailable 1137 The authorization server is currently unable to handle 1138 the request due to a temporary overloading or maintenance 1139 of the server. 1140 error_description 1141 OPTIONAL. A human-readable UTF-8 encoded text providing 1142 additional information, used to assist the client developer in 1143 understanding the error that occurred. 1144 error_uri 1145 OPTIONAL. A URI identifying a human-readable web page with 1146 information about the error, used to provide the client 1147 developer with additional information about the error. 1149 state 1150 REQUIRED if a "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?error=access_denied&state=xyz 1160 4.1.3. Access Token Request 1162 The client makes a request to the token endpoint by adding the 1163 following parameters using the "application/x-www-form-urlencoded" 1164 format in the HTTP request entity-body: 1166 grant_type 1167 REQUIRED. Value MUST be set to "authorization_code". 1168 code 1169 REQUIRED. The authorization code received from the 1170 authorization server. 1171 redirect_uri 1172 REQUIRED, if the "redirect_uri" parameter was included in the 1173 authorization request as described in Section 4.1.1, and their 1174 values MUST be identical. 1176 If the client type is confidential or the client was issued client 1177 credentials (or assigned other authentication requirements), the 1178 client MUST authenticate with the authorization server as described 1179 in Section 3.2.1. 1181 For example, the client makes the following HTTP request using TLS 1182 (extra line breaks are for display purposes only): 1184 POST /token HTTP/1.1 1185 Host: server.example.com 1186 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1187 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1189 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1190 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1192 The authorization server MUST: 1194 o require client authentication for confidential clients or for any 1195 client that was issued client credentials (or with other 1196 authentication requirements), 1197 o authenticate the client if client authentication is included and 1198 ensure the authorization code was issued to the authenticated 1199 client, 1200 o verify that the authorization code is valid, and 1201 o ensure that the "redirect_uri" parameter is present if the 1202 "redirect_uri" parameter was included in the initial authorization 1203 request as described in Section 4.1.1, and if included ensure 1204 their values are identical. 1206 4.1.4. Access Token Response 1208 If the access token request is valid and authorized, the 1209 authorization server issues an access token and optional refresh 1210 token as described in Section 5.1. If the request client 1211 authentication failed or is invalid, the authorization server returns 1212 an error response as described in Section 5.2. 1214 An example successful response: 1216 HTTP/1.1 200 OK 1217 Content-Type: application/json;charset=UTF-8 1218 Cache-Control: no-store 1219 Pragma: no-cache 1221 { 1222 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1223 "token_type":"example", 1224 "expires_in":3600, 1225 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1226 "example_parameter":"example_value" 1227 } 1229 4.2. Implicit Grant 1231 The implicit grant type is used to obtain access tokens (it does not 1232 support the issuance of refresh tokens) and is optimized for public 1233 clients known to operate a particular redirection URI. These clients 1234 are typically implemented in a browser using a scripting language 1235 such as JavaScript. 1237 As a redirection-based flow, the client must be capable of 1238 interacting with the resource owner's user-agent (typically a web 1239 browser) and capable of receiving incoming requests (via redirection) 1240 from the authorization server. 1242 Unlike the authorization code grant type in which the client makes 1243 separate requests for authorization and access token, the client 1244 receives the access token as the result of the authorization request. 1246 The implicit grant type does not include client authentication, and 1247 relies on the presence of the resource owner and the registration of 1248 the redirection URI. Because the access token is encoded into the 1249 redirection URI, it may be exposed to the resource owner and other 1250 applications residing on the same device. 1252 +----------+ 1253 | Resource | 1254 | Owner | 1255 | | 1256 +----------+ 1257 ^ 1258 | 1259 (B) 1260 +----|-----+ Client Identifier +---------------+ 1261 | -+----(A)-- & Redirection URI --->| | 1262 | User- | | Authorization | 1263 | Agent -|----(B)-- User authenticates -->| Server | 1264 | | | | 1265 | |<---(C)--- Redirection URI ----<| | 1266 | | with Access Token +---------------+ 1267 | | in Fragment 1268 | | +---------------+ 1269 | |----(D)--- Redirection URI ---->| Web-Hosted | 1270 | | without Fragment | Client | 1271 | | | Resource | 1272 | (F) |<---(E)------- Script ---------<| | 1273 | | +---------------+ 1274 +-|--------+ 1275 | | 1276 (A) (G) Access Token 1277 | | 1278 ^ v 1279 +---------+ 1280 | | 1281 | Client | 1282 | | 1283 +---------+ 1285 Note: The lines illustrating steps A and B are broken into two parts 1286 as they pass through the user-agent. 1288 Figure 4: Implicit Grant Flow 1290 The flow illustrated in Figure 4 includes the following steps: 1292 (A) The client initiates the flow by directing the resource owner's 1293 user-agent to the authorization endpoint. The client includes 1294 its client identifier, requested scope, local state, and a 1295 redirection URI to which the authorization server will send the 1296 user-agent back once access is granted (or denied). 1297 (B) The authorization server authenticates the resource owner (via 1298 the user-agent) and establishes whether the resource owner 1299 grants or denies the client's access request. 1300 (C) Assuming the resource owner grants access, the authorization 1301 server redirects the user-agent back to the client using the 1302 redirection URI provided earlier. The redirection URI includes 1303 the access token in the URI fragment. 1304 (D) The user-agent follows the redirection instructions by making a 1305 request to the web-hosted client resource (which does not 1306 include the fragment per [RFC2616]). The user-agent retains the 1307 fragment information locally. 1308 (E) The web-hosted client resource returns a web page (typically an 1309 HTML document with an embedded script) capable of accessing the 1310 full redirection URI including the fragment retained by the 1311 user-agent, and extracting the access token (and other 1312 parameters) contained in the fragment. 1313 (F) The user-agent executes the script provided by the web-hosted 1314 client resource locally, which extracts the access token and 1315 passes it to the client. 1317 4.2.1. Authorization Request 1319 The client constructs the request URI by adding the following 1320 parameters to the query component of the authorization endpoint URI 1321 using the "application/x-www-form-urlencoded" format: 1323 response_type 1324 REQUIRED. Value MUST be set to "token". 1325 client_id 1326 REQUIRED. The client identifier as described in Section 2.2. 1327 redirect_uri 1328 OPTIONAL. As described in Section 3.1.2. 1329 scope 1330 OPTIONAL. The scope of the access request as described by 1331 Section 3.3. 1333 state 1334 RECOMMENDED. An opaque value used by the client to maintain 1335 state between the request and callback. The authorization 1336 server includes this value when redirecting the user-agent back 1337 to the client. The parameter SHOULD be used for preventing 1338 cross-site request forgery as described in Section 10.12. 1340 The client directs the resource owner to the constructed URI using an 1341 HTTP redirection response, or by other means available to it via the 1342 user-agent. 1344 For example, the client directs the user-agent to make the following 1345 HTTP request using TLS (extra line breaks are for display purposes 1346 only): 1348 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1349 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1350 Host: server.example.com 1352 The authorization server validates the request to ensure all required 1353 parameters are present and valid. The authorization server MUST 1354 verify that the redirection URI to which it will redirect the access 1355 token matches a redirection URI registered by the client as described 1356 in Section 3.1.2. 1358 If the request is valid, the authorization server authenticates the 1359 resource owner and obtains an authorization decision (by asking the 1360 resource owner or by establishing approval via other means). 1362 When a decision is established, the authorization server directs the 1363 user-agent to the provided client redirection URI using an HTTP 1364 redirection response, or by other means available to it via the user- 1365 agent. 1367 4.2.2. Access Token Response 1369 If the resource owner grants the access request, the authorization 1370 server issues an access token and delivers it to the client by adding 1371 the following parameters to the fragment component of the redirection 1372 URI using the "application/x-www-form-urlencoded" format: 1374 access_token 1375 REQUIRED. The access token issued by the authorization server. 1377 token_type 1378 REQUIRED. The type of the token issued as described in 1379 Section 7.1. Value is case insensitive. 1380 expires_in 1381 RECOMMENDED. The lifetime in seconds of the access token. For 1382 example, the value "3600" denotes that the access token will 1383 expire in one hour from the time the response was generated. 1384 If omitted, the authorization server SHOULD provide the 1385 expiration time via other means or document the default value. 1386 scope 1387 OPTIONAL, if identical to the scope requested by the client, 1388 otherwise REQUIRED. The scope of the access token as described 1389 by Section 3.3. 1390 state 1391 REQUIRED if the "state" parameter was present in the client 1392 authorization request. The exact value received from the 1393 client. 1395 The authorization server MUST NOT issue a refresh token. 1397 For example, the authorization server redirects the user-agent by 1398 sending the following HTTP response (URI extra line breaks are for 1399 display purposes only): 1401 HTTP/1.1 302 Found 1402 Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA 1403 &state=xyz&token_type=example&expires_in=3600 1405 Developers should note that some user-agents do not support the 1406 inclusion of a fragment component in the HTTP "Location" response 1407 header field. Such clients will require using other methods for 1408 redirecting the client than a 3xx redirection response. For example, 1409 returning an HTML page which includes a 'continue' button with an 1410 action linked to the redirection URI. 1412 The client MUST ignore unrecognized response parameters. The access 1413 token string size is left undefined by this specification. The 1414 client should avoid making assumptions about value sizes. The 1415 authorization server should document the size of any value it issues. 1417 4.2.2.1. Error Response 1419 If the request fails due to a missing, invalid, or mismatching 1420 redirection URI, or if the client identifier is missing or invalid, 1421 the authorization server SHOULD inform the resource owner of the 1422 error, and MUST NOT automatically redirect the user-agent to the 1423 invalid redirection URI. 1425 If the resource owner denies the access request or if the request 1426 fails for reasons other than a missing or invalid redirection URI, 1427 the authorization server informs the client by adding the following 1428 parameters to the fragment component of the redirection URI using the 1429 "application/x-www-form-urlencoded" format: 1431 error 1432 REQUIRED. A single error code from the following: 1433 invalid_request 1434 The request is missing a required parameter, includes an 1435 invalid parameter value, or is otherwise malformed. 1436 unauthorized_client 1437 The client is not authorized to request an access token 1438 using this method. 1439 access_denied 1440 The resource owner or authorization server denied the 1441 request. 1442 unsupported_response_type 1443 The authorization server does not support obtaining an 1444 access token using this method. 1445 invalid_scope 1446 The requested scope is invalid, unknown, or malformed. 1447 server_error 1448 The authorization server encountered an unexpected 1449 condition which prevented it from fulfilling the request. 1450 temporarily_unavailable 1451 The authorization server is currently unable to handle 1452 the request due to a temporary overloading or maintenance 1453 of the server. 1454 error_description 1455 OPTIONAL. A human-readable UTF-8 encoded text providing 1456 additional information, used to assist the client developer in 1457 understanding the error that occurred. 1458 error_uri 1459 OPTIONAL. A URI identifying a human-readable web page with 1460 information about the error, used to provide the client 1461 developer with additional information about the error. 1462 state 1463 REQUIRED if a "state" parameter was present in the client 1464 authorization request. The exact value received from the 1465 client. 1467 For example, the authorization server redirects the user-agent by 1468 sending the following HTTP response: 1470 HTTP/1.1 302 Found 1471 Location: https://client.example.com/cb#error=access_denied&state=xyz 1473 4.3. Resource Owner Password Credentials Grant 1475 The resource owner password credentials grant type is suitable in 1476 cases where the resource owner has a trust relationship with the 1477 client, such as the device operating system or a highly privileged 1478 application. The authorization server should take special care when 1479 enabling this grant type, and only allow it when other flows are not 1480 viable. 1482 The grant type is suitable for clients capable of obtaining the 1483 resource owner's credentials (username and password, typically using 1484 an interactive form). It is also used to migrate existing clients 1485 using direct authentication schemes such as HTTP Basic or Digest 1486 authentication to OAuth by converting the stored credentials to an 1487 access token. 1489 +----------+ 1490 | Resource | 1491 | Owner | 1492 | | 1493 +----------+ 1494 v 1495 | Resource Owner 1496 (A) Password Credentials 1497 | 1498 v 1499 +---------+ +---------------+ 1500 | |>--(B)---- Resource Owner ------->| | 1501 | | Password Credentials | Authorization | 1502 | Client | | Server | 1503 | |<--(C)---- Access Token ---------<| | 1504 | | (w/ Optional Refresh Token) | | 1505 +---------+ +---------------+ 1507 Figure 5: Resource Owner Password Credentials Flow 1509 The flow illustrated in Figure 5 includes the following steps: 1511 (A) The resource owner provides the client with its username and 1512 password. 1513 (B) The client requests an access token from the authorization 1514 server's token endpoint by including the credentials received 1515 from the resource owner. When making the request, the client 1516 authenticates with the authorization server. 1517 (C) The authorization server authenticates the client and validates 1518 the resource owner credentials, and if valid issues an access 1519 token. 1521 4.3.1. Authorization Request and Response 1523 The method through which the client obtains the resource owner 1524 credentials is beyond the scope of this specification. The client 1525 MUST discard the credentials once an access token has been obtained. 1527 4.3.2. Access Token Request 1529 The client makes a request to the token endpoint by adding the 1530 following parameters using the "application/x-www-form-urlencoded" 1531 format in the HTTP request entity-body: 1533 grant_type 1534 REQUIRED. Value MUST be set to "password". 1535 username 1536 REQUIRED. The resource owner username, encoded as UTF-8. 1537 password 1538 REQUIRED. The resource owner password, encoded as UTF-8. 1539 scope 1540 OPTIONAL. The scope of the access request as described by 1541 Section 3.3. 1543 If the client type is confidential or the client was issued client 1544 credentials (or assigned other authentication requirements), the 1545 client MUST authenticate with the authorization server as described 1546 in Section 3.2.1. 1548 For example, the client makes the following HTTP request using 1549 transport-layer security (extra line breaks are for display purposes 1550 only): 1552 POST /token HTTP/1.1 1553 Host: server.example.com 1554 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1555 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1557 grant_type=password&username=johndoe&password=A3ddj3w 1559 The authorization server MUST: 1561 o require client authentication for confidential clients or for any 1562 client that was issued client credentials (or with other 1563 authentication requirements), 1564 o authenticate the client if client authentication is included, and 1565 o validate the resource owner password credentials. 1567 Since this access token request utilizes the resource owner's 1568 password, the authorization server MUST protect the endpoint against 1569 brute force attacks (e.g. using rate-limitation or generating 1570 alerts). 1572 4.3.3. Access Token Response 1574 If the access token request is valid and authorized, the 1575 authorization server issues an access token and optional refresh 1576 token as described in Section 5.1. If the request failed client 1577 authentication or is invalid, the authorization server returns an 1578 error response as described in Section 5.2. 1580 An example successful response: 1582 HTTP/1.1 200 OK 1583 Content-Type: application/json;charset=UTF-8 1584 Cache-Control: no-store 1585 Pragma: no-cache 1587 { 1588 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1589 "token_type":"example", 1590 "expires_in":3600, 1591 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1592 "example_parameter":"example_value" 1593 } 1595 4.4. Client Credentials Grant 1597 The client can request an access token using only its client 1598 credentials (or other supported means of authentication) when the 1599 client is requesting access to the protected resources under its 1600 control, or those of another resource owner which has been previously 1601 arranged with the authorization server (the method of which is beyond 1602 the scope of this specification). 1604 The client credentials grant type MUST only be used by confidential 1605 clients. 1607 +---------+ +---------------+ 1608 | | | | 1609 | |>--(A)- Client Authentication --->| Authorization | 1610 | Client | | Server | 1611 | |<--(B)---- Access Token ---------<| | 1612 | | | | 1613 +---------+ +---------------+ 1615 Figure 6: Client Credentials Flow 1617 The flow illustrated in Figure 6 includes the following steps: 1619 (A) The client authenticates with the authorization server and 1620 requests an access token from the token endpoint. 1621 (B) The authorization server authenticates the client, and if valid 1622 issues an access token. 1624 4.4.1. Authorization Request and Response 1626 Since the client authentication is used as the authorization grant, 1627 no additional authorization request is needed. 1629 4.4.2. Access Token Request 1631 The client makes a request to the token endpoint by adding the 1632 following parameters using the "application/x-www-form-urlencoded" 1633 format in the HTTP request entity-body: 1635 grant_type 1636 REQUIRED. Value MUST be set to "client_credentials". 1637 scope 1638 OPTIONAL. The scope of the access request as described by 1639 Section 3.3. 1641 The client MUST authenticate with the authorization server as 1642 described in Section 3.2.1. 1644 For example, the client makes the following HTTP request using 1645 transport-layer security (extra line breaks are for display purposes 1646 only): 1648 POST /token HTTP/1.1 1649 Host: server.example.com 1650 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1651 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1653 grant_type=client_credentials 1655 The authorization server MUST authenticate the client. 1657 4.4.3. Access Token Response 1659 If the access token request is valid and authorized, the 1660 authorization server issues an access token as described in 1661 Section 5.1. A refresh token SHOULD NOT be included. If the request 1662 failed client authentication or is invalid, the authorization server 1663 returns an 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 "example_parameter":"example_value" 1677 } 1679 4.5. Extension Grants 1681 The client uses an extension grant type by specifying the grant type 1682 using an absolute URI (defined by the authorization server) as the 1683 value of the "grant_type" parameter of the token endpoint, and by 1684 adding any additional parameters necessary. 1686 For example, to request an access token using a SAML 2.0 assertion 1687 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1688 makes the following HTTP request using TLS (line breaks are for 1689 display purposes only): 1691 POST /token HTTP/1.1 1692 Host: server.example.com 1693 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1695 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1696 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1697 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1699 If the access token request is valid and authorized, the 1700 authorization server issues an access token and optional refresh 1701 token as described in Section 5.1. If the request failed client 1702 authentication or is invalid, the authorization server returns an 1703 error response as described in Section 5.2. 1705 5. Issuing an Access Token 1707 If the access token request is valid and authorized, the 1708 authorization server issues an access token and optional refresh 1709 token as described in Section 5.1. If the request failed client 1710 authentication or is invalid, the authorization server returns an 1711 error response as described in Section 5.2. 1713 5.1. Successful Response 1715 The authorization server issues an access token and optional refresh 1716 token, and constructs the response by adding the following parameters 1717 to the entity body of the HTTP response with a 200 (OK) status code: 1719 access_token 1720 REQUIRED. The access token issued by the authorization server. 1721 token_type 1722 REQUIRED. The type of the token issued as described in 1723 Section 7.1. Value is case insensitive. 1724 expires_in 1725 RECOMMENDED. The lifetime in seconds of the access token. For 1726 example, the value "3600" denotes that the access token will 1727 expire in one hour from the time the response was generated. 1728 If omitted, the authorization server SHOULD provide the 1729 expiration time via other means or document the default value. 1731 refresh_token 1732 OPTIONAL. The refresh token which can be used to obtain new 1733 access tokens using the same authorization grant as described 1734 in Section 6. 1735 scope 1736 OPTIONAL, if identical to the scope requested by the client, 1737 otherwise REQUIRED. The scope of the access token as described 1738 by Section 3.3. 1740 The parameters are included in the entity body of the HTTP response 1741 using the "application/json" media type as defined by [RFC4627]. The 1742 parameters are serialized into a JSON structure by adding each 1743 parameter at the highest structure level. Parameter names and string 1744 values are included as JSON strings. Numerical values are included 1745 as JSON numbers. The order of parameters does not matter and can 1746 vary. 1748 The authorization server MUST include the HTTP "Cache-Control" 1749 response header field [RFC2616] with a value of "no-store" in any 1750 response containing tokens, credentials, or other sensitive 1751 information, as well as the "Pragma" response header field [RFC2616] 1752 with a value of "no-cache". 1754 For example: 1756 HTTP/1.1 200 OK 1757 Content-Type: application/json;charset=UTF-8 1758 Cache-Control: no-store 1759 Pragma: no-cache 1761 { 1762 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1763 "token_type":"example", 1764 "expires_in":3600, 1765 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1766 "example_parameter":"example_value" 1767 } 1769 The client MUST ignore unrecognized value names in the response. The 1770 sizes of tokens and other values received from the authorization 1771 server are left undefined. The client should avoid making 1772 assumptions about value sizes. The authorization server should 1773 document the size of any value it issues. 1775 5.2. Error Response 1777 The authorization server responds with an HTTP 400 (Bad Request) 1778 status code and includes the following parameters with the response: 1780 error 1781 REQUIRED. A single error code from the following: 1782 invalid_request 1783 The request is missing a required parameter, includes an 1784 unsupported parameter value (other than grant type), 1785 repeats a parameter, includes multiple credentials, 1786 utilizes more than one mechanism for authenticating the 1787 client, or is otherwise malformed. 1788 invalid_client 1789 Client authentication failed (e.g. unknown client, no 1790 client authentication included, or unsupported 1791 authentication method). The authorization server MAY 1792 return an HTTP 401 (Unauthorized) status code to indicate 1793 which HTTP authentication schemes are supported. If the 1794 client attempted to authenticate via the "Authorization" 1795 request header field, the authorization server MUST 1796 respond with an HTTP 401 (Unauthorized) status code, and 1797 include the "WWW-Authenticate" response header field 1798 matching the authentication scheme used by the client. 1799 invalid_grant 1800 The provided authorization grant (e.g. authorization 1801 code, resource owner credentials) or refresh token is 1802 invalid, expired, revoked, does not match the redirection 1803 URI used in the authorization request, or was issued to 1804 another client. 1805 unauthorized_client 1806 The authenticated client is not authorized to use this 1807 authorization grant type. 1808 unsupported_grant_type 1809 The authorization grant type is not supported by the 1810 authorization server. 1811 invalid_scope 1812 The requested scope is invalid, unknown, malformed, or 1813 exceeds the scope granted by the resource owner. 1814 error_description 1815 OPTIONAL. A human-readable UTF-8 encoded text providing 1816 additional information, used to assist the client developer in 1817 understanding the error that occurred. 1818 error_uri 1819 OPTIONAL. A URI identifying a human-readable web page with 1820 information about the error, used to provide the client 1821 developer with additional information about the error. 1823 The parameters are included in the entity body of the HTTP response 1824 using the "application/json" media type as defined by [RFC4627]. The 1825 parameters are serialized into a JSON structure by adding each 1826 parameter at the highest structure level. Parameter names and string 1827 values are included as JSON strings. Numerical values are included 1828 as JSON numbers. The order of parameters does not matter and can 1829 vary. 1831 For example: 1833 HTTP/1.1 400 Bad Request 1834 Content-Type: application/json;charset=UTF-8 1835 Cache-Control: no-store 1836 Pragma: no-cache 1838 { 1839 "error":"invalid_request" 1840 } 1842 6. Refreshing an Access Token 1844 If the authorization server issued a refresh token to the client, the 1845 client makes a refresh request to the token endpoint by adding the 1846 following parameters using the "application/x-www-form-urlencoded" 1847 format in the HTTP request entity-body: 1849 grant_type 1850 REQUIRED. Value MUST be set to "refresh_token". 1851 refresh_token 1852 REQUIRED. The refresh token issued to the client. 1853 scope 1854 OPTIONAL. The scope of the access request as described by 1855 Section 3.3. The requested scope MUST NOT include any scope 1856 not originally granted by the resource owner, and if omitted is 1857 treated as equal to the scope originally granted by the 1858 resource owner. 1860 Because refresh tokens are typically long-lasting credentials used to 1861 request additional access tokens, the refresh token is bound to the 1862 client which it was issued. If the client type is confidential or 1863 the client was issued client credentials (or assigned other 1864 authentication requirements), the client MUST authenticate with the 1865 authorization server as described in Section 3.2.1. 1867 For example, the client makes the following HTTP request using 1868 transport-layer security (extra line breaks are for display purposes 1869 only): 1871 POST /token HTTP/1.1 1872 Host: server.example.com 1873 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1874 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1876 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1878 The authorization server MUST: 1880 o require client authentication for confidential clients or for any 1881 client that was issued client credentials (or with other 1882 authentication requirements), 1883 o authenticate the client if client authentication is included and 1884 ensure the refresh token was issued to the authenticated client, 1885 and 1886 o validate the refresh token. 1888 If valid and authorized, the authorization server issues an access 1889 token as described in Section 5.1. If the request failed 1890 verification or is invalid, the authorization server returns an error 1891 response as described in Section 5.2. 1893 The authorization server MAY issue a new refresh token, in which case 1894 the client MUST discard the old refresh token and replace it with the 1895 new refresh token. The authorization server MAY revoke the old 1896 refresh token after issuing a new refresh token to the client. If a 1897 new refresh token is issued, the refresh token scope MUST be 1898 identical to that of the refresh token included by the client in the 1899 request. 1901 7. Accessing Protected Resources 1903 The client accesses protected resources by presenting the access 1904 token to the resource server. The resource server MUST validate the 1905 access token and ensure it has not expired and that its scope covers 1906 the requested resource. The methods used by the resource server to 1907 validate the access token (as well as any error responses) are beyond 1908 the scope of this specification, but generally involve an interaction 1909 or coordination between the resource server and the authorization 1910 server. 1912 The method in which the client utilized the access token to 1913 authenticate with the resource server depends on the type of access 1914 token issued by the authorization server. Typically, it involves 1915 using the HTTP "Authorization" request header field [RFC2617] with an 1916 authentication scheme defined by the access token type specification. 1918 7.1. Access Token Types 1920 The access token type provides the client with the information 1921 required to successfully utilize the access token to make a protected 1922 resource request (along with type-specific attributes). The client 1923 MUST NOT use an access token if it does not understand the token 1924 type. 1926 For example, the "bearer" token type defined in 1927 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1928 token string in the request: 1930 GET /resource/1 HTTP/1.1 1931 Host: example.com 1932 Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw 1934 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 1935 utilized by issuing a MAC key together with the access token which is 1936 used to sign certain components of the HTTP requests: 1938 GET /resource/1 HTTP/1.1 1939 Host: example.com 1940 Authorization: MAC id="h480djs93hd8", 1941 nonce="274312:dj83hs9s", 1942 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1944 The above examples are provided for illustration purposes only. 1945 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 1946 [I-D.ietf-oauth-v2-http-mac] specifications before use. 1948 Each access token type definition specifies the additional attributes 1949 (if any) sent to the client together with the "access_token" response 1950 parameter. It also defines the HTTP authentication method used to 1951 include the access token when making a protected resource request. 1953 8. Extensibility 1955 8.1. Defining Access Token Types 1957 Access token types can be defined in one of two ways: registered in 1958 the access token type registry (following the procedures in 1959 Section 11.1), or by using a unique absolute URI as its name. 1961 Types utilizing a URI name SHOULD be limited to vendor-specific 1962 implementations that are not commonly applicable, and are specific to 1963 the implementation details of the resource server where they are 1964 used. 1966 All other types MUST be registered. Type names MUST conform to the 1967 type-name ABNF. If the type definition includes a new HTTP 1968 authentication scheme, the type name SHOULD be identical to the HTTP 1969 authentication scheme name (as defined by [RFC2617]). The token type 1970 "example" is reserved for use in examples. 1972 type-name = 1*name-char 1973 name-char = "-" / "." / "_" / DIGIT / ALPHA 1975 8.2. Defining New Endpoint Parameters 1977 New request or response parameters for use with the authorization 1978 endpoint or the token endpoint are defined and registered in the 1979 parameters registry following the procedure in Section 11.2. 1981 Parameter names MUST conform to the param-name ABNF and parameter 1982 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1983 to the syntax of an existing parameter). 1985 param-name = 1*name-char 1986 name-char = "-" / "." / "_" / DIGIT / ALPHA 1988 Unregistered vendor-specific parameter extensions that are not 1989 commonly applicable, and are specific to the implementation details 1990 of the authorization server where they are used SHOULD utilize a 1991 vendor-specific prefix that is not likely to conflict with other 1992 registered values (e.g. begin with 'companyname_'). 1994 8.3. Defining New Authorization Grant Types 1996 New authorization grant types can be defined by assigning them a 1997 unique absolute URI for use with the "grant_type" parameter. If the 1998 extension grant type requires additional token endpoint parameters, 1999 they MUST be registered in the OAuth parameters registry as described 2000 by Section 11.2. 2002 8.4. Defining New Authorization Endpoint Response Types 2004 New response types for use with the authorization endpoint are 2005 defined and registered in the authorization endpoint response type 2006 registry following the procedure in Section 11.3. Response type 2007 names MUST conform to the response-type ABNF. 2009 response-type = response-name *( SP response-name ) 2010 response-name = 1*response-char 2011 response-char = "_" / DIGIT / ALPHA 2013 If a response type contains one or more space characters (%x20), it 2014 is compared as a space-delimited list of values in which the order of 2015 values does not matter. Only one order of values can be registered, 2016 which covers all other arrangements of the same set of values. 2018 For example, the response type "token code" is left undefined by this 2019 specification. However, an extension can define and register the 2020 "token code" response type. Once registered, the same combination 2021 cannot be registered as "code token", but both values can be used to 2022 denote the same response type. 2024 8.5. Defining Additional Error Codes 2026 In cases where protocol extensions (i.e. access token types, 2027 extension parameters, or extension grant types) require additional 2028 error codes to be used with the authorization code grant error 2029 response (Section 4.1.2.1), the implicit grant error response 2030 (Section 4.2.2.1), or the token error response (Section 5.2), such 2031 error codes MAY be defined. 2033 Extension error codes MUST be registered (following the procedures in 2034 Section 11.4) if the extension they are used in conjunction with is a 2035 registered access token type, a registered endpoint parameter, or an 2036 extension grant type. Error codes used with unregistered extensions 2037 MAY be registered. 2039 Error codes MUST conform to the error-code ABNF, and SHOULD be 2040 prefixed by an identifying name when possible. For example, an error 2041 identifying an invalid value set to the extension parameter "example" 2042 should be named "example_invalid". 2044 error-code = ALPHA *error-char 2045 error-char = "-" / "." / "_" / DIGIT / ALPHA 2047 9. Native Applications 2049 Native applications are clients installed and executed on the device 2050 used by the resource owner (i.e. desktop application, native mobile 2051 application). Native applications require special consideration 2052 related to security, platform capabilities, and overall end-user 2053 experience. 2055 The authorization endpoint requires interaction between the client 2056 and the resource owner's user-agent. Native applications can invoke 2057 an external user-agent or embed a user-agent within the application. 2058 For example: 2060 o External user-agent - the native application can capture the 2061 response from the authorization server using a redirection URI 2062 with a scheme registered with the operating system to invoke the 2063 client as the handler, manual copy-and-paste of the credentials, 2064 running a local web server, installing a user-agent extension, or 2065 by providing a redirection URI identifying a server-hosted 2066 resource under the client's control, which in turn makes the 2067 response available to the native application. 2068 o Embedded user-agent - the native application obtains the response 2069 by directly communicating with the embedded user-agent by 2070 monitoring state changes emitted during the resource load, or 2071 accessing the user-agent's cookies storage. 2073 When choosing between an external or embedded user-agent, developers 2074 should consider: 2076 o An External user-agent may improve completion rate as the resource 2077 owner may already have an active session with the authorization 2078 server removing the need to re-authenticate. It provides a 2079 familiar end-user experience and functionality. The resource 2080 owner may also rely on user-agent features or extensions to assist 2081 with authentication (e.g. password manager, 2-factor device 2082 reader). 2084 o An embedded user-agent may offer improved usability, as it removes 2085 the need to switch context and open new windows. 2086 o An embedded user-agent poses a security challenge because resource 2087 owners are authenticating in an unidentified window without access 2088 to the visual protections found in most external user-agents. An 2089 embedded user-agent educates end-users to trust unidentified 2090 requests for authentication (making phishing attacks easier to 2091 execute). 2093 When choosing between the implicit grant type and the authorization 2094 code grant type, the following should be considered: 2096 o Native applications that use the authorization code grant type 2097 SHOULD do so without using client credentials, due to the native 2098 application's inability to keep client credentials confidential. 2099 o When using the implicit grant type flow a refresh token is not 2100 returned which requires repeating the authorization process once 2101 the access token expires. 2103 10. Security Considerations 2105 As a flexible and extensible framework, OAuth's security 2106 considerations depend on many factors. The following sections 2107 provide implementers with security guidelines focused on the three 2108 client profiles described in Section 2.1: web application, user- 2109 agent-based application, and native application. 2111 A comprehensive OAuth security model and analysis, as well as 2112 background for the protocol design is provided by 2113 [I-D.ietf-oauth-v2-threatmodel]. 2115 10.1. Client Authentication 2117 The authorization server establishes client credentials with web 2118 application clients for the purpose of client authentication. The 2119 authorization server is encouraged to consider stronger client 2120 authentication means than a client password. Web application clients 2121 MUST ensure confidentiality of client passwords and other client 2122 credentials. 2124 The authorization server MUST NOT issue client passwords or other 2125 client credentials to native application or user-agent-based 2126 application clients for the purpose of client authentication. The 2127 authorization server MAY issue a client password or other credentials 2128 for a specific installation of a native application client on a 2129 specific device. 2131 When client authentication is not possible, the authorization server 2132 SHOULD employ other means to validate the client's identity. For 2133 example, by requiring the registration of the client redirection URI 2134 or enlisting the resource owner to confirm identity. A valid 2135 redirection URI is not sufficient to verify the client's identity 2136 when asking for resource owner authorization, but can be used to 2137 prevent delivering credentials to a counterfeit client after 2138 obtaining resource owner authorization. 2140 The authorization server must consider the security implications of 2141 interacting with unauthenticated clients and take measures to limit 2142 the potential exposure of other credentials (e.g. refresh tokens) 2143 issued to such clients. 2145 10.2. Client Impersonation 2147 A malicious client can impersonate another client and obtain access 2148 to protected resources, if the impersonated client fails to, or is 2149 unable to, keep its client credentials confidential. 2151 The authorization server MUST authenticate the client whenever 2152 possible. If the authorization server cannot authenticate the client 2153 due to the client's nature, the authorization server MUST require the 2154 registration of any redirection URI used for receiving authorization 2155 responses, and SHOULD utilize other means to protect resource owners 2156 from such potentially malicious clients. For example, the 2157 authorization server can engage the resource owner to assist in 2158 identifying the client and its origin. 2160 The authorization server SHOULD enforce explicit resource owner 2161 authentication and provide the resource owner with information about 2162 the client and the requested authorization scope and lifetime. It is 2163 up to the resource owner to review the information in the context of 2164 the current client, and authorize or deny the request. 2166 The authorization server SHOULD NOT process repeated authorization 2167 requests automatically (without active resource owner interaction) 2168 without authenticating the client or relying on other measures to 2169 ensure the repeated request comes from the original client and not an 2170 impersonator. 2172 10.3. Access Tokens 2174 Access token credentials (as well as any confidential access token 2175 attributes) MUST be kept confidential in transit and storage, and 2176 only shared among the authorization server, the resource servers the 2177 access token is valid for, and the client to whom the access token is 2178 issued. Access token credentials MUST only be transmitted using TLS 2179 as described in Section 1.6 with server authentication as defined by 2180 [RFC2818]. 2182 When using the implicit grant type, the access token is transmitted 2183 in the URI fragment, which can expose it to unauthorized parties. 2185 The authorization server MUST ensure that access tokens cannot be 2186 generated, modified, or guessed to produce valid access tokens by 2187 unauthorized parties. 2189 The client SHOULD request access tokens with the minimal scope 2190 necessary. The authorization server SHOULD take the client identity 2191 into account when choosing how to honor the requested scope, and MAY 2192 issue an access token with a less rights than requested. 2194 10.4. Refresh Tokens 2196 Authorization servers MAY issue refresh tokens to web application 2197 clients and native application clients. 2199 Refresh tokens MUST be kept confidential in transit and storage, and 2200 shared only among the authorization server and the client to whom the 2201 refresh tokens were issued. The authorization server MUST maintain 2202 the binding between a refresh token and the client to whom it was 2203 issued. Refresh tokens MUST only be transmitted using TLS as 2204 described in Section 1.6 with server authentication as defined by 2205 [RFC2818]. 2207 The authorization server MUST verify the binding between the refresh 2208 token and client identity whenever the client identity can be 2209 authenticated. When client authentication is not possible, the 2210 authorization server SHOULD deploy other means to detect refresh 2211 token abuse. 2213 For example, the authorization server could employ refresh token 2214 rotation in which a new refresh token is issued with every access 2215 token refresh response. The previous refresh token is invalidated 2216 but retained by the authorization server. If a refresh token is 2217 compromised and subsequently used by both the attacker and the 2218 legitimate client, one of them will present an invalidated refresh 2219 token which will inform the authorization server of the breach. 2221 The authorization server MUST ensure that refresh tokens cannot be 2222 generated, modified, or guessed to produce valid refresh tokens by 2223 unauthorized parties. 2225 10.5. Authorization Codes 2227 The transmission of authorization codes SHOULD be made over a secure 2228 channel, and the client SHOULD implement TLS for use with its 2229 redirection URI if the URI identifies a network resource. Since 2230 authorization codes are transmitted via user-agent redirections, they 2231 could potentially be disclosed through user-agent history and HTTP 2232 referrer headers. 2234 Authorization codes operate as plaintext bearer credentials, used to 2235 verify that the resource owner who granted authorization at the 2236 authorization server is the same resource owner returning to the 2237 client to complete the process. Therefore, if the client relies on 2238 the authorization code for its own resource owner authentication, the 2239 client redirection endpoint MUST require TLS. 2241 Authorization codes MUST be short lived and single use. If the 2242 authorization server observes multiple attempts to exchange an 2243 authorization code for an access token, the authorization server 2244 SHOULD attempt to revoke all access tokens already granted based on 2245 the compromised authorization code. 2247 If the client can be authenticated, the authorization servers MUST 2248 authenticate the client and ensure that the authorization code was 2249 issued to the same client. 2251 10.6. Authorization Code Redirection URI Manipulation 2253 When requesting authorization using the authorization code grant 2254 type, the client can specify a redirection URI via the "redirect_uri" 2255 parameter. If an attacker can manipulate the value of the 2256 redirection URI, it can cause the authorization server to redirect 2257 the resource owner user-agent to a URI under the control of the 2258 attacker with the authorization code. 2260 An attacker can create an account at a legitimate client and initiate 2261 the authorization flow. When the attacker's user-agent is sent to 2262 the authorization server to grant access, the attacker grabs the 2263 authorization URI provided by the legitimate client, and replaces the 2264 client's redirection URI with a URI under the control of the 2265 attacker. The attacker then tricks the victim into following the 2266 manipulated link to authorize access to the legitimate client. 2268 Once at the authorization server, the victim is prompted with a 2269 normal, valid request on behalf of a legitimate and trusted client, 2270 and authorizes the request. The victim is then redirected to an 2271 endpoint under the control of the attacker with the authorization 2272 code. The attacker completes the authorization flow by sending the 2273 authorization code to the client using the original redirection URI 2274 provided by the client. The client exchanges the authorization code 2275 with an access token and links it to the attacker's client account 2276 which can now gain access to the protected resources authorized by 2277 the victim (via the client). 2279 In order to prevent such an attack, the authorization server MUST 2280 ensure that the redirection URI used to obtain the authorization code 2281 is identical to the redirection URI provided when exchanging the 2282 authorization code for an access token. The authorization server 2283 MUST require public clients and SHOULD require confidential clients 2284 to register their redirection URIs. If a redirection URI is provided 2285 in the request, the authorization server MUST validate it against the 2286 registered value. 2288 10.7. Resource Owner Password Credentials 2290 The resource owner password credentials grant type is often used for 2291 legacy or migration reasons. It reduces the overall risk of storing 2292 username and password by the client, but does not eliminate the need 2293 to expose highly privileged credentials to the client. 2295 This grant type carries a higher risk than other grant types because 2296 it maintains the password anti-pattern this protocol seeks to avoid. 2297 The client could abuse the password or the password could 2298 unintentionally be disclosed to an attacker (e.g. via log files or 2299 other records kept by the client). 2301 Additionally, because the resource owner does not have control over 2302 the authorization process (the resource owner involvement ends when 2303 it hands over its credentials to the client), the client can obtain 2304 access tokens with a broader scope than desired by the resource 2305 owner. The authorization server should consider the scope and 2306 lifetime of access tokens issued via this grant type. 2308 The authorization server and client SHOULD minimize use of this grant 2309 type and utilize other grant types whenever possible. 2311 10.8. Request Confidentiality 2313 Access tokens, refresh tokens, resource owner passwords, and client 2314 credentials MUST NOT be transmitted in the clear. Authorization 2315 codes SHOULD NOT be transmitted in the clear. 2317 The "state" and "scope" parameters SHOULD NOT include sensitive 2318 client or resource owner information in plain text as they can be 2319 transmitted over insecure channels or stored insecurely. 2321 10.9. Endpoints Authenticity 2323 In order to prevent man-in-the-middle attacks, the authorization 2324 server MUST implement and require TLS with server authentication as 2325 defined by [RFC2818] for any request sent to the authorization and 2326 token endpoints. The client MUST validate the authorization server's 2327 TLS certificate as defined by [RFC6125], and in accordance with its 2328 requirements for server identity authentication. 2330 10.10. Credentials Guessing Attacks 2332 The authorization server MUST prevent attackers from guessing access 2333 tokens, authorization codes, refresh tokens, resource owner 2334 passwords, and client credentials. 2336 The probability of an attacker guessing generated tokens (and other 2337 credentials not intended for handling by end-users) MUST be less than 2338 or equal to 2^(-128) and SHOULD be less than or equal to 2^(-160). 2340 The authorization server MUST utilize other means to protect 2341 credentials intended for end-user usage. 2343 10.11. Phishing Attacks 2345 Wide deployment of this and similar protocols may cause end-users to 2346 become inured to the practice of being redirected to websites where 2347 they are asked to enter their passwords. If end-users are not 2348 careful to verify the authenticity of these websites before entering 2349 their credentials, it will be possible for attackers to exploit this 2350 practice to steal resource owners' passwords. 2352 Service providers should attempt to educate end-users about the risks 2353 phishing attacks pose, and should provide mechanisms that make it 2354 easy for end-users to confirm the authenticity of their sites. 2355 Client developers should consider the security implications of how 2356 they interact with the user-agent (e.g., external, embedded), and the 2357 ability of the end-user to verify the authenticity of the 2358 authorization server. 2360 To reduce the risk of phishing attacks, the authorization servers 2361 MUST utilize TLS on every endpoint used for end-user interaction. 2363 10.12. Cross-Site Request Forgery 2365 Cross-site request forgery (CSRF) is an exploit in which an attacker 2366 causes the user-agent of a victim end-user to follow a malicious URI 2367 (e.g. provided to the user-agent as a misleading link, image, or 2368 redirection) to a trusting server (usually established via the 2369 presence of a valid session cookie). 2371 A CSRF attack against the client's redirection URI allows an attacker 2372 to inject their own authorization code or access token, which can 2373 result in the client using an access token associated with the 2374 attacker's protected resources rather than the victim's (e.g. save 2375 the victim's bank account information to a protected resource 2376 controlled by the attacker). 2378 The client MUST implement CSRF protection for its redirection URI. 2379 This is typically accomplished by requiring any request sent to the 2380 redirection URI endpoint to include a value that binds the request to 2381 the user-agent's authenticated state (e.g. a hash of the session 2382 cookie used to authenticate the user-agent). The client SHOULD 2383 utilize the "state" request parameter to deliver this value to the 2384 authorization server when making an authorization request. 2386 Once authorization has been obtained from the end-user, the 2387 authorization server redirects the end-user's user-agent back to the 2388 client with the required binding value contained in the "state" 2389 parameter. The binding value enables the client to verify the 2390 validity of the request by matching the binding value to the user- 2391 agent's authenticated state. The binding value used for CSRF 2392 protection MUST contain a non-guessable value (as described in 2393 Section 10.10), and the user-agent's authenticated state (e.g. 2394 session cookie, HTML5 local storage) MUST be kept in a location 2395 accessible only to the client and the user-agent (i.e., protected by 2396 same-origin policy). 2398 A CSRF attack against the authorization server's authorization 2399 endpoint can result in an attacker obtaining end-user authorization 2400 for a malicious client without involving or alerting the end-user. 2402 The authorization server MUST implement CSRF protection for its 2403 authorization endpoint, and ensure that a malicious client cannot 2404 obtain authorization without the awareness and explicit consent of 2405 the resource owner. 2407 10.13. Clickjacking 2409 In a clickjacking attack, an attacker registers a legitimate client 2410 and then constructs a malicious site in which it loads the 2411 authorization server's authorization endpoint web page in a 2412 transparent iframe overlaid on top of a set of dummy buttons which 2413 are carefully constructed to be placed directly under important 2414 buttons on the authorization page. When an end-user clicks a 2415 misleading visible button, the end-user is actually clicking an 2416 invisible button on the authorization page (such as an "Authorize" 2417 button). This allows an attacker to trick a resource owner into 2418 granting its client access without their knowledge. 2420 To prevent this form of attack, native applications SHOULD use 2421 external browsers instead of embedding browsers within the 2422 application when requesting end-user authorization. For most newer 2423 browsers, avoidance of iframes can be enforced by the authorization 2424 server using the (non-standard) "x-frame-options" header. This 2425 header can have two values, "deny" and "sameorigin", which will block 2426 any framing, or framing by sites with a different origin, 2427 respectively. For older browsers, javascript framebusting techniques 2428 can be used but may not be effective in all browsers. 2430 10.14. Code Injection and Input Validation 2432 A code injection attack occurs when an input or otherwise external 2433 variable is used by an application unsanitized and causes 2434 modification to the application logic. This may allow an attacker to 2435 gain access to the application device or its data, cause denial of 2436 service, or a wide range of malicious side-effects. 2438 The Authorization server and client MUST sanitize (and validate when 2439 possible) any value received, in particular, the value of the "state" 2440 and "redirect_uri" parameters. 2442 10.15. Open Redirectors 2444 The authorization server authorization endpoint and the client 2445 redirection endpoint can be improperly configured and operate as open 2446 redirectors. An open redirector is an endpoint using a parameter to 2447 automatically redirect a user-agent to the location specified by the 2448 parameter value without any validation. 2450 Open redirectors can be used in phishing attacks, or by an attacker 2451 to get end-users to visit malicious sites by making the URI's 2452 authority look like a familiar and trusted destination. In addition, 2453 if the authorization server allows the client to register only part 2454 of the redirection URI, an attacker can use an open redirector 2455 operated by the client to construct a redirection URI that will pass 2456 the authorization server validation but will send the authorization 2457 code or access token to an endpoint under the control of the 2458 attacker. 2460 11. IANA Considerations 2461 11.1. The OAuth Access Token Type Registry 2463 This specification establishes the OAuth access token type registry. 2465 Access token types are registered on the advice of one or more 2466 Designated Experts (appointed by the IESG or their delegate), with a 2467 Specification Required (using terminology from [RFC5226]). However, 2468 to allow for the allocation of values prior to publication, the 2469 Designated Expert(s) may approve registration once they are satisfied 2470 that such a specification will be published. 2472 Registration requests should be sent to the [TBD]@ietf.org mailing 2473 list for review and comment, with an appropriate subject (e.g., 2474 "Request for access token type: example"). [[ Note to RFC-EDITOR: The 2475 name of the mailing list should be determined in consultation with 2476 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2478 Within at most 14 days of the request, the Designated Expert(s) will 2479 either approve or deny the registration request, communicating this 2480 decision to the review list and IANA. Denials should include an 2481 explanation and, if applicable, suggestions as to how to make the 2482 request successful. 2484 Decisions (or lack thereof) made by the Designated Expert(s) can be 2485 first appealed to Security Area Directors (contactable using 2486 app-ads@tools.ietf.org email address or directly by looking up their 2487 email addresses on http://www.iesg.org/ website) and, if the 2488 appellant is not satisfied with the response, to the full IESG (using 2489 the iesg@iesg.org mailing list). 2491 IANA should only accept registry updates from the Designated 2492 Expert(s), and should direct all requests for registration to the 2493 review mailing list. 2495 11.1.1. Registration Template 2497 Type name: 2498 The name requested (e.g., "example"). 2499 Additional Token Endpoint Response Parameters: 2500 Additional response parameters returned together with the 2501 "access_token" parameter. New parameters MUST be separately 2502 registered in the OAuth parameters registry as described by 2503 Section 11.2. 2504 HTTP Authentication Scheme(s): 2505 The HTTP authentication scheme name(s), if any, used to 2506 authenticate protected resources requests using access tokens of 2507 this type. 2509 Change controller: 2510 For standards-track RFCs, state "IETF". For others, give the name 2511 of the responsible party. Other details (e.g., postal address, 2512 e-mail address, home page URI) may also be included. 2513 Specification document(s): 2514 Reference to the document that specifies the parameter, preferably 2515 including a URI that can be used to retrieve a copy of the 2516 document. An indication of the relevant sections may also be 2517 included, but is not required. 2519 11.2. The OAuth Parameters Registry 2521 This specification establishes the OAuth parameters registry. 2523 Additional parameters for inclusion in the authorization endpoint 2524 request, the authorization endpoint response, the token endpoint 2525 request, or the token endpoint response are registered on the advice 2526 of one or more Designated Experts (appointed by the IESG or their 2527 delegate), with a Specification Required (using terminology from 2528 [RFC5226]). However, to allow for the allocation of values prior to 2529 publication, the Designated Expert(s) may approve registration once 2530 they are satisfied that such a specification will be published. 2532 Registration requests should be sent to the [TBD]@ietf.org mailing 2533 list for review and comment, with an appropriate subject (e.g., 2534 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 2535 the mailing list should be determined in consultation with the IESG 2536 and IANA. Suggested name: oauth-ext-review. ]] 2538 Within at most 14 days of the request, the Designated Expert(s) will 2539 either approve or deny the registration request, communicating this 2540 decision to the review list and IANA. Denials should include an 2541 explanation and, if applicable, suggestions as to how to make the 2542 request successful. 2544 Decisions (or lack thereof) made by the Designated Expert(s) can be 2545 first appealed to Security Area Directors (contactable using 2546 app-ads@tools.ietf.org email address or directly by looking up their 2547 email addresses on http://www.iesg.org/ website) and, if the 2548 appellant is not satisfied with the response, to the full IESG (using 2549 the iesg@iesg.org mailing list). 2551 IANA should only accept registry updates from the Designated 2552 Expert(s), and should direct all requests for registration to the 2553 review mailing list. 2555 11.2.1. Registration Template 2557 Parameter name: 2558 The name requested (e.g., "example"). 2559 Parameter usage location: 2560 The location(s) where parameter can be used. The possible 2561 locations are: authorization request, authorization response, 2562 token request, or token response. 2563 Change controller: 2564 For standards-track RFCs, state "IETF". For others, give the name 2565 of the responsible party. Other details (e.g., postal address, 2566 e-mail address, home page URI) may also be included. 2567 Specification document(s): 2568 Reference to the document that specifies the parameter, preferably 2569 including a URI that can be used to retrieve a copy of the 2570 document. An indication of the relevant sections may also be 2571 included, but is not required. 2573 11.2.2. Initial Registry Contents 2575 The OAuth Parameters Registry's initial contents are: 2577 o Parameter name: client_id 2578 o Parameter usage location: authorization request, token request 2579 o Change controller: IETF 2580 o Specification document(s): [[ this document ]] 2582 o Parameter name: client_secret 2583 o Parameter usage location: token request 2584 o Change controller: IETF 2585 o Specification document(s): [[ this document ]] 2587 o Parameter name: response_type 2588 o Parameter usage location: authorization request 2589 o Change controller: IETF 2590 o Specification document(s): [[ this document ]] 2592 o Parameter name: redirect_uri 2593 o Parameter usage location: authorization request, token request 2594 o Change controller: IETF 2595 o Specification document(s): [[ this document ]] 2597 o Parameter name: scope 2598 o Parameter usage location: authorization request, authorization 2599 response, token request, token response 2600 o Change controller: IETF 2601 o Specification document(s): [[ this document ]] 2603 o Parameter name: state 2604 o Parameter usage location: authorization request, authorization 2605 response 2606 o Change controller: IETF 2607 o Specification document(s): [[ this document ]] 2609 o Parameter name: code 2610 o Parameter usage location: authorization response, token request 2611 o Change controller: IETF 2612 o Specification document(s): [[ this document ]] 2614 o Parameter name: error_description 2615 o Parameter usage location: authorization response, token response 2616 o Change controller: IETF 2617 o Specification document(s): [[ this document ]] 2619 o Parameter name: error_uri 2620 o Parameter usage location: authorization response, token response 2621 o Change controller: IETF 2622 o Specification document(s): [[ this document ]] 2624 o Parameter name: grant_type 2625 o Parameter usage location: token request 2626 o Change controller: IETF 2627 o Specification document(s): [[ this document ]] 2629 o Parameter name: access_token 2630 o Parameter usage location: authorization response, token response 2631 o Change controller: IETF 2632 o Specification document(s): [[ this document ]] 2634 o Parameter name: token_type 2635 o Parameter usage location: authorization response, token response 2636 o Change controller: IETF 2637 o Specification document(s): [[ this document ]] 2639 o Parameter name: expires_in 2640 o Parameter usage location: authorization response, token response 2641 o Change controller: IETF 2642 o Specification document(s): [[ this document ]] 2644 o Parameter name: username 2645 o Parameter usage location: token request 2646 o Change controller: IETF 2647 o Specification document(s): [[ this document ]] 2649 o Parameter name: password 2650 o Parameter usage location: token request 2651 o Change controller: IETF 2652 o Specification document(s): [[ this document ]] 2654 o Parameter name: refresh_token 2655 o Parameter usage location: token request, token response 2656 o Change controller: IETF 2657 o Specification document(s): [[ this document ]] 2659 11.3. The OAuth Authorization Endpoint Response Type Registry 2661 This specification establishes the OAuth authorization endpoint 2662 response type registry. 2664 Additional response type for use with the authorization endpoint are 2665 registered on the advice of one or more Designated Experts (appointed 2666 by the IESG or their delegate), with a Specification Required (using 2667 terminology from [RFC5226]). However, to allow for the allocation of 2668 values prior to publication, the Designated Expert(s) may approve 2669 registration once they are satisfied that such a specification will 2670 be published. 2672 Registration requests should be sent to the [TBD]@ietf.org mailing 2673 list for review and comment, with an appropriate subject (e.g., 2674 "Request for response type: example"). [[ Note to RFC-EDITOR: The 2675 name of the mailing list should be determined in consultation with 2676 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2678 Within at most 14 days of the request, the Designated Expert(s) will 2679 either approve or deny the registration request, communicating this 2680 decision to the review list and IANA. Denials should include an 2681 explanation and, if applicable, suggestions as to how to make the 2682 request successful. 2684 Decisions (or lack thereof) made by the Designated Expert(s) can be 2685 first appealed to Security Area Directors (contactable using 2686 app-ads@tools.ietf.org email address or directly by looking up their 2687 email addresses on http://www.iesg.org/ website) and, if the 2688 appellant is not satisfied with the response, to the full IESG (using 2689 the iesg@iesg.org mailing list). 2691 IANA should only accept registry updates from the Designated 2692 Expert(s), and should direct all requests for registration to the 2693 review mailing list. 2695 11.3.1. Registration Template 2697 Response type name: 2698 The name requested (e.g., "example"). 2699 Change controller: 2700 For standards-track RFCs, state "IETF". For others, give the name 2701 of the responsible party. Other details (e.g., postal address, 2702 e-mail address, home page URI) may also be included. 2703 Specification document(s): 2704 Reference to the document that specifies the type, preferably 2705 including a URI that can be used to retrieve a copy of the 2706 document. An indication of the relevant sections may also be 2707 included, but is not required. 2709 11.3.2. Initial Registry Contents 2711 The OAuth Authorization Endpoint Response Type Registry's initial 2712 contents are: 2714 o Response type name: code 2715 o Change controller: IETF 2716 o Specification document(s): [[ this document ]] 2718 o Response type name: token 2719 o Change controller: IETF 2720 o Specification document(s): [[ this document ]] 2722 11.4. The OAuth Extensions Error Registry 2724 This specification establishes the OAuth extensions error registry. 2726 Additional error codes used together with other protocol extensions 2727 (i.e. extension grant types, access token types, or extension 2728 parameters) are registered on the advice of one or more Designated 2729 Experts (appointed by the IESG or their delegate), with a 2730 Specification Required (using terminology from [RFC5226]). However, 2731 to allow for the allocation of values prior to publication, the 2732 Designated Expert(s) may approve registration once they are satisfied 2733 that such a specification will be published. 2735 Registration requests should be sent to the [TBD]@ietf.org mailing 2736 list for review and comment, with an appropriate subject (e.g., 2737 "Request for error code: example"). [[ Note to RFC-EDITOR: The name 2738 of the mailing list should be determined in consultation with the 2739 IESG and IANA. Suggested name: oauth-ext-review. ]] 2741 Within at most 14 days of the request, the Designated Expert(s) will 2742 either approve or deny the registration request, communicating this 2743 decision to the review list and IANA. Denials should include an 2744 explanation and, if applicable, suggestions as to how to make the 2745 request successful. 2747 Decisions (or lack thereof) made by the Designated Expert(s) can be 2748 first appealed to Security Area Directors (contactable using 2749 app-ads@tools.ietf.org email address or directly by looking up their 2750 email addresses on http://www.iesg.org/ website) and, if the 2751 appellant is not satisfied with the response, to the full IESG (using 2752 the iesg@iesg.org mailing list). 2754 IANA should only accept registry updates from the Designated 2755 Expert(s), and should direct all requests for registration to the 2756 review mailing list. 2758 11.4.1. Registration Template 2760 Error name: 2761 The name requested (e.g., "example"). 2762 Error usage location: 2763 The location(s) where the error can be used. The possible 2764 locations are: authorization code grant error response 2765 (Section 4.1.2.1), implicit grant error response 2766 (Section 4.2.2.1), or token error response (Section 5.2). 2767 Related protocol extension: 2768 The name of the extension grant type, access token type, or 2769 extension parameter, the error code is used in conjunction with. 2770 Change controller: 2771 For standards-track RFCs, state "IETF". For others, give the name 2772 of the responsible party. Other details (e.g., postal address, 2773 e-mail address, home page URI) may also be included. 2774 Specification document(s): 2775 Reference to the document that specifies the error code, 2776 preferably including a URI that can be used to retrieve a copy of 2777 the document. An indication of the relevant sections may also be 2778 included, but is not required. 2780 12. Acknowledgements 2782 The initial OAuth 2.0 protocol specification was edited by David 2783 Recordon, based on two previous publications: the OAuth 1.0 community 2784 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 2785 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 2786 Considerations section was drafted by Torsten Lodderstedt, Mark 2787 McGloin, Phil Hunt, and Anthony Nadalin. 2789 The OAuth 1.0 community specification was edited by Eran Hammer and 2790 authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 2791 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 2792 Kellan Elliott-McCrea, Larry Halff, Eran Hammer, Ben Laurie, Chris 2793 Messina, John Panzer, Sam Quigley, David Recordon, Eran Sandler, 2794 Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy Smith. 2796 The OAuth WRAP specification was edited by Dick Hardt and authored by 2797 Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. 2799 This specification is the work of the OAuth Working Group which 2800 includes dozens of active and dedicated participants. In particular, 2801 the following individuals contributed ideas, feedback, and wording 2802 which shaped and formed the final specification: 2804 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 2805 Bell, Brian Campbell, Scott Cantor, Marcos Caceres, Blaine Cook, 2806 Roger Crew, Brian Eaton, Leah Culver, Bill de hOra, Andre DeMarre, 2807 Brian Eaton, Wolter Eldering, Brian Ellin, Igor Faynberg, George 2808 Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, Brent Goldman, 2809 Kristoffer Gronowski, Justin Hart, Dick Hardt, Craig Heath, Phil 2810 Hunt, Michael B. Jones, Terry Jones, John Kemp, Mark Kent, Raffi 2811 Krikorian, Chasen Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui- 2812 Lan Lu, Casey Lucas, Paul Madsen, Alastair Mair, Eve Maler, James 2813 Manger, Mark McGloin, Laurence Miao, William Mills, Chuck Mortimore, 2814 Anthony Nadalin, Julian Reschke, Justin Richer, Peter Saint-Andre, 2815 Nat Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, 2816 Vlad Skvortsov, Justin Smith, Haibin Song, Niv Steingarten, Christian 2817 Stubner, Jeremy Suriel, Paul Tarjan, Christopher Thomas, Henry S. 2818 Thompson, Allen Tom, Franklin Tse, Nick Walker, Shane Weeden, and 2819 Skylar Woodward. 2821 This document was produced under the chairmanship of Blaine Cook, 2822 Peter Saint-Andre, Hannes Tschofenig, and Barry Leiba. The area 2823 directors included Lisa Dusseault, Peter Saint-Andre, and Stephen 2824 Farrell. 2826 Appendix A. Editor's Notes 2828 While many people contributed to this specification throughout its 2829 long journey, the editor would like to acknowledge and thank a few 2830 individuals for their outstanding and invaluable efforts leading up 2831 to the publication of this specification. It is these individuals 2832 without whom this work would not have existed or reached its 2833 successful conclusion. 2835 David Recordon for continuously being one of OAuth's most valuable 2836 assets, bringing pragmatism and urgency to the work, and helping 2837 shape it from its very beginning, as well as being one of the best 2838 collaborators I had the pleasure of working with. 2840 James Manger for his creative ideas and always insightful feedback. 2841 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 2842 Marius Scurtescu, and Luke Shepard for their continued participation 2843 and valuable feedback. 2845 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 2846 support of this work for over three years. 2848 13. References 2850 13.1. Normative References 2852 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2853 Requirement Levels", BCP 14, RFC 2119, March 1997. 2855 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2856 RFC 2246, January 1999. 2858 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2859 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2860 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2862 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2863 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2864 Authentication: Basic and Digest Access Authentication", 2865 RFC 2617, June 1999. 2867 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2869 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2870 Resource Identifier (URI): Generic Syntax", STD 66, 2871 RFC 3986, January 2005. 2873 [RFC4627] Crockford, D., "The application/json Media Type for 2874 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2876 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2877 RFC 4949, August 2007. 2879 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2880 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2881 May 2008. 2883 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2884 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2886 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2887 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2889 [RFC6125] Saint-Andre, P. and J. Hodges, "Representation and 2890 Verification of Domain-Based Application Service Identity 2891 within Internet Public Key Infrastructure Using X.509 2892 (PKIX) Certificates in the Context of Transport Layer 2893 Security (TLS)", RFC 6125, March 2011. 2895 [W3C.REC-html401-19991224] 2896 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 2897 Specification", World Wide Web Consortium 2898 Recommendation REC-html401-19991224, December 1999, 2899 . 2901 13.2. Informative References 2903 [I-D.draft-hardt-oauth-01] 2904 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2905 Web Resource Authorization Profiles", January 2010. 2907 [I-D.ietf-oauth-saml2-bearer] 2908 Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for 2909 OAuth 2.0", draft-ietf-oauth-saml2-bearer-08 (work in 2910 progress), August 2011. 2912 [I-D.ietf-oauth-v2-bearer] 2913 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2914 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-08 2915 (work in progress), July 2011. 2917 [I-D.ietf-oauth-v2-http-mac] 2918 Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP 2919 Authentication: MAC Access Authentication", 2920 draft-ietf-oauth-v2-http-mac-00 (work in progress), 2921 May 2011. 2923 [I-D.ietf-oauth-v2-threatmodel] 2924 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2925 Threat Model and Security Considerations", 2926 draft-ietf-oauth-v2-threatmodel-00 (work in progress), 2927 July 2011. 2929 [OASIS.saml-core-2.0-os] 2930 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2931 "Assertions and Protocol for the OASIS Security Assertion 2932 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2933 2.0-os, March 2005. 2935 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2936 April 2010. 2938 Authors' Addresses 2940 Eran Hammer (editor) 2942 Email: eran@hueniverse.com 2943 URI: http://hueniverse.com 2945 David Recordon 2946 Facebook 2948 Email: dr@fb.com 2949 URI: http://www.davidrecordon.com/ 2951 Dick Hardt 2952 Microsoft 2954 Email: dick.hardt@gmail.com 2955 URI: http://dickhardt.org/