idnits 2.17.1 draft-ietf-oauth-v2-22.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 (September 22, 2011) is 4593 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) == 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: 8 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-Lahav, Ed. 3 Internet-Draft Yahoo! 4 Obsoletes: 5849 (if approved) D. Recordon 5 Intended status: Standards Track Facebook 6 Expires: March 25, 2012 D. Hardt 7 Microsoft 8 September 22, 2011 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-22 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 March 25, 2012. 40 Copyright Notice 42 Copyright (c) 2011 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 . . . . . . . . . . . . . . . . . . 7 62 1.3.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 8 63 1.3.3. Resource Owner Password Credentials . . . . . . . . . 8 64 1.3.4. Client Credentials . . . . . . . . . . . . . . . . . . 8 65 1.4. Access Token . . . . . . . . . . . . . . . . . . . . . . 9 66 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 9 67 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 11 68 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 11 69 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 12 70 2.2. Client Identifier . . . . . . . . . . . . . . . . . . . . 13 71 2.3. Client Authentication . . . . . . . . . . . . . . . . . . 13 72 2.3.1. Client Password . . . . . . . . . . . . . . . . . . . 13 73 2.3.2. Other Authentication Methods . . . . . . . . . . . . . 14 74 2.4. Unregistered Clients . . . . . . . . . . . . . . . . . . 15 75 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 15 76 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 15 77 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 16 78 3.1.2. Redirection Endpoint . . . . . . . . . . . . . . . . . 16 79 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 18 80 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 19 81 3.3. Access Token Scope . . . . . . . . . . . . . . . . . . . 20 82 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 20 83 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 20 84 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 22 85 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 23 86 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 25 87 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 26 88 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 26 89 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 28 90 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 29 91 4.3. Resource Owner Password Credentials . . . . . . . . . . . 32 92 4.3.1. Authorization Request and Response . . . . . . . . . . 33 93 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 33 94 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 34 95 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 34 96 4.4.1. Authorization Request and Response . . . . . . . . . . 35 97 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 35 98 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 36 99 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 36 100 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 37 101 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 37 102 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 38 103 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 40 104 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 41 105 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 106 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42 107 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 42 108 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 43 109 8.3. Defining New Authorization Grant Types . . . . . . . . . 43 110 8.4. Defining New Authorization Endpoint Response Types . . . 43 111 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 44 112 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 44 113 10. Security Considerations . . . . . . . . . . . . . . . . . . . 45 114 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 46 115 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 46 116 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 117 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 47 118 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 48 119 10.6. Authorization Code Redirection URI Manipulation . . . . . 48 120 10.7. Resource Owner Password Credentials . . . . . . . . . . . 49 121 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 50 122 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 50 123 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 50 124 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 50 125 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 51 126 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 52 127 10.14. Code Injection and Input Validation . . . . . . . . . . . 52 128 10.15. Open Redirectors . . . . . . . . . . . . . . . . . . . . 52 129 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 53 130 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 53 131 11.1.1. Registration Template . . . . . . . . . . . . . . . . 53 132 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 54 133 11.2.1. Registration Template . . . . . . . . . . . . . . . . 55 134 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 55 135 11.3. The OAuth Authorization Endpoint Response Type 136 Registry . . . . . . . . . . . . . . . . . . . . . . . . 57 137 11.3.1. Registration Template . . . . . . . . . . . . . . . . 58 138 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 58 139 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 58 140 11.4.1. Registration Template . . . . . . . . . . . . . . . . 59 141 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 60 142 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 60 143 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 61 144 13.1. Normative References . . . . . . . . . . . . . . . . . . 61 145 13.2. Informative References . . . . . . . . . . . . . . . . . 62 146 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 148 1. Introduction 150 In the traditional client-server authentication model, the client 151 requests an access restricted resource (protected resource) on the 152 server by authenticating with the server using the resource owner's 153 credentials. In order to provide third-party applications access to 154 restricted resources, the resource owner shares its credentials with 155 the third-party. This creates several problems and limitations: 157 o Third-party applications are required to store the resource 158 owner's credentials for future use, typically a password in clear- 159 text. 160 o Servers are required to support password authentication, despite 161 the security weaknesses created by passwords. 162 o Third-party applications gain overly broad access to the resource 163 owner's protected resources, leaving resource owners without any 164 ability to restrict duration or access to a limited subset of 165 resources. 166 o Resource owners cannot revoke access to an individual third-party 167 without revoking access to all third-parties, and must do so by 168 changing their password. 169 o Compromise of any third-party application results in compromise of 170 the end-user's password and all of the data protected by that 171 password. 173 OAuth addresses these issues by introducing an authorization layer 174 and separating the role of the client from that of the resource 175 owner. In OAuth, the client requests access to resources controlled 176 by the resource owner and hosted by the resource server, and is 177 issued a different set of credentials than those of the resource 178 owner. 180 Instead of using the resource owner's credentials to access protected 181 resources, the client obtains an access token - a string denoting a 182 specific scope, lifetime, and other access attributes. Access tokens 183 are issued to third-party clients by an authorization server with the 184 approval of the resource owner. The client uses the access token to 185 access the protected resources hosted by the resource server. 187 For example, an end-user (resource owner) can grant a printing 188 service (client) access to her protected photos stored at a photo 189 sharing service (resource server), without sharing her username and 190 password with the printing service. Instead, she authenticates 191 directly with a server trusted by the photo sharing service 192 (authorization server) which issues the printing service delegation- 193 specific credentials (access token). 195 This specification is designed for use with HTTP [RFC2616]. The use 196 of OAuth with any transport protocol other than HTTP is undefined. 198 1.1. Roles 200 OAuth defines four roles: 202 resource owner 203 An entity capable of granting access to a protected resource (e.g. 204 end-user). 205 resource server 206 The server hosting the protected resources, capable of accepting 207 and responding to protected resource requests using access tokens. 208 client 209 An application making protected resource requests on behalf of the 210 resource owner and with its authorization. 211 authorization server 212 The server issuing access tokens to the client after successfully 213 authenticating the resource owner and obtaining authorization. 215 The interaction between the authorization server and resource server 216 is beyond the scope of this specification. The authorization server 217 may be the same server as the resource server or a separate entity. 218 A single authorization server may issue access tokens accepted by 219 multiple resource servers. 221 1.2. Protocol Flow 223 +--------+ +---------------+ 224 | |--(A)- Authorization Request ->| Resource | 225 | | | Owner | 226 | |<-(B)-- Authorization Grant ---| | 227 | | +---------------+ 228 | | 229 | | +---------------+ 230 | |--(C)-- Authorization Grant -->| Authorization | 231 | Client | | Server | 232 | |<-(D)----- Access Token -------| | 233 | | +---------------+ 234 | | 235 | | +---------------+ 236 | |--(E)----- Access Token ------>| Resource | 237 | | | Server | 238 | |<-(F)--- Protected Resource ---| | 239 +--------+ +---------------+ 241 Figure 1: Abstract Protocol Flow 243 The abstract flow illustrated in Figure 1 describes the interaction 244 between the four roles and includes the following steps: 246 (A) The client requests authorization from the resource owner. The 247 authorization request can be made directly to the resource owner 248 (as shown), or preferably indirectly via the authorization 249 server as an intermediary. 250 (B) The client receives an authorization grant which is a credential 251 representing the resource owner's authorization, expressed using 252 one of four grant types defined in this specification or using 253 an extension grant type. The authorization grant type depends 254 on the method used by the client to request authorization and 255 the types supported by the authorization server. 256 (C) The client requests an access token by authenticating with the 257 authorization server and presenting the authorization grant. 258 (D) The authorization server authenticates the client and validates 259 the authorization grant, and if valid issues an access token. 260 (E) The client requests the protected resource from the resource 261 server and authenticates by presenting the access token. 262 (F) The resource server validates the access token, and if valid, 263 serves the request. 265 1.3. Authorization Grant 267 An authorization grant is a credential representing the resource 268 owner's authorization (to access its protected resources) used by the 269 client to obtain an access token. This specification defines four 270 grant types: authorization code, implicit, resource owner password 271 credentials, and client credentials, as well as an extensibility 272 mechanism for defining additional types. 274 1.3.1. Authorization Code 276 The authorization code is obtained by using an authorization server 277 as an intermediary between the client and resource owner. Instead of 278 requesting authorization directly from the resource owner, the client 279 directs the resource owner to an authorization server (via its user- 280 agent as defined in [RFC2616]), which in turn directs the resource 281 owner back to the client with the authorization code. 283 Before directing the resource owner back to the client with the 284 authorization code, the authorization server authenticates the 285 resource owner and obtains authorization. Because the resource owner 286 only authenticates with the authorization server, the resource 287 owner's credentials are never shared with the client. 289 The authorization code provides a few important security benefits 290 such as the ability to authenticate the client, and the transmission 291 of the access token directly to the client without passing it through 292 the resource owner's user-agent, potentially exposing it to others, 293 including the resource owner. 295 1.3.2. Implicit 297 The implicit grant is a simplified authorization code flow optimized 298 for clients implemented in a browser using a scripting language such 299 as JavaScript. In the implicit flow, instead of issuing the client 300 an authorization code, the client is issued an access token directly 301 (as the result of the resource owner authorization). The grant type 302 is implicit as no intermediate credentials (such as an authorization 303 code) are issued (and later used to obtain an access token). 305 When issuing an implicit grant, the authorization server does not 306 authenticate the client. In some cases, the client identity can be 307 verified via the redirection URI used to deliver the access token to 308 the client. The access token may be exposed to the resource owner or 309 other applications with access to the resource owner's user-agent. 311 Implicit grants improve the responsiveness and efficiency of some 312 clients (such as a client implemented as an in-browser application) 313 since it reduces the number of round trips required to obtain an 314 access token. However, this convenience should be weighed against 315 the security implications of using implicit grants, especially when 316 the authorization code grant type is available. 318 1.3.3. Resource Owner Password Credentials 320 The resource owner password credentials (i.e. username and password) 321 can be used directly as an authorization grant to obtain an access 322 token. The credentials should only be used when there is a high 323 degree of trust between the resource owner and the client (e.g. its 324 device operating system or a highly privileged application), and when 325 other authorization grant types are not available (such as an 326 authorization code). 328 Even though this grant type requires direct client access to the 329 resource owner credentials, the resource owner credentials are used 330 for a single request and are exchanged for an access token. This 331 grant type can eliminate the need for the client to store the 332 resource owner credentials for future use, by exchanging the 333 credentials with a long-lived access token or refresh token. 335 1.3.4. Client Credentials 337 The client credentials (or other forms of client authentication) can 338 be used as an authorization grant when the authorization scope is 339 limited to the protected resources under the control of the client, 340 or to protected resources previously arranged with the authorization 341 server. Client credentials are used as an authorization grant 342 typically when the client is acting on its own behalf (the client is 343 also the resource owner), or is requesting access to protected 344 resources based on an authorization previously arranged with the 345 authorization server. 347 1.4. Access Token 349 Access tokens are credentials used to access protected resources. An 350 access token is a string representing an authorization issued to the 351 client. The string is usually opaque to the client. Tokens 352 represent specific scopes and durations of access, granted by the 353 resource owner, and enforced by the resource server and authorization 354 server. 356 The token may denote an identifier used to retrieve the authorization 357 information, or self-contain the authorization information in a 358 verifiable manner (i.e. a token string consisting of some data and a 359 signature). Additional authentication credentials, which are beyond 360 the scope of this specification, may be required in order for the 361 client to use a token. 363 The access token provides an abstraction layer, replacing different 364 authorization constructs (e.g. username and password) with a single 365 token understood by the resource server. This abstraction enables 366 issuing access tokens more restrictive than the authorization grant 367 used to obtain them, as well as removing the resource server's need 368 to understand a wide range of authentication methods. 370 Access tokens can have different formats, structures, and methods of 371 utilization (e.g. cryptographic properties) based on the resource 372 server security requirements. Access token attributes and the 373 methods used to access protected resources are beyond the scope of 374 this specification and are defined by companion specifications. 376 1.5. Refresh Token 378 Refresh tokens are credentials used to obtain access tokens. Refresh 379 tokens are issued to the client by the authorization server and are 380 used to obtain a new access token when the current access token 381 becomes invalid or expires, or to obtain additional access tokens 382 with identical or narrower scope (access tokens may have a shorter 383 lifetime and fewer permissions than authorized by the resource 384 owner). Issuing a refresh token is optional. If the authorization 385 server issues a refresh token, it is included when issuing an access 386 token. 388 A refresh token is a string representing the authorization granted to 389 the client by the resource owner. The string is usually opaque to 390 the client. The token denotes an identifier used to retrieve the 391 authorization information. Unlike access tokens, refresh tokens are 392 intended for use only with authorization servers and are never sent 393 to resource servers. 395 +--------+ +---------------+ 396 | |--(A)------- Authorization Grant --------->| | 397 | | | | 398 | |<-(B)----------- Access Token -------------| | 399 | | & Refresh Token | | 400 | | | | 401 | | +----------+ | | 402 | |--(C)---- Access Token ---->| | | | 403 | | | | | | 404 | |<-(D)- Protected Resource --| Resource | | Authorization | 405 | Client | | Server | | Server | 406 | |--(E)---- Access Token ---->| | | | 407 | | | | | | 408 | |<-(F)- Invalid Token Error -| | | | 409 | | +----------+ | | 410 | | | | 411 | |--(G)----------- Refresh Token ----------->| | 412 | | | | 413 | |<-(H)----------- Access Token -------------| | 414 +--------+ & Optional Refresh Token +---------------+ 416 Figure 2: Refreshing an Expired Access Token 418 The flow illustrated in Figure 2 includes the following steps: 420 (A) The client requests an access token by authenticating with the 421 authorization server, and presenting an authorization grant. 422 (B) The authorization server authenticates the client and validates 423 the authorization grant, and if valid issues an access token and 424 a refresh token. 425 (C) The client makes a protected resource request to the resource 426 server by presenting the access token. 427 (D) The resource server validates the access token, and if valid, 428 serves the request. 429 (E) Steps (C) and (D) repeat until the access token expires. If the 430 client knows the access token expired, it skips to step (G), 431 otherwise it makes another protected resource request. 433 (F) Since the access token is invalid, the resource server returns 434 an invalid token error. 435 (G) The client requests a new access token by authenticating with 436 the authorization server and presenting the refresh token. The 437 client authentication requirements are based on the client type 438 and on the authorization server policies. 439 (H) The authorization server authenticates the client and validates 440 the refresh token, and if valid issues a new access token (and 441 optionally, a new refresh token). 443 1.6. Notational Conventions 445 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 446 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 447 specification are to be interpreted as described in [RFC2119]. 449 This specification uses the Augmented Backus-Naur Form (ABNF) 450 notation of [RFC5234]. 452 Certain security-related terms are to be understood in the sense 453 defined in [RFC4949]. These terms include, but are not limited to, 454 'attack', 'authentication', 'authorization', 'certificate', 455 'confidentiality', 'credential', 'encryption', 'identity', 'sign', 456 'signature', 'trust', 'validate', and 'verify'. 458 Unless otherwise noted, all the protocol parameter names and values 459 are case sensitive. 461 2. Client Registration 463 Before initiating the protocol, the client registers with the 464 authorization server. The means through which the client registers 465 with the authorization server are beyond the scope of this 466 specification, but typically involve end-user interaction with an 467 HTML registration form. 469 Client registration does not require a direct interaction between the 470 client and the authorization server. When supported by the 471 authorization server, registration can rely on other means for 472 establishing trust and obtaining the required client properties (e.g. 473 redirection URI, client type). For example, registration can be 474 accomplished using a self-issued or third-party-issued assertion, or 475 by the authorization server performing client discovery using a 476 trusted channel. 478 When registering a client, the client developer: 480 o specifies the client type as described in Section 2.1, 481 o provides its client redirection URIs as described in 482 Section 3.1.2, and 483 o includes any other information required by the authorization 484 server (e.g. application name, website, description, logo image, 485 the acceptance of legal terms). 487 2.1. Client Types 489 OAuth defines two client types, based on their ability to 490 authenticate securely with the authorization server (i.e. ability to 491 maintain the confidentiality of their client credentials): 493 confidential 494 Clients capable of maintaining the confidentiality of their 495 credentials (e.g. client implemented on a secure server with 496 restricted access to the client credentials), or capable of secure 497 client authentication using other means. 498 public 499 Clients incapable of maintaining the confidentiality of their 500 credentials (e.g. clients executing on the resource owner's device 501 such as an installed native application or a web browser-based 502 application), and incapable of secure client authentication via 503 any other means. 505 The client type designation is based on the authorization server's 506 definition of secure authentication and its acceptable exposure 507 levels of client credentials. 509 This specification has been designed around the following client 510 profiles: 512 web application 513 A web application is a confidential client running on a web 514 server. Resource owners access the client via an HTML user 515 interface rendered in a user-agent on the resource owner's device. 516 The client credentials as well as any access token issued to the 517 client are stored on the web server and are not exposed to or 518 accessible by the resource owner. 519 user-agent-based application 520 A user-agent-based application is a public client in which the 521 client code is downloaded from a web server and executes within a 522 user-agent (e.g. web browser) on the resource owner's device. 523 Protocol data and credentials are easily accessible (and often 524 visible) to the resource owner. Since such applications reside 525 within the user-agent, they can make seamless use of the user- 526 agent capabilities when requesting authorization. 528 native application 529 A native application is a public client installed and executed on 530 the resource owner's device. Protocol data and credentials are 531 accessible to the resource owner. It is assumed that any client 532 authentication credentials included in the application can be 533 extracted. On the other hand, dynamically issued credentials such 534 access tokens or refresh tokens can receive an acceptable level of 535 protection. At a minimum, these credentials are protected from 536 hostile servers which the application may interact with. On some 537 platform these credentials might be protected from other 538 applications residing on the same device. 540 2.2. Client Identifier 542 The authorization server issues the registered client a client 543 identifier - a unique string representing the registration 544 information provided by the client. The client identifier is not a 545 secret, it is exposed to the resource owner, and MUST NOT be used 546 alone for client authentication. 548 2.3. Client Authentication 550 If the client type is confidential, the client and authorization 551 server establish a client authentication method suitable for the 552 security requirements of the authorization server. The authorization 553 server MAY accept any form of client authentication meeting its 554 security requirements. 556 Confidential clients are typically issued (or establish) a set of 557 client credentials used for authenticating with the authorization 558 server (e.g. password, public/private key pair). 560 The authorization server SHOULD NOT make assumptions about the client 561 type or accept the type information provided without establishing 562 trust with the client or its developer. The authorization server MAY 563 establish a client authentication method with public clients. 564 However, the authorization server MUST NOT rely on public client 565 authentication for the purpose of identifying the client. 567 The client MUST NOT use more than one authentication method in each 568 request. 570 2.3.1. Client Password 572 Clients in possession of a client password MAY use the HTTP Basic 573 authentication scheme as defined in [RFC2617] to authenticate with 574 the authorization server. The client identifier is used as the 575 username, and the client password is used as the password. 577 For example (extra line breaks are for display purposes only): 579 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 581 Alternatively, the authorization server MAY allow including the 582 client credentials in the request body using the following 583 parameters: 585 client_id 586 REQUIRED. The client identifier issued to the client during 587 the registration process described by Section 2.2. 588 client_secret 589 REQUIRED. The client secret. The client MAY omit the 590 parameter if the client secret is an empty string. 592 Including the client credentials in the request body using the two 593 parameters is NOT RECOMMENDED, and should be limited to clients 594 unable to directly utilize the HTTP Basic authentication scheme (or 595 other password-based HTTP authentication schemes). 597 For example, requesting to refresh an access token (Section 6) using 598 the body parameters (extra line breaks are for display purposes 599 only): 601 POST /token HTTP/1.1 602 Host: server.example.com 603 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 605 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 606 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 608 The authorization server MUST require the use of a transport-layer 609 security mechanism when sending requests to the token endpoint, as 610 requests using this authentication method result in the transmission 611 of clear-text credentials. 613 Since this client authentication method involves a password, the 614 authorization server MUST protect any endpoint utilizing it against 615 brute force attacks. 617 2.3.2. Other Authentication Methods 619 The authorization server MAY support any suitable HTTP authentication 620 scheme matching its security requirements. When using other 621 authentication methods, the authorization server MUST define a 622 mapping between the client identifier (registration record) and 623 authentication scheme. 625 2.4. Unregistered Clients 627 This specification does not exclude the use of unregistered clients. 628 However, the use with such clients is beyond the scope of this 629 specification, and requires additional security analysis and review 630 of its interoperability impact. 632 3. Protocol Endpoints 634 The authorization process utilizes two endpoints (HTTP resources): 636 o Authorization endpoint - used to obtain authorization from the 637 resource owner via user-agent redirection. 638 o Token endpoint - used to exchange an authorization grant for an 639 access token, typically with client authentication. 641 Not every authorization grant type utilizes both endpoints. 642 Extension grant types MAY define additional endpoints as needed. 644 3.1. Authorization Endpoint 646 The authorization endpoint is used to interact with the resource 647 owner and obtain an authorization grant. The authorization server 648 MUST first verify the identity of the resource owner. The way in 649 which the authorization server authenticates the resource owner (e.g. 650 username and password login, session cookies) is beyond the scope of 651 this specification. 653 The means through which the client obtains the location of the 654 authorization endpoint are beyond the scope of this specification, 655 but the location is typically provided in the service documentation. 657 The endpoint URI MAY include an "application/x-www-form-urlencoded" 658 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 659 section 3.4), which MUST be retained when adding additional query 660 parameters. The endpoint URI MUST NOT include a fragment component. 662 Since requests to the authorization endpoint result in user 663 authentication and the transmission of clear-text credentials (in the 664 HTTP response), the authorization server MUST require the use of a 665 transport-layer security mechanism when sending requests to the 666 authorization endpoint. The authorization server MUST support TLS 667 1.0 ([RFC2246]), SHOULD support TLS 1.2 ([RFC5246]) and its future 668 replacements, and MAY support additional transport-layer mechanisms 669 meeting its security requirements. 671 The authorization server MUST support the use of the HTTP "GET" 672 method [RFC2616] for the authorization endpoint, and MAY support the 673 use of the "POST" method as well. 675 Parameters sent without a value MUST be treated as if they were 676 omitted from the request. The authorization server SHOULD ignore 677 unrecognized request parameters. Request and response parameters 678 MUST NOT be included more than once. 680 3.1.1. Response Type 682 The authorization endpoint is used by the authorization code grant 683 type and implicit grant type flows. The client informs the 684 authorization server of the desired grant type using the following 685 parameter: 687 response_type 688 REQUIRED. The value MUST be one of "code" for requesting an 689 authorization code as described by Section 4.1.1, "token" for 690 requesting an access token (implicit grant) as described by 691 Section 4.2.1, or a registered extension value as described by 692 Section 8.4. If the response type contains one or more space 693 characters (%x20), it is interpreted as a space-delimited list 694 of values, where the order of values does not matter (e.g. "a 695 b" is the same as "b a"). 697 If an authorization request is missing the "response_type" parameter, 698 the authorization server SHOULD return an error response as described 699 in Section 4.1.2.1. 701 3.1.2. Redirection Endpoint 703 After completing its interaction with the resource owner, the 704 authorization server directs the resource owner's user-agent back to 705 the client. The authorization server redirects the user-agent to the 706 client's redirection endpoint previously established with the 707 authorization server during the client registration process or when 708 making the authorization request. 710 The redirection endpoint URI MUST be an absolute URI as defined by 711 [RFC3986] section 4.3. The endpoint URI MAY include an 712 "application/x-www-form-urlencoded" formatted 713 ([W3C.REC-html401-19991224]) query component ([RFC3986] section 3.4), 714 which MUST be retained when adding additional query parameters. The 715 endpoint URI MUST NOT include a fragment component. 717 3.1.2.1. Endpoint Request Confidentiality 719 If a redirection request will result in the transmission of an 720 authorization code or access token over an open network (between the 721 resource owner's user-agent and the client), the client SHOULD 722 require the use of a transport-layer security mechanism. 724 Lack of transport-layer security can have a severe impact on the 725 security of the client and the protected resources it is authorized 726 to access. The use of transport-layer security is particularly 727 critical when the authorization process is used as a form of 728 delegated end-user authentication by the client (e.g. third-party 729 sign-in service). 731 3.1.2.2. Registration Requirements 733 The authorization server SHOULD require all clients to register their 734 redirection URI prior to using the authorization endpoint, and MUST 735 require the following clients to register their redirection URI: 737 o Public clients. 738 o Confidential clients utilizing the implicit grant type. 740 The authorization server SHOULD require the client to provide the 741 complete redirection URI (the client MAY use the "state" request 742 parameter to achieve per-request customization). The authorization 743 server MAY allow the client to register multiple redirection URIs. 744 If requiring the registration of the complete redirection URI is not 745 possible, the authorization server SHOULD require the registration of 746 the URI scheme, authority, and path (allowing the client to 747 dynamically change only the query component of the redirection URI 748 when requesting authorization). 750 3.1.2.3. Dynamic Configuration 752 If multiple redirection URIs have been registered, if only part of 753 the redirection URI has been registered, or if no redirection URI has 754 been registered, the client MUST include a redirection URI with the 755 authorization request using the "redirect_uri" request parameter. 757 When a redirection URI is included in an authorization request, the 758 authorization server MUST compare and match the value received 759 against at least one of the registered redirection URIs (or URI 760 components) as defined in [RFC3986] section 6, if any redirection 761 URIs were registered. If the client registration included the full 762 redirection URI, the authorization server MUST compare the two URIs 763 using simple string comparison as defined in [RFC3986] section 6.2.1. 765 If the authorization server allows the client to dynamically change 766 the query component of the redirection URI, the client MUST ensure 767 that manipulation of the query component by an attacker cannot lead 768 to an abuse of the redirection endpoint as described in 769 Section 10.15. 771 3.1.2.4. Invalid Endpoint 773 If an authorization request fails validation due to a missing, 774 invalid, or mismatching redirection URI, the authorization server 775 SHOULD inform the resource owner of the error, and MUST NOT 776 automatically redirect the user-agent to the invalid redirection URI. 778 The authorization server SHOULD NOT redirect the user-agent to 779 unregistered or untrusted URIs to prevent the authorization endpoint 780 from being used as an open redirector. 782 3.1.2.5. Endpoint Content 784 The redirection request to the client's endpoint typically results in 785 an HTML document response, processed by the user-agent. If the HTML 786 response is served directly as the result of the redirection request, 787 any script included in the HTML document will execute with full 788 access to the redirection URI and the credentials it contains. 790 The client MUST NOT include any untrusted third-party scripts in the 791 redirection endpoint response (e.g. third-party analytics, social 792 plug-ins, ad networks) without first ensuring that its own scripts 793 used to extract and remove the credentials from the URI will execute 794 first. 796 The client SHOULD NOT include any third-party scripts in the 797 redirection endpoint response. Instead, it should extract the 798 credentials from the URI and redirect the user-agent again to another 799 endpoint without the credentials in the URI. 801 3.2. Token Endpoint 803 The token endpoint is used by the client to obtain an access token by 804 presenting its authorization grant or refresh token. The token 805 endpoint is used with every authorization grant except for the 806 implicit grant type (since an access token is issued directly). 808 The means through which the client obtains the location of the token 809 endpoint are beyond the scope of this specification but is typically 810 provided in the service documentation. 812 The endpoint URI MAY include an "application/x-www-form-urlencoded" 813 formatted ([W3C.REC-html401-19991224]) query component ([RFC3986] 814 section 3.4), which MUST be retained when adding additional query 815 parameters. The endpoint URI MUST NOT include a fragment component. 817 Since requests to the token endpoint result in the transmission of 818 clear-text credentials (in the HTTP request and response), the 819 authorization server MUST require the use of a transport-layer 820 security mechanism when sending requests to the token endpoint. The 821 authorization server MUST support TLS 1.0 ([RFC2246]), SHOULD support 822 TLS 1.2 ([RFC5246]) and its future replacements, and MAY support 823 additional transport-layer mechanisms meeting its security 824 requirements. 826 The client MUST use the HTTP "POST" method when making access token 827 requests. 829 Parameters sent without a value MUST be treated as if they were 830 omitted from the request. The authorization server SHOULD ignore 831 unrecognized request parameters. Request and response parameters 832 MUST NOT be included more than once. 834 3.2.1. Client Authentication 836 Confidential clients, clients issued client credentials, or clients 837 assigned other authentication requirements MUST authenticate with the 838 authorization server as described in Section 2.3 when making requests 839 to the token endpoint. Client authentication is used for: 841 o Enforcing the binding of refresh tokens and authorization codes to 842 the client they are issued. Client authentication is critical 843 when an authorization code is transmitted to the redirection 844 endpoint over an insecure channel, or when the redirection URI has 845 not been registered in full. 846 o Recovering from a compromised client by disabling the client or 847 changing its credentials, thus preventing an attacker from abusing 848 stolen refresh tokens. Changing a single set of client 849 credentials is significantly faster than revoking an entire set of 850 refresh tokens. 851 o Implementing authentication management best practices which 852 require periodic credential rotation. Rotation of an entire set 853 of refresh tokens can be challenging, while rotation of a single 854 set of client credentials is significantly easier. 856 A public client that was not issued a client password MAY use the 857 "client_id" request parameter to identify itself when sending 858 requests to the token endpoint. 860 The security ramifications of allowing unauthenticated access by 861 public clients to the token endpoint, as well as the issuance of 862 refresh tokens to public clients MUST be taken into consideration. 864 3.3. Access Token Scope 866 The authorization and token endpoints allow the client to specify the 867 scope of the access request using the "scope" request parameter. In 868 turn, the authorization server uses the "scope" response parameter to 869 inform the client of the scope of the access token issued. 871 The value of the scope parameter is expressed as a list of space- 872 delimited, case sensitive strings. The strings are defined by the 873 authorization server. If the value contains multiple space-delimited 874 strings, their order does not matter, and each string adds an 875 additional access range to the requested scope. 877 The authorization server MAY fully or partially ignore the scope 878 requested by the client based on the authorization server policy or 879 the resource owner's instructions. If the issued access token scope 880 is different from the one requested by the client, the authorization 881 server SHOULD include the "scope" response parameter to inform the 882 client of the actual scope granted. 884 4. Obtaining Authorization 886 To request an access token, the client obtains authorization from the 887 resource owner. The authorization is expressed in the form of an 888 authorization grant which the client uses to request the access 889 token. OAuth defines four grant types: authorization code, implicit, 890 resource owner password credentials, and client credentials. It also 891 provides an extension mechanism for defining additional grant types. 893 4.1. Authorization Code 895 The authorization code grant type is used to obtain both access 896 tokens and refresh tokens and is optimized for confidential clients. 897 As a redirection-based flow, the client must be capable of 898 interacting with the resource owner's user-agent (typically a web 899 browser) and capable of receiving incoming requests (via redirection) 900 from the authorization server. 902 +----------+ 903 | resource | 904 | owner | 905 | | 906 +----------+ 907 ^ 908 | 909 (B) 910 +----|-----+ Client Identifier +---------------+ 911 | -+----(A)-- & Redirection URI ---->| | 912 | User- | | Authorization | 913 | Agent -+----(B)-- User authenticates --->| Server | 914 | | | | 915 | -+----(C)-- Authorization Code ---<| | 916 +-|----|---+ +---------------+ 917 | | ^ v 918 (A) (C) | | 919 | | | | 920 ^ v | | 921 +---------+ | | 922 | |>---(D)-- Authorization Code ---------' | 923 | Client | & Redirection URI | 924 | | | 925 | |<---(E)----- Access Token -------------------' 926 +---------+ (w/ Optional Refresh Token) 928 Figure 3: Authorization Code Flow 930 The flow illustrated in Figure 3 includes the following steps: 932 (A) The client initiates the flow by directing the resource owner's 933 user-agent to the authorization endpoint. The client includes 934 its client identifier, requested scope, local state, and a 935 redirection URI to which the authorization server will send the 936 user-agent back once access is granted (or denied). 937 (B) The authorization server authenticates the resource owner (via 938 the user-agent) and establishes whether the resource owner 939 grants or denies the client's access request. 940 (C) Assuming the resource owner grants access, the authorization 941 server redirects the user-agent back to the client using the 942 redirection URI provided earlier (in the request or during 943 client registration). The redirection URI includes an 944 authorization code and any local state provided by the client 945 earlier. 947 (D) The client requests an access token from the authorization 948 server's token endpoint by including the authorization code 949 received in the previous step. When making the request, the 950 client authenticates with the authorization server. The client 951 includes the redirection URI used to obtain the authorization 952 code for verification. 953 (E) The authorization server authenticates the client, validates the 954 authorization code, and ensures the redirection URI received 955 matches the URI used to redirect the client in step (C). If 956 valid, the authorization server responds back with an access 957 token and optional refresh token. 959 4.1.1. Authorization Request 961 The client constructs the request URI by adding the following 962 parameters to the query component of the authorization endpoint URI 963 using the "application/x-www-form-urlencoded" format as defined by 964 [W3C.REC-html401-19991224]: 966 response_type 967 REQUIRED. Value MUST be set to "code". 968 client_id 969 REQUIRED. The client identifier as described in Section 2.2. 970 redirect_uri 971 OPTIONAL, as described in Section 3.1.2. 972 scope 973 OPTIONAL. The scope of the access request as described by 974 Section 3.3. 975 state 976 RECOMMENDED. An opaque value used by the client to maintain 977 state between the request and callback. The authorization 978 server includes this value when redirecting the user-agent back 979 to the client. The parameter SHOULD be used for preventing 980 cross-site request forgery as described in Section 10.12. 982 The client directs the resource owner to the constructed URI using an 983 HTTP redirection response, or by other means available to it via the 984 user-agent. 986 For example, the client directs the user-agent to make the following 987 HTTP request using transport-layer security (extra line breaks are 988 for display purposes only): 990 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 991 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 992 Host: server.example.com 994 The authorization server validates the request to ensure all required 995 parameters are present and valid. If the request is valid, the 996 authorization server authenticates the resource owner and obtains an 997 authorization decision (by asking the resource owner or by 998 establishing approval via other means). 1000 When a decision is established, the authorization server directs the 1001 user-agent to the provided client redirection URI using an HTTP 1002 redirection response, or by other means available to it via the user- 1003 agent. 1005 4.1.2. Authorization Response 1007 If the resource owner grants the access request, the authorization 1008 server issues an authorization code and delivers it to the client by 1009 adding the following parameters to the query component of the 1010 redirection URI using the "application/x-www-form-urlencoded" format: 1012 code 1013 REQUIRED. The authorization code generated by the 1014 authorization server. The authorization code MUST expire 1015 shortly after it is issued to mitigate the risk of leaks. A 1016 maximum authorization code lifetime of 10 minutes is 1017 RECOMMENDED. The client MUST NOT use the authorization code 1018 more than once. If an authorization code is used more than 1019 once, the authorization server MUST deny the request and SHOULD 1020 attempt to revoke all tokens previously issued based on that 1021 authorization code. The authorization code is bound to the 1022 client identifier and redirection URI. 1023 state 1024 REQUIRED if the "state" parameter was present in the client 1025 authorization request. The exact value received from the 1026 client. 1028 For example, the authorization server redirects the user-agent by 1029 sending the following HTTP response: 1031 HTTP/1.1 302 Found 1032 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 1033 &state=xyz 1035 The client SHOULD ignore unrecognized response parameters. The 1036 authorization code string size is left undefined by this 1037 specification. The client should avoid making assumptions about code 1038 value sizes. The authorization server should document the size of 1039 any value it issues. 1041 4.1.2.1. Error Response 1043 If the request fails due to a missing, invalid, or mismatching 1044 redirection URI, or if the client identifier provided is invalid, the 1045 authorization server SHOULD inform the resource owner of the error, 1046 and MUST NOT automatically redirect the user-agent to the invalid 1047 redirection URI. 1049 If the resource owner denies the access request or if the request 1050 fails for reasons other than a missing or invalid redirection URI, 1051 the authorization server informs the client by adding the following 1052 parameters to the query component of the redirection URI using the 1053 "application/x-www-form-urlencoded" format: 1055 error 1056 REQUIRED. A single error code from the following: 1057 invalid_request 1058 The request is missing a required parameter, includes an 1059 unsupported parameter value, or is otherwise malformed. 1060 unauthorized_client 1061 The client is not authorized to request an authorization 1062 code using this method. 1063 access_denied 1064 The resource owner or authorization server denied the 1065 request. 1066 unsupported_response_type 1067 The authorization server does not support obtaining an 1068 authorization code using this method. 1069 invalid_scope 1070 The requested scope is invalid, unknown, or malformed. 1071 server_error 1072 The authorization server encountered an unexpected 1073 condition which prevented it from fulfilling the request. 1074 temporarily_unavailable 1075 The authorization server is currently unable to handle 1076 the request due to a temporary overloading or maintenance 1077 of the server. 1078 error_description 1079 OPTIONAL. A human-readable UTF-8 encoded text providing 1080 additional information, used to assist the client developer in 1081 understanding the error that occurred. 1082 error_uri 1083 OPTIONAL. A URI identifying a human-readable web page with 1084 information about the error, used to provide the client 1085 developer with additional information about the error. 1087 state 1088 REQUIRED if a valid "state" parameter was present in the client 1089 authorization request. The exact value received from the 1090 client. 1092 For example, the authorization server redirects the user-agent by 1093 sending the following HTTP response: 1095 HTTP/1.1 302 Found 1096 Location: https://client.example.com/cb?error=access_denied&state=xyz 1098 4.1.3. Access Token Request 1100 The client makes a request to the token endpoint by adding the 1101 following parameters using the "application/x-www-form-urlencoded" 1102 format in the HTTP request entity-body: 1104 grant_type 1105 REQUIRED. Value MUST be set to "authorization_code". 1106 code 1107 REQUIRED. The authorization code received from the 1108 authorization server. 1109 redirect_uri 1110 REQUIRED, if the "redirect_uri" parameter was included in the 1111 authorization request as described in Section 4.1.1, and their 1112 values MUST be identical. 1114 If the client type is confidential or the client was issued client 1115 credentials (or assigned other authentication requirements), the 1116 client MUST authenticate with the authorization server as described 1117 in Section 3.2.1. 1119 For example, the client makes the following HTTP request using 1120 transport-layer security (extra line breaks are for display purposes 1121 only): 1123 POST /token HTTP/1.1 1124 Host: server.example.com 1125 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1126 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1128 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1129 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1131 The authorization server MUST: 1133 o require client authentication for confidential clients or for any 1134 client that was issued client credentials (or with other 1135 authentication requirements), 1136 o authenticate the client if client authentication is included and 1137 ensure the authorization code was issued to the authenticated 1138 client, 1139 o verify that the authorization code is valid, and 1140 o ensure that the "redirect_uri" parameter is present if the 1141 "redirect_uri" parameter was included in the initial authorization 1142 request as described in Section 4.1.1, and if included ensure 1143 their values are identical. 1145 4.1.4. Access Token Response 1147 If the access token request is valid and authorized, the 1148 authorization server issues an access token and optional refresh 1149 token as described in Section 5.1. If the request client 1150 authentication failed or is invalid, the authorization server returns 1151 an error response as described in Section 5.2. 1153 An example successful response: 1155 HTTP/1.1 200 OK 1156 Content-Type: application/json;charset=UTF-8 1157 Cache-Control: no-store 1158 Pragma: no-cache 1160 { 1161 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1162 "token_type":"example", 1163 "expires_in":3600, 1164 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1165 "example_parameter":"example_value" 1166 } 1168 4.2. Implicit Grant 1170 The implicit grant type is used to obtain access tokens (it does not 1171 support the issuance of refresh tokens) and is optimized for public 1172 clients known to operate a particular redirection URI. These clients 1173 are typically implemented in a browser using a scripting language 1174 such as JavaScript. 1176 As a redirection-based flow, the client must be capable of 1177 interacting with the resource owner's user-agent (typically a web 1178 browser) and capable of receiving incoming requests (via redirection) 1179 from the authorization server. 1181 Unlike the authorization code grant type in which the client makes 1182 separate requests for authorization and access token, the client 1183 receives the access token as the result of the authorization request. 1185 The implicit grant type does not include client authentication, and 1186 relies on the presence of the resource owner and the registration of 1187 the redirection URI. Because the access token is encoded into the 1188 redirection URI, it may be exposed to the resource owner and other 1189 applications residing on its device. 1191 +----------+ 1192 | Resource | 1193 | Owner | 1194 | | 1195 +----------+ 1196 ^ 1197 | 1198 (B) 1199 +----|-----+ Client Identifier +---------------+ 1200 | -+----(A)-- & Redirection URI --->| | 1201 | User- | | Authorization | 1202 | Agent -|----(B)-- User authenticates -->| Server | 1203 | | | | 1204 | |<---(C)--- Redirection URI ----<| | 1205 | | with Access Token +---------------+ 1206 | | in Fragment 1207 | | +---------------+ 1208 | |----(D)--- Redirection URI ---->| Web-Hosted | 1209 | | without Fragment | Client | 1210 | | | Resource | 1211 | (F) |<---(E)------- Script ---------<| | 1212 | | +---------------+ 1213 +-|--------+ 1214 | | 1215 (A) (G) Access Token 1216 | | 1217 ^ v 1218 +---------+ 1219 | | 1220 | Client | 1221 | | 1222 +---------+ 1223 Figure 4: Implicit Grant Flow 1225 The flow illustrated in Figure 4 includes the following steps: 1227 (A) The client initiates the flow by directing the resource owner's 1228 user-agent to the authorization endpoint. The client includes 1229 its client identifier, requested scope, local state, and a 1230 redirection URI to which the authorization server will send the 1231 user-agent back once access is granted (or denied). 1232 (B) The authorization server authenticates the resource owner (via 1233 the user-agent) and establishes whether the resource owner 1234 grants or denies the client's access request. 1235 (C) Assuming the resource owner grants access, the authorization 1236 server redirects the user-agent back to the client using the 1237 redirection URI provided earlier. The redirection URI includes 1238 the access token in the URI fragment. 1239 (D) The user-agent follows the redirection instructions by making a 1240 request to the web-hosted client resource (which does not 1241 include the fragment). The user-agent retains the fragment 1242 information locally. 1243 (E) The web-hosted client resource returns a web page (typically an 1244 HTML document with an embedded script) capable of accessing the 1245 full redirection URI including the fragment retained by the 1246 user-agent, and extracting the access token (and other 1247 parameters) contained in the fragment. 1248 (F) The user-agent executes the script provided by the web-hosted 1249 client resource locally, which extracts the access token and 1250 passes it to the client. 1252 4.2.1. Authorization Request 1254 The client constructs the request URI by adding the following 1255 parameters to the query component of the authorization endpoint URI 1256 using the "application/x-www-form-urlencoded" format: 1258 response_type 1259 REQUIRED. Value MUST be set to "token". 1260 client_id 1261 REQUIRED. The client identifier as described in Section 2.2. 1262 redirect_uri 1263 OPTIONAL, as described in Section 3.1.2. 1264 scope 1265 OPTIONAL. The scope of the access request as described by 1266 Section 3.3. 1268 state 1269 RECOMMENDED. An opaque value used by the client to maintain 1270 state between the request and callback. The authorization 1271 server includes this value when redirecting the user-agent back 1272 to the client. The parameter SHOULD be used for preventing 1273 cross-site request forgery as described in Section 10.12. 1275 The client directs the resource owner to the constructed URI using an 1276 HTTP redirection response, or by other means available to it via the 1277 user-agent. 1279 For example, the client directs the user-agent to make the following 1280 HTTP request using transport-layer security (extra line breaks are 1281 for display purposes only): 1283 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1284 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1285 Host: server.example.com 1287 The authorization server validates the request to ensure all required 1288 parameters are present and valid. The authorization server MUST 1289 verify that the redirection URI to which it will redirect the access 1290 token matches a redirection URI registered by the client as described 1291 in Section 3.1.2. 1293 If the request is valid, the authorization server authenticates the 1294 resource owner and obtains an authorization decision (by asking the 1295 resource owner or by establishing approval via other means). 1297 When a decision is established, the authorization server directs the 1298 user-agent to the provided client redirection URI using an HTTP 1299 redirection response, or by other means available to it via the user- 1300 agent. 1302 4.2.2. Access Token Response 1304 If the resource owner grants the access request, the authorization 1305 server issues an access token and delivers it to the client by adding 1306 the following parameters to the fragment component of the redirection 1307 URI using the "application/x-www-form-urlencoded" format: 1309 access_token 1310 REQUIRED. The access token issued by the authorization server. 1312 token_type 1313 REQUIRED. The type of the token issued as described in 1314 Section 7.1. Value is case insensitive. 1315 expires_in 1316 OPTIONAL. The lifetime in seconds of the access token. For 1317 example, the value "3600" denotes that the access token will 1318 expire in one hour from the time the response was generated. 1319 scope 1320 OPTIONAL. The scope of the access token as described by 1321 Section 3.3. 1322 state 1323 REQUIRED if the "state" parameter was present in the client 1324 authorization request. The exact value received from the 1325 client. 1327 The authorization server MUST NOT issue a refresh token. 1329 For example, the authorization server redirects the user-agent by 1330 sending the following HTTP response (URI extra line breaks are for 1331 display purposes only): 1333 HTTP/1.1 302 Found 1334 Location: http://example.com/rd#access_token=2YotnFZFEjr1zCsicMWpAA 1335 &state=xyz&token_type=example&expires_in=3600 1337 Developers should note that some HTTP client implementations do not 1338 support the inclusion of a fragment component in the HTTP "Location" 1339 response header field. Such client will require using other methods 1340 for redirecting the client than a 3xx redirection response. For 1341 example, returning an HTML page which includes a 'continue' button 1342 with an action linked to the redirection URI. 1344 The client SHOULD ignore unrecognized response parameters. The 1345 access token string size is left undefined by this specification. 1346 The client should avoid making assumptions about value sizes. The 1347 authorization server should document the size of any value it issues. 1349 4.2.2.1. Error Response 1351 If the request fails due to a missing, invalid, or mismatching 1352 redirection URI, or if the client identifier provided is invalid, the 1353 authorization server SHOULD inform the resource owner of the error, 1354 and MUST NOT automatically redirect the user-agent to the invalid 1355 redirection URI. 1357 If the resource owner denies the access request or if the request 1358 fails for reasons other than a missing or invalid redirection URI, 1359 the authorization server informs the client by adding the following 1360 parameters to the fragment component of the redirection URI using the 1361 "application/x-www-form-urlencoded" format: 1363 error 1364 REQUIRED. A single error code from the following: 1365 invalid_request 1366 The request is missing a required parameter, includes an 1367 unsupported parameter value, or is otherwise malformed. 1368 unauthorized_client 1369 The client is not authorized to request an access token 1370 using this method. 1371 access_denied 1372 The resource owner or authorization server denied the 1373 request. 1374 unsupported_response_type 1375 The authorization server does not support obtaining an 1376 access token using this method. 1377 invalid_scope 1378 The requested scope is invalid, unknown, or malformed. 1379 server_error 1380 The authorization server encountered an unexpected 1381 condition which prevented it from fulfilling the request. 1382 temporarily_unavailable 1383 The authorization server is currently unable to handle 1384 the request due to a temporary overloading or maintenance 1385 of the server. 1386 error_description 1387 OPTIONAL. A human-readable UTF-8 encoded text providing 1388 additional information, used to assist the client developer in 1389 understanding the error that occurred. 1390 error_uri 1391 OPTIONAL. A URI identifying a human-readable web page with 1392 information about the error, used to provide the client 1393 developer with additional information about the error. 1394 state 1395 REQUIRED if a valid "state" parameter was present in the client 1396 authorization request. The exact value received from the 1397 client. 1399 For example, the authorization server redirects the user-agent by 1400 sending the following HTTP response: 1402 HTTP/1.1 302 Found 1403 Location: https://client.example.com/cb#error=access_denied&state=xyz 1405 4.3. Resource Owner Password Credentials 1407 The resource owner password credentials grant type is suitable in 1408 cases where the resource owner has a trust relationship with the 1409 client, such as its device operating system or a highly privileged 1410 application. The authorization server should take special care when 1411 enabling this grant type, and only allow it when other flows are not 1412 viable. 1414 The grant type is suitable for clients capable of obtaining the 1415 resource owner's credentials (username and password, typically using 1416 an interactive form). It is also used to migrate existing clients 1417 using direct authentication schemes such as HTTP Basic or Digest 1418 authentication to OAuth by converting the stored credentials to an 1419 access token. 1421 +----------+ 1422 | Resource | 1423 | Owner | 1424 | | 1425 +----------+ 1426 v 1427 | Resource Owner 1428 (A) Password Credentials 1429 | 1430 v 1431 +---------+ +---------------+ 1432 | |>--(B)---- Resource Owner ------->| | 1433 | | Password Credentials | Authorization | 1434 | Client | | Server | 1435 | |<--(C)---- Access Token ---------<| | 1436 | | (w/ Optional Refresh Token) | | 1437 +---------+ +---------------+ 1439 Figure 5: Resource Owner Password Credentials Flow 1441 The flow illustrated in Figure 5 includes the following steps: 1443 (A) The resource owner provides the client with its username and 1444 password. 1445 (B) The client requests an access token from the authorization 1446 server's token endpoint by including the credentials received 1447 from the resource owner. When making the request, the client 1448 authenticates with the authorization server. 1450 (C) The authorization server authenticates the client and validates 1451 the resource owner credentials, and if valid issues an access 1452 token. 1454 4.3.1. Authorization Request and Response 1456 The method through which the client obtains the resource owner 1457 credentials is beyond the scope of this specification. The client 1458 MUST discard the credentials once an access token has been obtained. 1460 4.3.2. Access Token Request 1462 The client makes a request to the token endpoint by adding the 1463 following parameters using the "application/x-www-form-urlencoded" 1464 format in the HTTP request entity-body: 1466 grant_type 1467 REQUIRED. Value MUST be set to "password". 1468 username 1469 REQUIRED. The resource owner username, encoded as UTF-8. 1470 password 1471 REQUIRED. The resource owner password, encoded as UTF-8. 1472 scope 1473 OPTIONAL. The scope of the access request as described by 1474 Section 3.3. 1476 If the client type is confidential or the client was issued client 1477 credentials (or assigned other authentication requirements), the 1478 client MUST authenticate with the authorization server as described 1479 in Section 3.2.1. 1481 For example, the client makes the following HTTP request using 1482 transport-layer security (extra line breaks are for display purposes 1483 only): 1485 POST /token HTTP/1.1 1486 Host: server.example.com 1487 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1488 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1490 grant_type=password&username=johndoe&password=A3ddj3w 1492 The authorization server MUST: 1494 o require client authentication for confidential clients or for any 1495 client that was issued client credentials (or with other 1496 authentication requirements), 1497 o authenticate the client if client authentication is included, and 1498 o validate the resource owner password credentials. 1500 Since this access token request utilizes the resource owner's 1501 password, the authorization server MUST protect the endpoint against 1502 brute force attacks. 1504 4.3.3. Access Token Response 1506 If the access token request is valid and authorized, the 1507 authorization server issues an access token and optional refresh 1508 token as described in Section 5.1. If the request failed client 1509 authentication or is invalid, the authorization server returns an 1510 error response as described in Section 5.2. 1512 An example successful response: 1514 HTTP/1.1 200 OK 1515 Content-Type: application/json;charset=UTF-8 1516 Cache-Control: no-store 1517 Pragma: no-cache 1519 { 1520 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1521 "token_type":"example", 1522 "expires_in":3600, 1523 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1524 "example_parameter":"example_value" 1525 } 1527 4.4. Client Credentials 1529 The client can request an access token using only its client 1530 credentials (or other supported means of authentication) when the 1531 client is requesting access to the protected resources under its 1532 control, or those of another resource owner which has been previously 1533 arranged with the authorization server (the method of which is beyond 1534 the scope of this specification). 1536 The client credentials grant type MUST only be used by confidential 1537 clients. 1539 +---------+ +---------------+ 1540 | | | | 1541 | |>--(A)- Client Authentication --->| Authorization | 1542 | Client | | Server | 1543 | |<--(B)---- Access Token ---------<| | 1544 | | | | 1545 +---------+ +---------------+ 1547 Figure 6: Client Credentials Flow 1549 The flow illustrated in Figure 6 includes the following steps: 1551 (A) The client authenticates with the authorization server and 1552 requests an access token from the token endpoint. 1553 (B) The authorization server authenticates the client, and if valid 1554 issues an access token. 1556 4.4.1. Authorization Request and Response 1558 Since the client authentication is used as the authorization grant, 1559 no additional authorization request is needed. 1561 4.4.2. Access Token Request 1563 The client makes a request to the token endpoint by adding the 1564 following parameters using the "application/x-www-form-urlencoded" 1565 format in the HTTP request entity-body: 1567 grant_type 1568 REQUIRED. Value MUST be set to "client_credentials". 1569 scope 1570 OPTIONAL. The scope of the access request as described by 1571 Section 3.3. 1573 The client MUST authenticate with the authorization server as 1574 described in Section 3.2.1. 1576 For example, the client makes the following HTTP request using 1577 transport-layer security (extra line breaks are for display purposes 1578 only): 1580 POST /token HTTP/1.1 1581 Host: server.example.com 1582 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1583 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1584 grant_type=client_credentials 1586 The authorization server MUST authenticate the client. 1588 4.4.3. Access Token Response 1590 If the access token request is valid and authorized, the 1591 authorization server issues an access token as described in 1592 Section 5.1. A refresh token SHOULD NOT be included. If the request 1593 failed client authentication or is invalid, the authorization server 1594 returns an error response as described in Section 5.2. 1596 An example successful response: 1598 HTTP/1.1 200 OK 1599 Content-Type: application/json;charset=UTF-8 1600 Cache-Control: no-store 1601 Pragma: no-cache 1603 { 1604 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1605 "token_type":"example", 1606 "expires_in":3600, 1607 "example_parameter":"example_value" 1608 } 1610 4.5. Extensions 1612 The client uses an extension grant type by specifying the grant type 1613 using an absolute URI (defined by the authorization server) as the 1614 value of the "grant_type" parameter of the token endpoint, and by 1615 adding any additional parameters necessary. 1617 For example, to request an access token using a SAML 2.0 assertion 1618 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1619 makes the following HTTP request using transport-layer security (line 1620 breaks are for display purposes only): 1622 POST /token HTTP/1.1 1623 Host: server.example.com 1624 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1626 grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Asaml2- 1627 bearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ9IjIwMTEtMDU 1629 [...omitted for brevity...]aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1631 If the access token request is valid and authorized, the 1632 authorization server issues an access token and optional refresh 1633 token as described in Section 5.1. If the request failed client 1634 authentication or is invalid, the authorization server returns an 1635 error response as described in Section 5.2. 1637 5. Issuing an Access Token 1639 If the access token request is valid and authorized, the 1640 authorization server issues an access token and optional refresh 1641 token as described in Section 5.1. If the request failed client 1642 authentication or is invalid, the authorization server returns an 1643 error response as described in Section 5.2. 1645 5.1. Successful Response 1647 The authorization server issues an access token and optional refresh 1648 token, and constructs the response by adding the following parameters 1649 to the entity body of the HTTP response with a 200 (OK) status code: 1651 access_token 1652 REQUIRED. The access token issued by the authorization server. 1653 token_type 1654 REQUIRED. The type of the token issued as described in 1655 Section 7.1. Value is case insensitive. 1656 expires_in 1657 OPTIONAL. The lifetime in seconds of the access token. For 1658 example, the value "3600" denotes that the access token will 1659 expire in one hour from the time the response was generated. 1660 refresh_token 1661 OPTIONAL. The refresh token which can be used to obtain new 1662 access tokens using the same authorization grant as described 1663 in Section 6. 1664 scope 1665 OPTIONAL. The scope of the access token as described by 1666 Section 3.3. 1668 The parameters are included in the entity body of the HTTP response 1669 using the "application/json" media type as defined by [RFC4627]. The 1670 parameters are serialized into a JSON structure by adding each 1671 parameter at the highest structure level. Parameter names and string 1672 values are included as JSON strings. Numerical values are included 1673 as JSON numbers. The order of parameters does not matter and can 1674 vary. 1676 The authorization server MUST include the HTTP "Cache-Control" 1677 response header field [RFC2616] with a value of "no-store" in any 1678 response containing tokens, credentials, or other sensitive 1679 information, as well as the "Pragma" response header field [RFC2616] 1680 with a value of "no-cache". 1682 For example: 1684 HTTP/1.1 200 OK 1685 Content-Type: application/json;charset=UTF-8 1686 Cache-Control: no-store 1687 Pragma: no-cache 1689 { 1690 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1691 "token_type":"example", 1692 "expires_in":3600, 1693 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1694 "example_parameter":"example_value" 1695 } 1697 The client SHOULD ignore unrecognized response parameters. The sizes 1698 of tokens and other values received from the authorization server are 1699 left undefined. The client should avoid making assumptions about 1700 value sizes. The authorization server should document the size of 1701 any value it issues. 1703 5.2. Error Response 1705 The authorization server responds with an HTTP 400 (Bad Request) 1706 status code and includes the following parameters with the response: 1708 error 1709 REQUIRED. A single error code from the following: 1710 invalid_request 1711 The request is missing a required parameter, includes an 1712 unsupported parameter value, repeats a parameter, 1713 includes multiple credentials, utilizes more than one 1714 mechanism for authenticating the client, or is otherwise 1715 malformed. 1716 invalid_client 1717 Client authentication failed (e.g. unknown client, no 1718 client authentication included, or unsupported 1719 authentication method). The authorization server MAY 1720 return an HTTP 401 (Unauthorized) status code to indicate 1721 which HTTP authentication schemes are supported. If the 1722 client attempted to authenticate via the "Authorization" 1723 request header field, the authorization server MUST 1724 respond with an HTTP 401 (Unauthorized) status code, and 1725 include the "WWW-Authenticate" response header field 1726 matching the authentication scheme used by the client. 1727 invalid_grant 1728 The provided authorization grant (e.g. authorization 1729 code, resource owner credentials, client credentials) is 1730 invalid, expired, revoked, does not match the redirection 1731 URI used in the authorization request, or was issued to 1732 another client. 1733 unauthorized_client 1734 The authenticated client is not authorized to use this 1735 authorization grant type. 1736 unsupported_grant_type 1737 The authorization grant type is not supported by the 1738 authorization server. 1739 invalid_scope 1740 The requested scope is invalid, unknown, malformed, or 1741 exceeds the scope granted by the resource owner. 1742 error_description 1743 OPTIONAL. A human-readable UTF-8 encoded text providing 1744 additional information, used to assist the client developer in 1745 understanding the error that occurred. 1746 error_uri 1747 OPTIONAL. A URI identifying a human-readable web page with 1748 information about the error, used to provide the client 1749 developer with additional information about the error. 1751 The parameters are included in the entity body of the HTTP response 1752 using the "application/json" media type as defined by [RFC4627]. The 1753 parameters are serialized into a JSON structure by adding each 1754 parameter at the highest structure level. Parameter names and string 1755 values are included as JSON strings. Numerical values are included 1756 as JSON numbers. The order of parameters does not matter and can 1757 vary. 1759 For example: 1761 HTTP/1.1 400 Bad Request 1762 Content-Type: application/json;charset=UTF-8 1763 Cache-Control: no-store 1764 Pragma: no-cache 1766 { 1767 "error":"invalid_request" 1768 } 1770 6. Refreshing an Access Token 1772 If the authorization server issued a refresh token to the client, the 1773 client makes a refresh request to the token endpoint by adding the 1774 following parameters using the "application/x-www-form-urlencoded" 1775 format in the HTTP request entity-body: 1777 grant_type 1778 REQUIRED. Value MUST be set to "refresh_token". 1779 refresh_token 1780 REQUIRED. The refresh token issued to the client. 1781 scope 1782 OPTIONAL. The scope of the access request as described by 1783 Section 3.3. The requested scope MUST NOT include any scope 1784 not originally granted by the resource owner, and if omitted is 1785 treated as equal to the scope originally granted by the 1786 resource owner. 1788 Because refresh tokens are typically long-lasting credentials used to 1789 request additional access tokens, the refresh token is bound to the 1790 client it was issued. If the client type is confidential or the 1791 client was issued client credentials (or assigned other 1792 authentication requirements), the client MUST authenticate with the 1793 authorization server as described in Section 3.2.1. 1795 For example, the client makes the following HTTP request using 1796 transport-layer security (extra line breaks are for display purposes 1797 only): 1799 POST /token HTTP/1.1 1800 Host: server.example.com 1801 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1802 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1804 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1806 The authorization server MUST: 1808 o require client authentication for confidential clients or for any 1809 client that was issued client credentials (or with other 1810 authentication requirements), 1811 o authenticate the client if client authentication is included and 1812 ensure the refresh token was issued to the authenticated client, 1813 and 1815 o validate the refresh token. 1817 If valid and authorized, the authorization server issues an access 1818 token as described in Section 5.1. If the request failed 1819 verification or is invalid, the authorization server returns an error 1820 response as described in Section 5.2. 1822 The authorization server MAY issue a new refresh token, in which case 1823 the client MUST discard the old refresh token and replace it with the 1824 new refresh token. The authorization server MAY revoke the old 1825 refresh token after issuing a new refresh token to the client. If a 1826 new refresh token is issued, the refresh token scope MUST be 1827 identical to that of the refresh token included by the client in the 1828 request. 1830 7. Accessing Protected Resources 1832 The client accesses protected resources by presenting the access 1833 token to the resource server. The resource server MUST validate the 1834 access token and ensure it has not expired and that its scope covers 1835 the requested resource. The methods used by the resource server to 1836 validate the access token (as well as any error responses) are beyond 1837 the scope of this specification, but generally involve an interaction 1838 or coordination between the resource server and the authorization 1839 server. 1841 The method in which the client utilized the access token to 1842 authenticate with the resource server depends on the type of access 1843 token issued by the authorization server. Typically, it involves 1844 using the HTTP "Authorization" request header field [RFC2617] with an 1845 authentication scheme defined by the access token type specification. 1847 7.1. Access Token Types 1849 The access token type provides the client with the information 1850 required to successfully utilize the access token to make a protected 1851 resource request (along with type-specific attributes). The client 1852 MUST NOT use an access token if it does not understand or does not 1853 trust the token type. 1855 For example, the "bearer" token type defined in 1856 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1857 token string in the request: 1859 GET /resource/1 HTTP/1.1 1860 Host: example.com 1861 Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw 1863 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 1864 utilized by issuing a MAC key together with the access token which is 1865 used to sign certain components of the HTTP requests: 1867 GET /resource/1 HTTP/1.1 1868 Host: example.com 1869 Authorization: MAC id="h480djs93hd8", 1870 nonce="274312:dj83hs9s", 1871 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1873 The above examples are provided for illustration purposes only. 1874 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 1875 [I-D.ietf-oauth-v2-http-mac] specifications before use. 1877 Each access token type definition specifies the additional attributes 1878 (if any) sent to the client together with the "access_token" response 1879 parameter. It also defines the HTTP authentication method used to 1880 include the access token when making a protected resource request. 1882 8. Extensibility 1884 8.1. Defining Access Token Types 1886 Access token types can be defined in one of two ways: registered in 1887 the access token type registry (following the procedures in 1888 Section 11.1), or by using a unique absolute URI as its name. 1890 Types utilizing a URI name SHOULD be limited to vendor-specific 1891 implementations that are not commonly applicable, and are specific to 1892 the implementation details of the resource server where they are 1893 used. 1895 All other types MUST be registered. Type names MUST conform to the 1896 type-name ABNF. If the type definition includes a new HTTP 1897 authentication scheme, the type name SHOULD be identical to the HTTP 1898 authentication scheme name (as defined by [RFC2617]). The token type 1899 "example" is reserved for use in examples. 1901 type-name = 1*name-char 1902 name-char = "-" / "." / "_" / DIGIT / ALPHA 1904 8.2. Defining New Endpoint Parameters 1906 New request or response parameters for use with the authorization 1907 endpoint or the token endpoint are defined and registered in the 1908 parameters registry following the procedure in Section 11.2. 1910 Parameter names MUST conform to the param-name ABNF and parameter 1911 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1912 to the syntax of an existing parameter). 1914 param-name = 1*name-char 1915 name-char = "-" / "." / "_" / DIGIT / ALPHA 1917 Unregistered vendor-specific parameter extensions that are not 1918 commonly applicable, and are specific to the implementation details 1919 of the authorization server where they are used SHOULD utilize a 1920 vendor-specific prefix that is not likely to conflict with other 1921 registered values (e.g. begin with 'companyname_'). 1923 8.3. Defining New Authorization Grant Types 1925 New authorization grant types can be defined by assigning them a 1926 unique absolute URI for use with the "grant_type" parameter. If the 1927 extension grant type requires additional token endpoint parameters, 1928 they MUST be registered in the OAuth parameters registry as described 1929 by Section 11.2. 1931 8.4. Defining New Authorization Endpoint Response Types 1933 New response types for use with the authorization endpoint are 1934 defined and registered in the authorization endpoint response type 1935 registry following the procedure in Section 11.3. Response type 1936 names MUST conform to the response-type ABNF. 1938 response-type = response-name *( SP response-name ) 1939 response-name = 1*response-char 1940 response-char = "_" / DIGIT / ALPHA 1942 If a response type contains one of more space characters (%x20), it 1943 is compared as a space-delimited list of values in which the order of 1944 values does not matter. Only one order of values can be registered, 1945 which covers all other arrangements of the same set of values. 1947 For example, the response type "token code" is left undefined by this 1948 specification. However, an extension can define and register the 1949 "token code" response type. Once registered, the same combination 1950 cannot be registered as "code token", but both values can be used to 1951 denote the same response type. 1953 8.5. Defining Additional Error Codes 1955 In cases where protocol extensions (i.e. access token types, 1956 extension parameters, or extension grant types) require additional 1957 error codes to be used with the authorization code grant error 1958 response (Section 4.1.2.1), the implicit grant error response 1959 (Section 4.2.2.1), or the token error response (Section 5.2), such 1960 error codes MAY be defined. 1962 Extension error codes MUST be registered (following the procedures in 1963 Section 11.4) if the extension they are used in conjunction with is a 1964 registered access token type, a registered endpoint parameter, or an 1965 extension grant type. Error codes used with unregistered extensions 1966 MAY be registered. 1968 Error codes MUST conform to the error-code ABNF, and SHOULD be 1969 prefixed by an identifying name when possible. For example, an error 1970 identifying an invalid value set to the extension parameter "example" 1971 should be named "example_invalid". 1973 error-code = ALPHA *error-char 1974 error-char = "-" / "." / "_" / DIGIT / ALPHA 1976 9. Native Applications 1978 Native applications are clients installed and executed on the 1979 resource owner's device (i.e. desktop application, native mobile 1980 application). Native applications may require special consideration 1981 related to security, platform capabilities, and overall end-user 1982 experience. 1984 The authorization endpoint requires interaction between the client 1985 and the resource owner's user-agent. Native applications can invoke 1986 an external user-agent or embed a user-agent within the application. 1987 For example: 1989 o External user-agent - the native application can capture the 1990 response from the authorization server using a redirection URI 1991 with a scheme registered with the operating system to invoke the 1992 client as the handler, manual copy-and-paste of the credentials, 1993 running a local web server, installing a user-agent extension, or 1994 by providing a redirection URI identifying a server-hosted 1995 resource under the client's control, which in turn makes the 1996 response available to the native application. 1997 o Embedded user-agent - the native application obtains the response 1998 by directly communicating with the embedded user-agent by 1999 monitoring state changes emitted during the resource load, or 2000 accessing the user-agent's cookies storage. 2002 When choosing between an external or embedded user-agent, developers 2003 should consider: 2005 o External user-agents may improve completion rate as the resource 2006 owner may already have an active session with the authorization 2007 server removing the need to re-authenticate. It provides a 2008 familiar end-user experience and functionality. The resource 2009 owner may also rely on user-agent features or extensions to assist 2010 with authentication (e.g. password manager, 2-factor device 2011 reader). 2012 o Embedded user-agents may offer improved usability, as they remove 2013 the need to switch context and open new windows. 2014 o Embedded user-agents pose a security challenge because resource 2015 owners are authenticating in an unidentified window without access 2016 to the visual protections found in most external user-agents. 2017 Embedded user-agents educate end-user to trust unidentified 2018 requests for authentication (making phishing attacks easier to 2019 execute). 2021 When choosing between the implicit grant type and the authorization 2022 code grant type, the following should be considered: 2024 o Native applications that use the authorization code grant type 2025 SHOULD do so without using client credentials, due to the native 2026 application's inability to keep client credentials confidential. 2027 o When using the implicit grant type flow a refresh token is not 2028 returned which requires repeating the authorization process once 2029 the access token expires. 2031 10. Security Considerations 2033 As a flexible and extensible framework, OAuth's security 2034 considerations depend on many factors. The following sections 2035 provide implementers with security guidelines focused on the three 2036 client profiles described in Section 2.1: web application, user- 2037 agent-based application, and native application. 2039 A comprehensive OAuth security model and analysis, as well as 2040 background for the protocol design is provided by 2041 [I-D.ietf-oauth-v2-threatmodel]. 2043 10.1. Client Authentication 2045 The authorization server establishes client credentials with web 2046 application clients for the purpose of client authentication. The 2047 authorization server is encouraged to consider stronger client 2048 authentication means than a client password. Web application clients 2049 MUST ensure confidentiality of client passwords and other client 2050 credentials. 2052 The authorization server MUST NOT issue client passwords or other 2053 client credentials to native application or user-agent-based 2054 application clients for the purpose of client authentication. The 2055 authorization server MAY issue a client password or other credentials 2056 for a specific installation of a native application client on a 2057 specific device. 2059 When client authentication is not possible, the authorization server 2060 SHOULD employ other means to validate the client's identity. For 2061 example, by requiring the registration of the client redirection URI 2062 or enlisting the resource owner to confirm identity. A valid 2063 redirection URI is not sufficient to verify the client's identity 2064 when asking for end-user authorization, but can be used to prevent 2065 delivering credentials to a counterfeit client after obtaining end- 2066 user authorization. 2068 The authorization server must consider the security implications of 2069 interacting with unauthenticated clients and take measures to limit 2070 the potential exposure of other credentials (e.g. refresh tokens) 2071 issued to such clients. 2073 10.2. Client Impersonation 2075 A malicious client can impersonate another client and obtain access 2076 to protected resources, if the impersonated client fails to, or is 2077 unable to, keep its client credentials confidential. 2079 The authorization server MUST authenticate the client whenever 2080 possible. If the authorization server cannot authenticate the client 2081 due to the client's nature, the authorization server MUST require the 2082 registration of any redirection URI used for receiving authorization 2083 responses, and SHOULD utilize other means to protect resource owners 2084 from such malicious clients. For example, the authorization server 2085 can engage the resource owner to assist in identifying the client and 2086 its origin. 2088 The authorization server SHOULD enforce explicit resource owner 2089 authentication and provide the resource owner with information about 2090 the client and the requested authorization scope and lifetime. It is 2091 up to the resource owner to review the information in the context of 2092 the current client, and authorize or deny the request. 2094 The authorization server SHOULD NOT process repeated authorization 2095 requests automatically (without active resource owner interaction) 2096 without authenticating the client or relying on other measures to 2097 ensure the repeated request comes from the original client and not an 2098 impersonator. 2100 10.3. Access Tokens 2102 Access token (as well as any access token type-specific attributes) 2103 MUST be kept confidential in transit and storage, and only shared 2104 among the authorization server, the resource servers the access token 2105 is valid for, and the client to whom the access token is issued. 2107 When using the implicit grant type, the access token is transmitted 2108 in the URI fragment, which can expose it to unauthorized parties. 2110 The authorization server MUST ensure that access tokens cannot be 2111 generated, modified, or guessed to produce valid access tokens by 2112 unauthorized parties. 2114 The client SHOULD request access tokens with the minimal scope and 2115 lifetime necessary. The authorization server SHOULD take the client 2116 identity into account when choosing how to honor the requested scope 2117 and lifetime, and MAY issue an access token with a less rights than 2118 requested. 2120 10.4. Refresh Tokens 2122 Authorization servers MAY issue refresh tokens to web application 2123 clients and native application clients. 2125 Refresh tokens MUST be kept confidential in transit and storage, and 2126 shared only among the authorization server and the client to whom the 2127 refresh tokens were issued. The authorization server MUST maintain 2128 the binding between a refresh token and the client to whom it was 2129 issued. 2131 The authorization server MUST verify the binding between the refresh 2132 token and client identity whenever the client identity can be 2133 authenticated. When client authentication is not possible, the 2134 authorization server SHOULD deploy other means to detect refresh 2135 token abuse. 2137 For example, the authorization server could employ refresh token 2138 rotation in which a new refresh token is issued with every access 2139 token refresh response. The previous refresh token is invalidated 2140 but retained by the authorization server. If a refresh token is 2141 compromised and subsequently used by both the attacker and the 2142 legitimate client, one of them will present an invalidated refresh 2143 token which will inform the authorization server of the breach. 2145 The authorization server MUST ensure that refresh tokens cannot be 2146 generated, modified, or guessed to produce valid refresh tokens by 2147 unauthorized parties. 2149 10.5. Authorization Codes 2151 The transmission of authorization codes SHOULD be made over a secure 2152 channel, and the client SHOULD implement TLS for use with its 2153 redirection URI if the URI identifies a network resource. Effort 2154 should be made to keep authorization codes confidential. Since 2155 authorization codes are transmitted via user-agent redirections, they 2156 could potentially be disclosed through user-agent history and HTTP 2157 referrer headers. 2159 Authorization codes operate as plaintext bearer credentials, used to 2160 verify that the resource owner who granted authorization at the 2161 authorization server is the same resource owner returning to the 2162 client to complete the process. Therefore, if the client relies on 2163 the authorization code for its own resource owner authentication, the 2164 client redirection endpoint MUST require TLS. 2166 Authorization codes MUST be short lived and single use. If the 2167 authorization server observes multiple attempts to exchange an 2168 authorization code for an access token, the authorization server 2169 SHOULD attempt to revoke all access tokens already granted based on 2170 the compromised authorization code. 2172 If the client can be authenticated, the authorization servers MUST 2173 authenticate the client and ensure that the authorization code was 2174 issued to the same client. 2176 10.6. Authorization Code Redirection URI Manipulation 2178 When requesting authorization using the authorization code grant 2179 type, the client can specify a redirection URI via the "redirect_uri" 2180 parameter. If an attacker can manipulate the value of the 2181 redirection URI, it can cause the authorization server to redirect 2182 the resource owner user-agent to a URI under the control of the 2183 attacker with the authorization code. 2185 An attacker can create an account at a legitimate client and initiate 2186 the authorization flow. When the attacker is sent to the 2187 authorization server to grant access, the attacker grabs the 2188 authorization URI provided by the legitimate client, and replaces the 2189 client's redirection URI with a URI under the control of the 2190 attacker. The attacker then tricks the victim into following the 2191 manipulated link to authorize access to the legitimate client. 2193 Once at the authorization server, the victim is prompted with a 2194 normal, valid request on behalf of a legitimate and trusted client, 2195 and authorizes the request. The victim is then redirected to an 2196 endpoint under the control of the attacker with the authorization 2197 code. The attacker completes the authorization flow by sending the 2198 authorization code to the client using the original redirection URI 2199 provided by the client. The client exchanges the authorization code 2200 with an access token and links it to the attacker's client account 2201 which can now gain access to the protected resources authorized by 2202 the victim (via the client). 2204 In order to prevent such an attack, the authorization server MUST 2205 ensure that the redirection URI used to obtain the authorization code 2206 is identical to the redirection URI provided when exchanging the 2207 authorization code for an access token. The authorization server 2208 MUST require public clients and SHOULD require confidential clients 2209 to register their redirection URIs. If a redirection URI is provided 2210 in the request, the authorization server MUST validate it against the 2211 registered value. 2213 10.7. Resource Owner Password Credentials 2215 The resource owner password credentials grant type is often used for 2216 legacy or migration reasons. It reduces the overall risk of storing 2217 username and password by the client, but does not eliminate the need 2218 to expose highly privileged credentials to the client. 2220 This grant type carries a higher risk than other grant types because 2221 it maintains the password anti-pattern this protocol seeks to avoid. 2222 The client could abuse the password or the password could 2223 unintentionally be disclosed to an attacker (e.g. via log files or 2224 other records kept by the client). 2226 Additionally, because the resource owner does not have control over 2227 the authorization process (the resource owner involvement ends when 2228 it hands over its credentials to the client), the client can obtain 2229 access tokens with a broader scope and longer lifetime than desired 2230 by the resource owner. The authorization server should consider the 2231 scope and lifetime of access tokens issued via this grant type. 2233 The authorization server and client SHOULD minimize use of this grant 2234 type and utilize other grant types whenever possible. 2236 10.8. Request Confidentiality 2238 Access tokens, refresh tokens, resource owner passwords, and client 2239 credentials MUST NOT be transmitted in the clear. Authorization 2240 codes SHOULD NOT be transmitted in the clear. 2242 10.9. Endpoints Authenticity 2244 In order to prevent man-in-the-middle and phishing attacks, the 2245 authorization server MUST implement and require TLS with server 2246 authentication as defined by [RFC2818] for any request sent to the 2247 authorization and token endpoints. The client MUST validate the 2248 authorization server's TLS certificate in accordance with its 2249 requirements for server identity authentication. 2251 10.10. Credentials Guessing Attacks 2253 The authorization server MUST prevent attackers from guessing access 2254 tokens, authorization codes, refresh tokens, resource owner 2255 passwords, and client credentials. 2257 When generating tokens and other credentials not intended for 2258 handling by end-users, the authorization server MUST use a reasonable 2259 level of entropy in order to mitigate the risk of guessing attacks. 2260 The authorization server MUST utilize other means to protect 2261 credentials intended for end-user usage. 2263 10.11. Phishing Attacks 2265 Wide deployment of this and similar protocols may cause end-users to 2266 become inured to the practice of being redirected to websites where 2267 they are asked to enter their passwords. If end-users are not 2268 careful to verify the authenticity of these websites before entering 2269 their credentials, it will be possible for attackers to exploit this 2270 practice to steal resource owners' passwords. 2272 Service providers should attempt to educate end-users about the risks 2273 phishing attacks pose, and should provide mechanisms that make it 2274 easy for end-users to confirm the authenticity of their sites. 2275 Client developers should consider the security implications of how 2276 they interact with the user-agent (e.g., external, embedded), and the 2277 ability of the end-user to verify the authenticity of the 2278 authorization server. 2280 To reduce the risk of phishing attacks, the authorization servers 2281 MUST utilize TLS on every endpoint used for end-user interaction. 2283 10.12. Cross-Site Request Forgery 2285 Cross-site request forgery (CSRF) is an exploit in which an attacker 2286 causes the user-agent of a victim end-user to follow a malicious URI 2287 (e.g. provided to the user-agent as a misleading link, image, or 2288 redirection) to a trusting server (usually established via the 2289 presence of a valid session cookie). 2291 A CSRF attack against the client's redirection URI allows an attacker 2292 to inject their own authorization code or access token, which can 2293 result in the client using an access token associated with the 2294 attacker's protected resources rather than the victim's (e.g. save 2295 the victim's bank account information to a protected resource 2296 controlled by the attacker). 2298 The client MUST implement CSRF protection for its redirection URI. 2299 This is typically accomplished by requiring any request sent to the 2300 redirection URI endpoint to include a value that binds the request to 2301 the user-agent's authenticated state (e.g. a hash of the session 2302 cookie used to authenticate the user-agent). The client SHOULD 2303 utilize the "state" request parameter to deliver this value to the 2304 authorization server when making an authorization request. 2306 Once authorization has been obtained from the end-user, the 2307 authorization server redirects the end-user's user-agent back to the 2308 client with the required binding value contained in the "state" 2309 parameter. The binding value enables the client to verify the 2310 validity of the request by matching the binding value to the user- 2311 agent's authenticated state. The binding value used for CSRF 2312 protection MUST contain a non-guessable value, and the user-agent's 2313 authenticated state (e.g. session cookie, HTML5 local storage) MUST 2314 be kept in a location accessible only to the client and the user- 2315 agent (i.e., protected by same-origin policy). 2317 A CSRF attack against the authorization server's authorization 2318 endpoint can result in an attacker obtaining end-user authorization 2319 for a malicious client without involving or alerting the end-user. 2321 The authorization server MUST implement CSRF protection for its 2322 authorization endpoint, and ensure that a malicious client cannot 2323 obtain authorization without the awareness and explicit consent of 2324 the resource owner. 2326 10.13. Clickjacking 2328 In a clickjacking attack, an attacker registers a legitimate client 2329 and then constructs a malicious site in which it loads the 2330 authorization server's authorization endpoint web page in a 2331 transparent iframe overlaid on top of a set of dummy buttons which 2332 are carefully constructed to be placed directly under important 2333 buttons on the authorization page. When an end-user clicks a 2334 misleading visible button, the end-user is actually clicking an 2335 invisible button on the authorization page (such as an "Authorize" 2336 button). This allows an attacker to trick a resource owner into 2337 granting its client access without their knowledge. 2339 To prevent this form of attack, native applications SHOULD use 2340 external browsers instead of embedding browsers in an iframe when 2341 requesting end-user authorization. For most newer browsers, 2342 avoidance of iframes can be enforced by the authorization server 2343 using the (non-standard) "x-frame-options" header. This header can 2344 have two values, "deny" and "sameorigin", which will block any 2345 framing, or framing by sites with a different origin, respectively. 2346 For older browsers, javascript framebusting techniques can be used 2347 but may not be effective in all browsers. 2349 10.14. Code Injection and Input Validation 2351 A code injection attack occurs when an input or otherwise external 2352 variable is used by an application unsanitized and causes 2353 modification to the application logic. This may allow an attacker to 2354 gain access to the application device or its data, cause denial of 2355 service, or a wide range of malicious side-effects. 2357 The Authorization server and client MUST validate and sanitize any 2358 value received, and in particular, the value of the "state" and 2359 "redirect_uri" parameters. 2361 10.15. Open Redirectors 2363 The authorization server authorization endpoint and the client 2364 redirection endpoint can be improperly configured and operate as open 2365 redirectors. An open redirector is an endpoint using a parameter to 2366 automatically redirect a user-agent to the location specified by the 2367 parameter value without any validation. 2369 Open redirectors can be used in phishing attacks, or by an attacker 2370 to get end-users to visit malicious sites by making the URI's 2371 authority look like a familiar and trusted destination. In addition, 2372 if the authorization server allows the client to register only part 2373 of the redirection URI, an attacker can use an open redirector 2374 operated by the client to construct a redirection URI that will pass 2375 the authorization server validation but will send the authorization 2376 code or access token to an endpoint under the control of the 2377 attacker. 2379 11. IANA Considerations 2381 11.1. The OAuth Access Token Type Registry 2383 This specification establishes the OAuth access token type registry. 2385 Access token types are registered on the advice of one or more 2386 Designated Experts (appointed by the IESG or their delegate), with a 2387 Specification Required (using terminology from [RFC5226]). However, 2388 to allow for the allocation of values prior to publication, the 2389 Designated Expert(s) may approve registration once they are satisfied 2390 that such a specification will be published. 2392 Registration requests should be sent to the [TBD]@ietf.org mailing 2393 list for review and comment, with an appropriate subject (e.g., 2394 "Request for access token type: example"). [[ Note to RFC-EDITOR: The 2395 name of the mailing list should be determined in consultation with 2396 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2398 Within at most 14 days of the request, the Designated Expert(s) will 2399 either approve or deny the registration request, communicating this 2400 decision to the review list and IANA. Denials should include an 2401 explanation and, if applicable, suggestions as to how to make the 2402 request successful. 2404 Decisions (or lack thereof) made by the Designated Expert(s) can be 2405 first appealed to Application Area Directors (contactable using 2406 app-ads@tools.ietf.org email address or directly by looking up their 2407 email addresses on http://www.iesg.org/ website) and, if the 2408 appellant is not satisfied with the response, to the full IESG (using 2409 the iesg@iesg.org mailing list). 2411 IANA should only accept registry updates from the Designated 2412 Expert(s), and should direct all requests for registration to the 2413 review mailing list. 2415 11.1.1. Registration Template 2416 Type name: 2417 The name requested (e.g., "example"). 2418 Additional Token Endpoint Response Parameters: 2419 Additional response parameters returned together with the 2420 "access_token" parameter. New parameters MUST be separately 2421 registered in the OAuth parameters registry as described by 2422 Section 11.2. 2423 HTTP Authentication Scheme(s): 2424 The HTTP authentication scheme name(s), if any, used to 2425 authenticate protected resources requests using access tokens of 2426 this type. 2427 Change controller: 2428 For standards-track RFCs, state "IETF". For others, give the name 2429 of the responsible party. Other details (e.g., postal address, 2430 e-mail address, home page URI) may also be included. 2431 Specification document(s): 2432 Reference to the document that specifies the parameter, preferably 2433 including a URI that can be used to retrieve a copy of the 2434 document. An indication of the relevant sections may also be 2435 included, but is not required. 2437 11.2. The OAuth Parameters Registry 2439 This specification establishes the OAuth parameters registry. 2441 Additional parameters for inclusion in the authorization endpoint 2442 request, the authorization endpoint response, the token endpoint 2443 request, or the token endpoint response are registered on the advice 2444 of one or more Designated Experts (appointed by the IESG or their 2445 delegate), with a Specification Required (using terminology from 2446 [RFC5226]). However, to allow for the allocation of values prior to 2447 publication, the Designated Expert(s) may approve registration once 2448 they are satisfied that such a specification will be published. 2450 Registration requests should be sent to the [TBD]@ietf.org mailing 2451 list for review and comment, with an appropriate subject (e.g., 2452 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 2453 the mailing list should be determined in consultation with the IESG 2454 and IANA. Suggested name: oauth-ext-review. ]] 2456 Within at most 14 days of the request, the Designated Expert(s) will 2457 either approve or deny the registration request, communicating this 2458 decision to the review list and IANA. Denials should include an 2459 explanation and, if applicable, suggestions as to how to make the 2460 request successful. 2462 Decisions (or lack thereof) made by the Designated Expert(s) can be 2463 first appealed to Application Area Directors (contactable using 2464 app-ads@tools.ietf.org email address or directly by looking up their 2465 email addresses on http://www.iesg.org/ website) and, if the 2466 appellant is not satisfied with the response, to the full IESG (using 2467 the iesg@iesg.org mailing list). 2469 IANA should only accept registry updates from the Designated 2470 Expert(s), and should direct all requests for registration to the 2471 review mailing list. 2473 11.2.1. Registration Template 2475 Parameter name: 2476 The name requested (e.g., "example"). 2477 Parameter usage location: 2478 The location(s) where parameter can be used. The possible 2479 locations are: authorization request, authorization response, 2480 token request, or token response. 2481 Change controller: 2482 For standards-track RFCs, state "IETF". For others, give the name 2483 of the responsible party. Other details (e.g., postal address, 2484 e-mail address, home page URI) may also be included. 2485 Specification document(s): 2486 Reference to the document that specifies the parameter, preferably 2487 including a URI that can be used to retrieve a copy of the 2488 document. An indication of the relevant sections may also be 2489 included, but is not required. 2491 11.2.2. Initial Registry Contents 2493 The OAuth Parameters Registry's initial contents are: 2495 o Parameter name: client_id 2496 o Parameter usage location: authorization request, token request 2497 o Change controller: IETF 2498 o Specification document(s): [[ this document ]] 2500 o Parameter name: client_secret 2501 o Parameter usage location: token request 2502 o Change controller: IETF 2503 o Specification document(s): [[ this document ]] 2505 o Parameter name: response_type 2506 o Parameter usage location: authorization request 2507 o Change controller: IETF 2508 o Specification document(s): [[ this document ]] 2509 o Parameter name: redirect_uri 2510 o Parameter usage location: authorization request, token request 2511 o Change controller: IETF 2512 o Specification document(s): [[ this document ]] 2514 o Parameter name: scope 2515 o Parameter usage location: authorization request, authorization 2516 response, token request, token response 2517 o Change controller: IETF 2518 o Specification document(s): [[ this document ]] 2520 o Parameter name: state 2521 o Parameter usage location: authorization request, authorization 2522 response 2523 o Change controller: IETF 2524 o Specification document(s): [[ this document ]] 2526 o Parameter name: code 2527 o Parameter usage location: authorization response, token request 2528 o Change controller: IETF 2529 o Specification document(s): [[ this document ]] 2531 o Parameter name: error_description 2532 o Parameter usage location: authorization response, token response 2533 o Change controller: IETF 2534 o Specification document(s): [[ this document ]] 2536 o Parameter name: error_uri 2537 o Parameter usage location: authorization response, token response 2538 o Change controller: IETF 2539 o Specification document(s): [[ this document ]] 2541 o Parameter name: grant_type 2542 o Parameter usage location: token request 2543 o Change controller: IETF 2544 o Specification document(s): [[ this document ]] 2546 o Parameter name: access_token 2547 o Parameter usage location: authorization response, token response 2548 o Change controller: IETF 2549 o Specification document(s): [[ this document ]] 2551 o Parameter name: token_type 2552 o Parameter usage location: authorization response, token response 2553 o Change controller: IETF 2554 o Specification document(s): [[ this document ]] 2555 o Parameter name: expires_in 2556 o Parameter usage location: authorization response, token response 2557 o Change controller: IETF 2558 o Specification document(s): [[ this document ]] 2560 o Parameter name: username 2561 o Parameter usage location: token request 2562 o Change controller: IETF 2563 o Specification document(s): [[ this document ]] 2565 o Parameter name: password 2566 o Parameter usage location: token request 2567 o Change controller: IETF 2568 o Specification document(s): [[ this document ]] 2570 o Parameter name: refresh_token 2571 o Parameter usage location: token request, token response 2572 o Change controller: IETF 2573 o Specification document(s): [[ this document ]] 2575 11.3. The OAuth Authorization Endpoint Response Type Registry 2577 This specification establishes the OAuth authorization endpoint 2578 response type registry. 2580 Additional response type for use with the authorization endpoint are 2581 registered on the advice of one or more Designated Experts (appointed 2582 by the IESG or their delegate), with a Specification Required (using 2583 terminology from [RFC5226]). However, to allow for the allocation of 2584 values prior to publication, the Designated Expert(s) may approve 2585 registration once they are satisfied that such a specification will 2586 be published. 2588 Registration requests should be sent to the [TBD]@ietf.org mailing 2589 list for review and comment, with an appropriate subject (e.g., 2590 "Request for response type: example"). [[ Note to RFC-EDITOR: The 2591 name of the mailing list should be determined in consultation with 2592 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2594 Within at most 14 days of the request, the Designated Expert(s) will 2595 either approve or deny the registration request, communicating this 2596 decision to the review list and IANA. Denials should include an 2597 explanation and, if applicable, suggestions as to how to make the 2598 request successful. 2600 Decisions (or lack thereof) made by the Designated Expert(s) can be 2601 first appealed to Application Area Directors (contactable using 2602 app-ads@tools.ietf.org email address or directly by looking up their 2603 email addresses on http://www.iesg.org/ website) and, if the 2604 appellant is not satisfied with the response, to the full IESG (using 2605 the iesg@iesg.org mailing list). 2607 IANA should only accept registry updates from the Designated 2608 Expert(s), and should direct all requests for registration to the 2609 review mailing list. 2611 11.3.1. Registration Template 2613 Response type name: 2614 The name requested (e.g., "example"). 2615 Change controller: 2616 For standards-track RFCs, state "IETF". For others, give the name 2617 of the responsible party. Other details (e.g., postal address, 2618 e-mail address, home page URI) may also be included. 2619 Specification document(s): 2620 Reference to the document that specifies the type, preferably 2621 including a URI that can be used to retrieve a copy of the 2622 document. An indication of the relevant sections may also be 2623 included, but is not required. 2625 11.3.2. Initial Registry Contents 2627 The OAuth Authorization Endpoint Response Type Registry's initial 2628 contents are: 2630 o Response type name: code 2631 o Change controller: IETF 2632 o Specification document(s): [[ this document ]] 2634 o Response type name: token 2635 o Change controller: IETF 2636 o Specification document(s): [[ this document ]] 2638 11.4. The OAuth Extensions Error Registry 2640 This specification establishes the OAuth extensions error registry. 2642 Additional error codes used together with other protocol extensions 2643 (i.e. extension grant types, access token types, or extension 2644 parameters) are registered on the advice of one or more Designated 2645 Experts (appointed by the IESG or their delegate), with a 2646 Specification Required (using terminology from [RFC5226]). However, 2647 to allow for the allocation of values prior to publication, the 2648 Designated Expert(s) may approve registration once they are satisfied 2649 that such a specification will be published. 2651 Registration requests should be sent to the [TBD]@ietf.org mailing 2652 list for review and comment, with an appropriate subject (e.g., 2653 "Request for error code: example"). [[ Note to RFC-EDITOR: The name 2654 of the mailing list should be determined in consultation with the 2655 IESG and IANA. Suggested name: oauth-ext-review. ]] 2657 Within at most 14 days of the request, the Designated Expert(s) will 2658 either approve or deny the registration request, communicating this 2659 decision to the review list and IANA. Denials should include an 2660 explanation and, if applicable, suggestions as to how to make the 2661 request successful. 2663 Decisions (or lack thereof) made by the Designated Expert(s) can be 2664 first appealed to Application Area Directors (contactable using 2665 app-ads@tools.ietf.org email address or directly by looking up their 2666 email addresses on http://www.iesg.org/ website) and, if the 2667 appellant is not satisfied with the response, to the full IESG (using 2668 the iesg@iesg.org mailing list). 2670 IANA should only accept registry updates from the Designated 2671 Expert(s), and should direct all requests for registration to the 2672 review mailing list. 2674 11.4.1. Registration Template 2676 Error name: 2677 The name requested (e.g., "example"). 2678 Error usage location: 2679 The location(s) where the error can be used. The possible 2680 locations are: authorization code grant error response 2681 (Section 4.1.2.1), implicit grant error response 2682 (Section 4.2.2.1), or token error response (Section 5.2). 2683 Related protocol extension: 2684 The name of the extension grant type, access token type, or 2685 extension parameter, the error code is used in conjunction with. 2686 Change controller: 2687 For standards-track RFCs, state "IETF". For others, give the name 2688 of the responsible party. Other details (e.g., postal address, 2689 e-mail address, home page URI) may also be included. 2690 Specification document(s): 2691 Reference to the document that specifies the error code, 2692 preferably including a URI that can be used to retrieve a copy of 2693 the document. An indication of the relevant sections may also be 2694 included, but is not required. 2696 12. Acknowledgements 2698 The initial OAuth 2.0 protocol specification was edited by David 2699 Recordon, based on two previous publications: the OAuth 1.0 community 2700 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 2701 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 2702 Considerations section was drafted by Torsten Lodderstedt, Mark 2703 McGloin, Phil Hunt, and Anthony Nadalin. 2705 The OAuth 1.0 community specification was edited by Eran Hammer-Lahav 2706 and authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 2707 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 2708 Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, 2709 Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran 2710 Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy 2711 Smith. 2713 The OAuth WRAP specification was edited by Dick Hardt and authored by 2714 Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. 2716 This specification is the work of the OAuth Working Group which 2717 includes dozens of active and dedicated participants. In particular, 2718 the following individuals contributed ideas, feedback, and wording 2719 which shaped and formed the final specification: 2721 Michael Adams, Amanda Anganes, Andrew Arnott, Dirk Balfanz, Aiden 2722 Bell, Scott Cantor, Marcos Caceres, Blaine Cook, Brian Campbell, 2723 Brian Eaton, Leah Culver, Bill de hOra, Andre DeMarre, Brian Eaton, 2724 Brian Ellin, Igor Faynberg, George Fletcher, Tim Freeman, Evan 2725 Gilbert, Yaron Goland, Brent Goldman, Kristoffer Gronowski, Justin 2726 Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. Jones, John 2727 Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, Rasmus Lerdorf, 2728 Torsten Lodderstedt, Hui-Lan Lu, Casey Lucas, Paul Madsen, Alastair 2729 Mair, Eve Maler, James Manger, Mark McGloin, Laurence Miao, Chuck 2730 Mortimore, Anthony Nadalin, Justin Richer, Peter Saint-Andre, Nat 2731 Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, 2732 Vlad Skvortsov, Justin Smith, Niv Steingarten, Christian Stuebner, 2733 Jeremy Suriel, Paul Tarjan, Allen Tom, Franklin Tse, Nick Walker, 2734 Shane Weeden, and Skylar Woodward. 2736 Appendix A. Editor's Notes 2738 While many people contributed to this specification throughout its 2739 long journey, the editor would like to acknowledge and thank a few 2740 individuals for their outstanding and invaluable efforts leading up 2741 to the publication of this specification. It is these individuals 2742 without whom this work would not have existed or reached its 2743 successful conclusion. 2745 David Recordon for continuously being one of OAuth's most valuable 2746 assets, bringing pragmatism and urgency to the work, and helping 2747 shape it from its very beginning, as well as being one of the best 2748 collaborators I had the pleasure of working with. 2750 Mark Nottingham for introducing OAuth to the IETF and setting the 2751 community on this course. Lisa Dusseault for her support and 2752 guidance as the Application area director. Blaine Cook, Peter Saint- 2753 Andre, and Hannes Tschofenig for their work as working group chairs. 2755 James Manger for his creative ideas and always insightful feedback. 2756 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 2757 Marius Scurtescu, and Luke Shepard for their continued participation 2758 and valuable feedback. 2760 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 2761 support of this work for over three years. 2763 13. References 2765 13.1. Normative References 2767 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2768 Requirement Levels", BCP 14, RFC 2119, March 1997. 2770 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2771 RFC 2246, January 1999. 2773 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2774 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2775 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2777 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2778 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2779 Authentication: Basic and Digest Access Authentication", 2780 RFC 2617, June 1999. 2782 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2784 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2785 Resource Identifier (URI): Generic Syntax", STD 66, 2786 RFC 3986, January 2005. 2788 [RFC4627] Crockford, D., "The application/json Media Type for 2789 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2791 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2792 RFC 4949, August 2007. 2794 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2795 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2796 May 2008. 2798 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2799 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2801 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2802 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2804 [W3C.REC-html401-19991224] 2805 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 2806 Specification", World Wide Web Consortium 2807 Recommendation REC-html401-19991224, December 1999, 2808 . 2810 13.2. Informative References 2812 [I-D.draft-hardt-oauth-01] 2813 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2814 Web Resource Authorization Profiles", January 2010. 2816 [I-D.ietf-oauth-saml2-bearer] 2817 Mortimore, C., "SAML 2.0 Bearer Assertion Profiles for 2818 OAuth 2.0", draft-ietf-oauth-saml2-bearer-08 (work in 2819 progress), August 2011. 2821 [I-D.ietf-oauth-v2-bearer] 2822 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2823 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-08 2824 (work in progress), July 2011. 2826 [I-D.ietf-oauth-v2-http-mac] 2827 Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP 2828 Authentication: MAC Access Authentication", 2829 draft-ietf-oauth-v2-http-mac-00 (work in progress), 2830 May 2011. 2832 [I-D.ietf-oauth-v2-threatmodel] 2833 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2834 Threat Model and Security Considerations", 2835 draft-ietf-oauth-v2-threatmodel-00 (work in progress), 2836 July 2011. 2838 [OASIS.saml-core-2.0-os] 2839 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2840 "Assertions and Protocol for the OASIS Security Assertion 2841 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2842 2.0-os, March 2005. 2844 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2845 April 2010. 2847 Authors' Addresses 2849 Eran Hammer-Lahav (editor) 2850 Yahoo! 2852 Email: eran@hueniverse.com 2853 URI: http://hueniverse.com 2855 David Recordon 2856 Facebook 2858 Email: dr@fb.com 2859 URI: http://www.davidrecordon.com/ 2861 Dick Hardt 2862 Microsoft 2864 Email: dick.hardt@gmail.com 2865 URI: http://dickhardt.org/