idnits 2.17.00 (12 Aug 2021) /tmp/idnits33243/draft-ietf-oauth-v2-18.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 mention this, which it should. 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 (July 8, 2011) is 3969 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 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) ** Downref: Normative reference to an Informational RFC: RFC 2818 ** 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: draft-ietf-oauth-saml2-bearer has been published as RFC 7522 == Outdated reference: draft-ietf-oauth-v2-bearer has been published as RFC 6750 == Outdated reference: A later version (-05) exists of draft-ietf-oauth-v2-http-mac-00 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 7 errors (**), 0 flaws (~~), 5 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: January 9, 2012 D. Hardt 7 Microsoft 8 July 8, 2011 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-18 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. 21 Status of this Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on January 9, 2012. 38 Copyright Notice 40 Copyright (c) 2011 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 5 57 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 5 58 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . 6 59 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 7 60 1.4.1. Authorization Code . . . . . . . . . . . . . . . . . . 7 61 1.4.2. Implicit . . . . . . . . . . . . . . . . . . . . . . . 7 62 1.4.3. Resource Owner Password Credentials . . . . . . . . . 8 63 1.4.4. Client Credentials . . . . . . . . . . . . . . . . . . 8 64 1.4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . 8 65 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 8 66 1.6. Notational Conventions . . . . . . . . . . . . . . . . . 10 67 2. Client Registration . . . . . . . . . . . . . . . . . . . . . 10 68 2.1. Client Types . . . . . . . . . . . . . . . . . . . . . . 11 69 2.2. Registration Requirements . . . . . . . . . . . . . . . . 11 70 2.3. Client Identifier . . . . . . . . . . . . . . . . . . . . 11 71 2.4. Client Authentication . . . . . . . . . . . . . . . . . . 11 72 2.4.1. Client Password . . . . . . . . . . . . . . . . . . . 12 73 2.4.2. Other Authentication Methods . . . . . . . . . . . . . 13 74 2.5. Unregistered Clients . . . . . . . . . . . . . . . . . . 13 75 3. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 13 76 3.1. Authorization Endpoint . . . . . . . . . . . . . . . . . 13 77 3.1.1. Response Type . . . . . . . . . . . . . . . . . . . . 14 78 3.1.2. Redirection URI . . . . . . . . . . . . . . . . . . . 15 79 3.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . 17 80 3.2.1. Client Authentication . . . . . . . . . . . . . . . . 17 81 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 18 82 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . 18 83 4.1.1. Authorization Request . . . . . . . . . . . . . . . . 20 84 4.1.2. Authorization Response . . . . . . . . . . . . . . . . 21 85 4.1.3. Access Token Request . . . . . . . . . . . . . . . . . 23 86 4.1.4. Access Token Response . . . . . . . . . . . . . . . . 24 87 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . 24 88 4.2.1. Authorization Request . . . . . . . . . . . . . . . . 27 89 4.2.2. Access Token Response . . . . . . . . . . . . . . . . 28 90 4.3. Resource Owner Password Credentials . . . . . . . . . . . 30 91 4.3.1. Authorization Request and Response . . . . . . . . . . 31 92 4.3.2. Access Token Request . . . . . . . . . . . . . . . . . 32 93 4.3.3. Access Token Response . . . . . . . . . . . . . . . . 33 94 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . 33 95 4.4.1. Authorization Request and Response . . . . . . . . . . 34 96 4.4.2. Access Token Request . . . . . . . . . . . . . . . . . 34 97 4.4.3. Access Token Response . . . . . . . . . . . . . . . . 35 98 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . 35 99 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 36 100 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 36 101 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . 38 102 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 39 103 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 40 104 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . 41 105 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 42 106 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 42 107 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . 42 108 8.3. Defining New Authorization Grant Types . . . . . . . . . 43 109 8.4. Defining New Authorization Endpoint Response Types . . . 43 110 8.5. Defining Additional Error Codes . . . . . . . . . . . . . 43 111 9. Native Applications . . . . . . . . . . . . . . . . . . . . . 44 112 10. Security Considerations . . . . . . . . . . . . . . . . . . . 45 113 10.1. Client Authentication . . . . . . . . . . . . . . . . . . 46 114 10.2. Client Impersonation . . . . . . . . . . . . . . . . . . 46 115 10.3. Access Tokens . . . . . . . . . . . . . . . . . . . . . . 47 116 10.4. Refresh Tokens . . . . . . . . . . . . . . . . . . . . . 47 117 10.5. Authorization Codes . . . . . . . . . . . . . . . . . . . 48 118 10.6. Authorization Code Leakage . . . . . . . . . . . . . . . 48 119 10.7. Resource Owner Password Credentials . . . . . . . . . . . 49 120 10.8. Request Confidentiality . . . . . . . . . . . . . . . . . 49 121 10.9. Endpoints Authenticity . . . . . . . . . . . . . . . . . 49 122 10.10. Credentials Guessing Attacks . . . . . . . . . . . . . . 49 123 10.11. Phishing Attacks . . . . . . . . . . . . . . . . . . . . 50 124 10.12. Cross-Site Request Forgery . . . . . . . . . . . . . . . 50 125 10.13. Clickjacking . . . . . . . . . . . . . . . . . . . . . . 51 126 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 127 11.1. The OAuth Access Token Type Registry . . . . . . . . . . 51 128 11.1.1. Registration Template . . . . . . . . . . . . . . . . 52 129 11.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 52 130 11.2.1. Registration Template . . . . . . . . . . . . . . . . 53 131 11.2.2. Initial Registry Contents . . . . . . . . . . . . . . 53 132 11.3. The OAuth Authorization Endpoint Response Type 133 Registry . . . . . . . . . . . . . . . . . . . . . . . . 55 134 11.3.1. Registration Template . . . . . . . . . . . . . . . . 56 135 11.3.2. Initial Registry Contents . . . . . . . . . . . . . . 56 136 11.4. The OAuth Extensions Error Registry . . . . . . . . . . . 57 137 11.4.1. Registration Template . . . . . . . . . . . . . . . . 57 138 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 58 139 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 59 140 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 141 13.1. Normative References . . . . . . . . . . . . . . . . . . 59 142 13.2. Informative References . . . . . . . . . . . . . . . . . 60 143 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 61 145 1. Introduction 147 In the traditional client-server authentication model, the client 148 accesses a protected resource on the server by authenticating with 149 the server using the resource owner's credentials. In order to 150 provide third-party applications access to protected resources, the 151 resource owner shares its credentials with the third-party. This 152 creates several problems and limitations: 154 o Third-party applications are required to store the resource 155 owner's credentials for future use, typically a password in clear- 156 text. 157 o Servers are required to support password authentication, despite 158 the security weaknesses created by passwords. 159 o Third-party applications gain overly broad access to the resource 160 owner's protected resources, leaving resource owners without any 161 ability to restrict duration or access to a limited subset of 162 resources. 163 o Resource owners cannot revoke access to an individual third-party 164 without revoking access to all third-parties, and must do so by 165 changing their password. 166 o Compromise of any third-party application results in compromise of 167 the end-user's password and all of the data protected by that 168 password. 170 OAuth addresses these issues by introducing an authorization layer 171 and separating the role of the client from that of the resource 172 owner. In OAuth, the client requests access to resources controlled 173 by the resource owner and hosted by the resource server, and is 174 issued a different set of credentials than those of the resource 175 owner. 177 Instead of using the resource owner's credentials to access protected 178 resources, the client obtains an access token - a string denoting a 179 specific scope, lifetime, and other access attributes. Access tokens 180 are issued to third-party clients by an authorization server with the 181 approval of the resource owner. The client uses the access token to 182 access the protected resources hosted by the resource server. 184 For example, an end-user (resource owner) can grant a printing 185 service (client) access to her protected photos stored at a photo 186 sharing service (resource server), without sharing her username and 187 password with the printing service. Instead, she authenticates 188 directly with a server trusted by the photo sharing service 189 (authorization server) which issues the printing service delegation- 190 specific credentials (access token). 192 This specification is designed for use with HTTP [RFC2616]. The use 193 of OAuth with any transport protocol other than HTTP is undefined. 195 1.1. Roles 197 OAuth includes four roles working together to grant and provide 198 access to protected resources - access restricted resources requiring 199 authentication: 201 resource owner 202 An entity capable of granting access to a protected resource (e.g. 203 end-user). 204 resource server 205 The server hosting the protected resources, capable of accepting 206 and responding to protected resource requests using access tokens. 207 client 208 An application making protected resource requests on behalf of the 209 resource owner and with its authorization. 210 authorization server 211 The server issuing access tokens to the client after successfully 212 authenticating the resource owner and obtaining authorization. 214 The interaction between the authorization server and resource server 215 is beyond the scope of this specification. The authorization server 216 may be the same server as the resource server or a separate entity. 217 A single authorization server may issue access tokens accepted by 218 multiple resource servers. 220 1.2. Protocol Flow 222 +--------+ +---------------+ 223 | |--(A)- Authorization Request ->| Resource | 224 | | | Owner | 225 | |<-(B)-- Authorization Grant ---| | 226 | | +---------------+ 227 | | 228 | | +---------------+ 229 | |--(C)-- Authorization Grant -->| Authorization | 230 | Client | | Server | 231 | |<-(D)----- Access Token -------| | 232 | | +---------------+ 233 | | 234 | | +---------------+ 235 | |--(E)----- Access Token ------>| Resource | 236 | | | Server | 237 | |<-(F)--- Protected Resource ---| | 238 +--------+ +---------------+ 239 Figure 1: Abstract Protocol Flow 241 The abstract flow illustrated in Figure 1 describes the interaction 242 between the four roles and includes the following steps: 244 (A) The client requests authorization from the resource owner. The 245 authorization request can be made directly to the resource owner 246 (as shown), or preferably indirectly via an intermediary such as 247 an authorization server. 248 (B) The client receives an authorization grant which represents the 249 authorization provided by the resource owner. The authorization 250 grant type depends on the method used by the client and 251 supported by the authorization server to obtain it. 252 (C) The client requests an access token by authenticating with the 253 authorization server and presenting the authorization grant. 254 (D) The authorization server authenticates the client and validates 255 the authorization grant, and if valid issues an access token. 256 (E) The client requests the protected resource from the resource 257 server and authenticates by presenting the access token. 258 (F) The resource server validates the access token, and if valid, 259 serves the request. 261 1.3. Access Token 263 Access tokens are credentials used to access protected resources. An 264 access token is a string representing an authorization issued to the 265 client. The string is usually opaque to the client. Tokens 266 represent specific scopes and durations of access, granted by the 267 resource owner, and enforced by the resource server and authorization 268 server. 270 The token may denote an identifier used to retrieve the authorization 271 information, or self-contain the authorization information in a 272 verifiable manner (i.e. a token string consisting of some data and a 273 signature). Additional authentication credentials, which are beyond 274 the scope of this specification, may be required in order for the 275 client to use a token. 277 The access token provides an abstraction layer, replacing different 278 authorization constructs (e.g. username and password) with a single 279 token understood by the resource server. This abstraction enables 280 issuing access tokens more restrictive than the authorization grant 281 used to obtain them, as well as removing the resource server's need 282 to understand a wide range of authentication methods. 284 Access tokens can have different formats, structures, and methods of 285 utilization (e.g. cryptographic properties) based on the resource 286 server security requirements. Access token attributes and the 287 methods used to access protected resources are beyond the scope of 288 this specification and are defined by companion specifications. 290 1.4. Authorization Grant 292 An authorization grant is a general term used to describe the 293 intermediate credentials representing the resource owner 294 authorization (to access its protected resources), and serves as an 295 abstraction layer. An authorization grant is used by the client to 296 obtain an access token. 298 This specification defines four grant types: authorization code, 299 implicit, resource owner password credentials, and client 300 credentials, as well as an extensibility mechanism for defining 301 additional types. 303 1.4.1. Authorization Code 305 The authorization code is obtained by using an authorization server 306 as an intermediary between the client and resource owner. Instead of 307 requesting authorization directly from the resource owner, the client 308 directs the resource owner to an authorization server (via its user- 309 agent as defined in [RFC2616]), which in turn directs the resource 310 owner back to the client with the authorization code. 312 Before directing the resource owner back to the client with the 313 authorization code, the authorization server authenticates the 314 resource owner and obtains authorization. Because the resource owner 315 only authenticates with the authorization server, the resource 316 owner's credentials are never shared with the client. 318 The authorization code provides a few important security benefits 319 such as the ability to authenticate the client and issuing the access 320 token directly to the client without potentially exposing it to 321 others, including the resource owner. 323 1.4.2. Implicit 325 The authorization grant is implicit when an access token is issued to 326 the client directly as the result of the resource owner 327 authorization, without using intermediate credentials (such as an 328 authorization code). 330 When issuing an implicit grant, the authorization server does not 331 authenticate the client and the client identity is verified via the 332 redirection URI used to deliver the access token to the client. The 333 access token may be exposed to the resource owner or other 334 applications with access to the resource owner's user-agent. 336 Implicit grants improve the responsiveness and efficiency of some 337 clients (such as a client implemented as an in-browser application) 338 since it reduces the number of round trips required to obtain an 339 access token. However, this convenience should be weighted against 340 the security implications of using implicit grants, especially when 341 the authorization code grant type is available. 343 1.4.3. Resource Owner Password Credentials 345 The resource owner password credentials (e.g. a username and 346 password) can be used directly as an authorization grant to obtain an 347 access token. The credentials should only be used when there is a 348 high degree of trust between the resource owner and the client (e.g. 349 its device operating system or a highly privileged application), and 350 when other authorization grant types are not available (such as an 351 authorization code). 353 Even though this grant type requires direct client access to the 354 resource owner credentials, the resource owner credentials are used 355 for a single request and are exchanged for an access token. Unlike 356 the HTTP Basic authentication scheme defined in [RFC2617], this grant 357 type (when combined with a refresh token) eliminates the need for the 358 client to store the resource owner credentials for future use. 360 1.4.4. Client Credentials 362 The client credentials (or other forms of client authentication) can 363 be used as an authorization grant when the authorization scope is 364 limited to the protected resources under the control of the client, 365 or to protected resources previously arranged with the authorization 366 server. Client credentials are used as an authorization grant 367 typically when the client is acting on its own behalf (the client is 368 also the resource owner). 370 1.4.5. Extensions 372 Additional grant types may be defined to provide a bridge between 373 OAuth and other protocols. 375 1.5. Refresh Token 377 Refresh tokens are credentials used to obtain access tokens. Refresh 378 tokens are issued to the client by the authorization server and are 379 used to obtain a new access token when the current access token 380 becomes invalid or expires, or to obtain additional access tokens 381 with identical or narrower scope (access tokens may have a shorter 382 lifetime and fewer permissions than authorized by the resource 383 owner). Issuing a refresh token is optional and is included when 384 issuing an access token. 386 A refresh token is a string representing the authorization granted to 387 the client by the resource owner. The string is usually opaque to 388 the client. The token denotes an identifier used to retrieve the 389 authorization information. Unlike access tokens, refresh tokens are 390 intended for use only with authorization servers and are never sent 391 to resource servers. 393 +--------+ +---------------+ 394 | |--(A)------- Authorization Grant --------->| | 395 | | | | 396 | |<-(B)----------- Access Token -------------| | 397 | | & Refresh Token | | 398 | | | | 399 | | +----------+ | | 400 | |--(C)---- Access Token ---->| | | | 401 | | | | | | 402 | |<-(D)- Protected Resource --| Resource | | Authorization | 403 | Client | | Server | | Server | 404 | |--(E)---- Access Token ---->| | | | 405 | | | | | | 406 | |<-(F)- Invalid Token Error -| | | | 407 | | +----------+ | | 408 | | | | 409 | |--(G)----------- Refresh Token ----------->| | 410 | | | | 411 | |<-(H)----------- Access Token -------------| | 412 +--------+ & Optional Refresh Token +---------------+ 414 Figure 2: Refreshing an Expired Access Token 416 The flow illustrated in Figure 2 includes the following steps: 418 (A) The client requests an access token by authenticating with the 419 authorization server, and presenting an authorization grant. 420 (B) The authorization server authenticates the client and validates 421 the authorization grant, and if valid issues an access token and 422 a refresh token. 423 (C) The client makes a protected resource requests to the resource 424 server by presenting the access token. 425 (D) The resource server validates the access token, and if valid, 426 serves the request. 428 (E) Steps (C) and (D) repeat until the access token expires. If the 429 client knows the access token expired, it skips to step (G), 430 otherwise it makes another protected resource request. 431 (F) Since the access token is invalid, the resource server returns 432 an invalid token error. 433 (G) The client requests a new access token by authenticating with 434 the authorization server and presenting the refresh token. 435 (H) The authorization server authenticates the client and validates 436 the refresh token, and if valid issues a new access token (and 437 optionally, a new refresh token). 439 1.6. Notational Conventions 441 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 442 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 443 specification are to be interpreted as described in [RFC2119]. 445 This specification uses the Augmented Backus-Naur Form (ABNF) 446 notation of [RFC5234]. 448 Certain security-related terms are to be understood in the sense 449 defined in [RFC4949]. These terms include, but are not limited to, 450 'attack', 'authentication', 'authorization', 'certificate', 451 'confidentiality', 'credential', 'encryption', 'identity', 'sign', 452 'signature', 'trust', 'validate', and 'verify'. 454 Unless otherwise noted, all the protocol parameter names and values 455 are case sensitive. 457 2. Client Registration 459 [[ Pending Consensus ]] 461 Before initiating the protocol, the client registers with the 462 authorization server. The means through which the client registers 463 with the authorization server are beyond the scope of this 464 specification, but typically involve end-user interaction with an 465 HTML registration form. 467 Client registration does not require a direct interaction between the 468 client and the authorization server. When supported by the 469 authorization server, registration can rely on other means for 470 establishing trust and obtaining the required client properties (e.g. 471 redirection URI, client type). For example, registration can be 472 accomplished using a self-issued or third-party-issued assertion, or 473 by the authorization server performing client discovery using a 474 trusted channel. 476 2.1. Client Types 478 OAuth defines two client types, based on their ability to 479 authenticate securely with the authorization server (i.e. ability to 480 maintain the confidentiality of their client credentials): 482 private 483 Clients capable of maintaining the confidentiality of their 484 credentials (e.g. client implemented on a secure server with 485 restricted access to the client credentials), or capable of secure 486 client authentication using other means. 487 public 488 Clients incapable of maintaining the confidentiality of their 489 credentials (e.g. clients executing on the resource owner's device 490 such as an installed native application or a user-agent-based 491 application), and incapable of secure client authentication via 492 any other mean. 494 The client type designation is based on the authorization server's 495 definition of secure authentication and its acceptable exposure 496 levels of client credentials. 498 2.2. Registration Requirements 500 When registering a client, the client developer MUST specify: 502 o the client type as described in Section 2.1, 503 o the client redirection URIs as described in Section 3.1.2, and 504 o any other information required by the authorization server (e.g. 505 application name, website, description, logo image, the acceptance 506 of legal terms). 508 2.3. Client Identifier 510 The authorization server issues the registered client a client 511 identifier - a unique string representing the registration 512 information provided by the client. The client identifier is not a 513 secret, it is exposed to the resource owner, and cannot not be used 514 alone for client authentication. 516 2.4. Client Authentication 518 In addition, the client and authorization server establish a client 519 authentication method suitable for the client type and security 520 requirements of the authorization server. The authorization server 521 MAY accept any form of client authentication meeting its security 522 requirements. 524 Private clients are typically issued (or establish) a set of client 525 credentials used for authenticating with the authorization server 526 (e.g. password, public/private key pair). 528 The authorization server SHOULD NOT make assumptions about the client 529 type or accept the type information provided without establishing 530 trust with the client or its developer. The authorization server 531 MUST NOT rely on client authentication performed by public clients. 533 The client MUST NOT use more than one authentication method in each 534 request. 536 2.4.1. Client Password 538 Clients in possession of a client password MAY use the HTTP Basic 539 authentication scheme as defined in [RFC2617] to authenticate with 540 the authorization server. The client identifier is used as the 541 username, and the client password is used as the password. 543 For example (extra line breaks are for display purposes only): 545 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 547 Alternatively, the authorization server MAY allow including the 548 client credentials in the request body using the following 549 parameters: 551 client_id 552 REQUIRED. The client identifier issued to the client during 553 the registration process described by Section 2.3. 554 client_secret 555 REQUIRED. The client secret. 557 Including the client credentials in the request body using the two 558 parameters is NOT RECOMMENDED, and should be limited to clients 559 unable to directly utilize the HTTP Basic authentication scheme (or 560 other password-based HTTP authentication schemes). 562 For example, requesting to refresh an access token (Section 6) using 563 the body parameters (extra line breaks are for display purposes 564 only): 566 POST /token HTTP/1.1 567 Host: server.example.com 568 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 570 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 571 &client_id=s6BhdRkqt3&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw 573 The authorization server MUST require the use of a transport-layer 574 security mechanism when sending requests to the token endpoint, as 575 requests using this authentication method result in the transmission 576 of clear-text credentials. 578 2.4.2. Other Authentication Methods 580 The authorization server MAY support any suitable HTTP authentication 581 scheme matching its security requirements. When using other 582 authentication methods, the authorization server MUST define a 583 mapping between the client identifier (registration record) and 584 authentication scheme. 586 2.5. Unregistered Clients 588 This specification does not exclude the use of unregistered clients. 589 However, the use with such clients is beyond the scope of this 590 specification, and requires additional security analysis and review 591 of its interoperability impact. 593 3. Protocol Endpoints 595 The authorization process utilizes two endpoints (HTTP resources): 597 o Authorization endpoint - used to obtain authorization from the 598 resource owner via user-agent redirection. 599 o Token endpoint - used to exchange an authorization grant for an 600 access token, typically with client authentication. 602 Not every authorization grant type utilizes both endpoints. 603 Extension grant types MAY define additional endpoints as needed. 605 3.1. Authorization Endpoint 607 The authorization endpoint is used to interact with the resource 608 owner and obtain authorization which is expressed explicitly as an 609 authorization code (later exchanged for an access token), or 610 implicitly by direct issuance of an access token. 612 The authorization server MUST first verify the identity of the 613 resource owner. The way in which the authorization server 614 authenticates the resource owner (e.g. username and password login, 615 session cookies) is beyond the scope of this specification. 617 The means through which the client obtains the location of the 618 authorization endpoint are beyond the scope of this specification but 619 the location is typically provided in the service documentation. The 620 endpoint URI MAY include a query component as defined by [RFC3986] 621 section 3, which MUST be retained when adding additional query 622 parameters. The endpoint URI MUST NOT include a fragment component. 624 Since requests to the authorization endpoint result in user 625 authentication and the transmission of clear-text credentials (in the 626 HTTP response), the authorization server MUST require the use of a 627 transport-layer security mechanism when sending requests to the 628 authorization endpoint. The authorization server MUST support TLS 629 1.2 as defined in [RFC5246], and MAY support additional transport- 630 layer mechanisms meeting its security requirements. 632 The authorization server MUST support the use of the HTTP "GET" 633 method [RFC2616] for the authorization endpoint, and MAY support the 634 use of the "POST" method as well. 636 Parameters sent without a value MUST be treated as if they were 637 omitted from the request. The authorization server SHOULD ignore 638 unrecognized request parameters. Request and response parameters 639 MUST NOT be included more than once. 641 3.1.1. Response Type 643 The authorization endpoint is used by the authorization code grant 644 type and implicit grant type flows. The client informs the 645 authorization server of the desired grant type using the following 646 parameter: 648 response_type 649 REQUIRED. The value MUST be one of "code" for requesting an 650 authorization code as described by Section 4.1.1, "token" for 651 requesting an access token (implicit grant) as described by 652 Section 4.2.1, or a registered extension value as described by 653 Section 8.4. 655 If an authorization request is missing the "response_type" parameter, 656 the authorization server SHOULD return an error response as described 657 in Section 4.1.2.1. 659 3.1.2. Redirection URI 661 [[ Pending Consensus ]] 663 After completing its interaction with the resource owner, the 664 authorization server directs the resource owner's user-agent back to 665 the client. The authorization server redirects the user-agent to the 666 client's redirection URI previously established with the 667 authorization server during the client registration process. 669 The redirection URI MUST be an absolute URI as defined by [RFC3986] 670 section 4.3, MAY include a query component which MUST be retained by 671 the authorization server when adding additional query parameters, and 672 MUST NOT include a fragment component. 674 3.1.2.1. Endpoint Confidentiality 676 If a redirection request will result in the transmission of an 677 authorization code or access token over an open network (between the 678 resource owner's user-agent and the client), the client SHOULD 679 require the use of a transport-layer security mechanism. 681 Lack of transport-layer security can have a severe impact on the 682 security of the client and the protected resources it is authorized 683 to access. The use of transport-layer security is particularly 684 critical when the authorization process is used as a form of 685 delegated end-user authentication by the client (e.g. third-party 686 sign-in service). 688 3.1.2.2. Registration Requirements 690 The authorization server MUST require public clients to register 691 their redirection URI, MUST require all clients to register their 692 redirection URI prior to utilizing the implicit grant type, and 693 SHOULD require all clients to register their redirection URI prior to 694 utilizing the authorization code grant type. 696 The authorization server SHOULD require the client to provide the 697 complete redirection URI (the client MAY use the "state" request 698 parameter to achieve per-request customization). The authorization 699 server MAY allow the client to register multiple redirection URIs. 700 If requiring the registration of the complete redirection URI is not 701 possible, the authorization server SHOULD require the registration of 702 the URI scheme, authority, and path. 704 3.1.2.3. Dynamic Configuration 706 If multiple redirection URIs have been registered, if only part of 707 the redirection URI has been registered, or if no redirection URI has 708 been registered, the client MUST include a redirection URI with the 709 authorization request using the "redirect_uri" request parameter. 711 When a redirection URI is included in an authorization request, the 712 authorization server MUST compare and match the value received 713 against at least one of the registered redirection URIs (or URI 714 components) as defined in [RFC3986] section 6, if any redirection 715 URIs were registered. 717 If the authorization server allows the client to dynamically change 718 the query component of the redirection URI, the client MUST ensure 719 that manipulation of the query component by an attacker cannot lead 720 to an abuse of the redirection endpoint as an open redirector. 722 3.1.2.4. Invalid Endpoint 724 If an authorization request fails validation due to a missing, 725 invalid, or mismatching redirection URI, the authorization server 726 SHOULD inform the resource owner of the error, and MUST NOT 727 automatically redirect the user-agent to the invalid redirection URI. 729 The authorization server SHOULD NOT redirect the user-agent to 730 unregistered or untrusted URIs to prevent the authorization endpoint 731 from being used as an open redirector. 733 3.1.2.5. Endpoint Content 735 The redirection request to the client's endpoint typically results in 736 an HTML document response, processed by the user-agent. If the HTML 737 response is served directly as the result of the redirection request, 738 any script included in the HTML document will execute with full 739 access to the redirection URI and the credentials it contains. 741 The client SHOULD NOT include any third-party scripts in the 742 redirection endpoint response. Instead, it should extract the 743 credentials from the URI and redirect the user-agent again to another 744 endpoint without the credentials in the URI. 746 The client MUST NOT include any untrusted third-party scripts in the 747 redirection endpoint response (e.g. third-party analytics, social 748 plug-ins, ad networks) without first ensuring that its own scripts 749 used to extract and remove the credentials from the URI will execute 750 first. 752 3.2. Token Endpoint 754 The token endpoint is used by the client to obtain an access token by 755 presenting its authorization grant or refresh token. The token 756 endpoint is used with every authorization grant except for the 757 implicit grant type (since an access token is issued directly). 759 The means through which the client obtains the location of the token 760 endpoint are beyond the scope of this specification but is typically 761 provided in the service documentation. The endpoint URI MAY include 762 a query component, which MUST be retained when adding additional 763 query parameters. 765 Since requests to the token endpoint result in the transmission of 766 clear-text credentials (in the HTTP request and response), the 767 authorization server MUST require the use of a transport-layer 768 security mechanism when sending requests to the token endpoint. The 769 authorization server MUST support TLS 1.2 as defined in [RFC5246], 770 and MAY support additional transport-layer mechanisms meeting its 771 security requirements. 773 The client MUST use the HTTP "POST" method when making access token 774 requests. 776 Parameters sent without a value MUST be treated as if they were 777 omitted from the request. The authorization server SHOULD ignore 778 unrecognized request parameters. Request and response parameters 779 MUST NOT be included more than once. 781 3.2.1. Client Authentication 783 [[ Pending Consensus ]] 785 Private clients, clients issued client credentials, or clients 786 assigned other authentication requirements, MUST authenticate with 787 the authorization server as described in Section 2.4 when making 788 requests to the token endpoint. Client authentication is used for: 790 o Enforcing the binding of refresh tokens and authorization codes to 791 the client they are issued. Client authentication is critical 792 when an authorization code is transmitted to the redirection URI 793 endpoint over an insecure channel, or when the redirection URI has 794 not been registered in full. 795 o Recovery from a compromised client by disabling the client or 796 changing its credentials, by preventing an attacker from abusing 797 stolen refresh tokens. Changing a single set of client 798 credentials is significantly faster than revoking an entire set of 799 refresh tokens. 801 o Implementing authentication management best practices which 802 require periodic credentials rotation. Rotation of an entire set 803 of refresh tokens can be challenging, while rotation of a single 804 set of client credentials is significantly easier. In addition, 805 this specification does not provide a mechanism for refresh token 806 rotation. 808 The security ramifications of allowing unauthenticated access by 809 public clients to the token endpoint MUST be considered, as well as 810 the issuance of refresh tokens to public clients, their scope, and 811 lifetime. 813 4. Obtaining Authorization 815 To request an access token, the client obtains authorization from the 816 resource owner. The authorization is expressed in the form of an 817 authorization grant which the client uses to request the access 818 token. OAuth defines four grant types: authorization code, implicit, 819 resource owner password credentials, and client credentials. It also 820 provides an extension mechanism for defining additional grant types. 822 4.1. Authorization Code 824 The authorization code grant type is used to obtain both access 825 tokens and refresh tokens and is optimized for private clients. As a 826 redirection-based flow, the client must be capable of interacting 827 with the resource owner's user-agent (typically a web browser) and 828 capable of receiving incoming requests (via redirection) from the 829 authorization server. 831 +----------+ 832 | resource | 833 | owner | 834 | | 835 +----------+ 836 ^ 837 | 838 (B) 839 +----|-----+ Client Identifier +---------------+ 840 | -+----(A)-- & Redirection URI ---->| | 841 | User- | | Authorization | 842 | Agent -+----(B)-- User authenticates --->| Server | 843 | | | | 844 | -+----(C)-- Authorization Code ---<| | 845 +-|----|---+ +---------------+ 846 | | ^ v 847 (A) (C) | | 848 | | | | 849 ^ v | | 850 +---------+ | | 851 | |>---(D)-- Authorization Code ---------' | 852 | Client | & Redirection URI | 853 | | | 854 | |<---(E)----- Access Token -------------------' 855 +---------+ (w/ Optional Refresh Token) 857 Figure 3: Authorization Code Flow 859 The flow illustrated in Figure 3 includes the following steps: 861 (A) The client initiates the flow by directing the resource owner's 862 user-agent to the authorization endpoint. The client includes 863 its client identifier, requested scope, local state, and a 864 redirection URI to which the authorization server will send the 865 user-agent back once access is granted (or denied). 866 (B) The authorization server authenticates the resource owner (via 867 the user-agent) and establishes whether the resource owner 868 grants or denies the client's access request. 869 (C) Assuming the resource owner grants access, the authorization 870 server redirects the user-agent back to the client using the 871 redirection URI provided earlier. The redirection URI includes 872 an authorization code and any local state provided by the client 873 earlier. 875 (D) The client requests an access token from the authorization 876 server's token endpoint by including the authorization code 877 received in the previous step. When making the request, the 878 client authenticates with the authorization server. The client 879 includes the redirection URI used to obtain the authorization 880 code for verification. 881 (E) The authorization server authenticates the client, validates the 882 authorization code, and ensures the redirection URI received 883 matches the URI used to redirect the client in step (C). If 884 valid, responds back with an access token. 886 4.1.1. Authorization Request 888 The client constructs the request URI by adding the following 889 parameters to the query component of the authorization endpoint URI 890 using the "application/x-www-form-urlencoded" format as defined by 891 [W3C.REC-html401-19991224]: 893 response_type 894 REQUIRED. Value MUST be set to "code". 895 client_id 896 REQUIRED. The client identifier as described in Section 2.3. 897 redirect_uri 898 OPTIONAL, as described in Section 3.1.2. 899 scope 900 OPTIONAL. The scope of the access request expressed as a list 901 of space-delimited, case sensitive strings. The value is 902 defined by the authorization server. If the value contains 903 multiple space-delimited strings, their order does not matter, 904 and each string adds an additional access range to the 905 requested scope. 906 state 907 OPTIONAL. An opaque value used by the client to maintain state 908 between the request and callback. The authorization server 909 includes this value when redirecting the user-agent back to the 910 client. 912 The client directs the resource owner to the constructed URI using an 913 HTTP redirection response, or by other means available to it via the 914 user-agent. 916 For example, the client directs the user-agent to make the following 917 HTTP request using transport-layer security (extra line breaks are 918 for display purposes only): 920 GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz 921 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 923 Host: server.example.com 925 The authorization server validates the request to ensure all required 926 parameters are present and valid. If the request is valid, the 927 authorization server authenticates the resource owner and obtains an 928 authorization decision (by asking the resource owner or by 929 establishing approval via other means). 931 When a decision is established, the authorization server directs the 932 user-agent to the provided client redirection URI using an HTTP 933 redirection response, or by other means available to it via the user- 934 agent. 936 4.1.2. Authorization Response 938 If the resource owner grants the access request, the authorization 939 server issues an authorization code and delivers it to the client by 940 adding the following parameters to the query component of the 941 redirection URI using the "application/x-www-form-urlencoded" format: 943 code 944 REQUIRED. The authorization code generated by the 945 authorization server. The authorization code MUST expire 946 shortly after it is issued to mitigate the risk of leaks. A 947 maximum authorization code lifetime of 10 minutes is 948 RECOMMENDED. The client MUST NOT reuse the authorization code. 949 If an authorization code is used more than once, the 950 authorization server SHOULD attempt to revoke all tokens 951 previously issued based on that authorization code. The 952 authorization code is bound to the client identifier and 953 redirection URI. 954 state 955 REQUIRED if the "state" parameter was present in the client 956 authorization request. Set to the exact value received from 957 the client. 959 For example, the authorization server redirects the user-agent by 960 sending the following HTTP response: 962 HTTP/1.1 302 Found 963 Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA 964 &state=xyz 966 The client SHOULD ignore unrecognized response parameters. The 967 authorization code string size is left undefined by this 968 specification. The client should avoid making assumptions about code 969 value sizes. The authorization server should document the size of 970 any value it issues. 972 4.1.2.1. Error Response 974 If the request fails due to a missing, invalid, or mismatching 975 redirection URI, or if the client identifier provided is invalid, the 976 authorization server SHOULD inform the resource owner of the error, 977 and MUST NOT automatically redirect the user-agent to the invalid 978 redirection URI. 980 If the resource owner denies the access request or if the request 981 fails for reasons other than a missing or invalid redirection URI, 982 the authorization server informs the client by adding the following 983 parameters to the query component of the redirection URI using the 984 "application/x-www-form-urlencoded" format: 986 error 987 REQUIRED. A single error code from the following: 988 invalid_request 989 The request is missing a required parameter, includes an 990 unsupported parameter or parameter value, or is otherwise 991 malformed. 992 unauthorized_client 993 The client is not authorized to request an authorization 994 code using this method. 995 access_denied 996 The resource owner or authorization server denied the 997 request. 998 unsupported_response_type 999 The authorization server does not support obtaining an 1000 authorization code using this method. 1001 invalid_scope 1002 The requested scope is invalid, unknown, or malformed. 1003 server_error 1004 The authorization server encountered an unexpected 1005 condition which prevented it from fulfilling the request. 1006 temporarily_unavailable 1007 The authorization server is currently unable to handle 1008 the request due to a temporary overloading or maintenance 1009 of the server. 1010 error_description 1011 OPTIONAL. A human-readable UTF-8 encoded text providing 1012 additional information, used to assist the client developer in 1013 understanding the error that occurred. 1015 error_uri 1016 OPTIONAL. A URI identifying a human-readable web page with 1017 information about the error, used to provide the client 1018 developer with additional information about the error. 1019 state 1020 REQUIRED if a valid "state" parameter was present in the client 1021 authorization request. Set to the exact value received from 1022 the client. 1024 For example, the authorization server redirects the user-agent by 1025 sending the following HTTP response: 1027 HTTP/1.1 302 Found 1028 Location: https://client.example.com/cb?error=access_denied&state=xyz 1030 4.1.3. Access Token Request 1032 The client makes a request to the token endpoint by adding the 1033 following parameters using the "application/x-www-form-urlencoded" 1034 format in the HTTP request entity-body: 1036 grant_type 1037 REQUIRED. Value MUST be set to "authorization_code". 1038 code 1039 REQUIRED. The authorization code received from the 1040 authorization server. 1041 redirect_uri 1042 REQUIRED, if the "redirect_uri" parameter was included in the 1043 authorization request described in Section 4.1.1, and their 1044 values MUST be identical. 1046 If the client type is private or was issued client credentials (or 1047 assigned other authentication requirements), the client MUST 1048 authenticate with the authorization server as described in 1049 Section 3.2.1. 1051 For example, the client makes the following HTTP using transport- 1052 layer security (extra line breaks are for display purposes only): 1054 POST /token HTTP/1.1 1055 Host: server.example.com 1056 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1057 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1059 grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA 1060 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 1062 The authorization server MUST: 1064 o require client authentication for private clients or for any 1065 client issued client credentials (or with other authentication 1066 requirements), 1067 o authenticate the client if client authentication is included and 1068 ensure the authorization code was issued to the authenticated 1069 client, 1070 o verify that the authorization code is valid, and 1071 o ensure that the "redirect_uri" parameter is present if the 1072 "redirect_uri" parameter was included in the initial authorization 1073 request described in Section 4.1.1, and that their values are 1074 identical. 1076 4.1.4. Access Token Response 1078 If the access token request is valid and authorized, the 1079 authorization server issues an access token and optional refresh 1080 token as described in Section 5.1. If the request client 1081 authentication failed or is invalid, the authorization server returns 1082 an error response as described in Section 5.2. 1084 An example successful response: 1086 HTTP/1.1 200 OK 1087 Content-Type: application/json;charset=UTF-8 1088 Cache-Control: no-store 1089 Pragma: no-cache 1091 { 1092 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1093 "token_type":"example", 1094 "expires_in":3600, 1095 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1096 "example_parameter":"example_value" 1097 } 1099 4.2. Implicit Grant 1101 The implicit grant type is used to obtain access tokens (it does not 1102 support the issuance of refresh tokens) and is optimized for public 1103 clients known to operate a particular redirection URI. These clients 1104 are typically implemented in a browser using a scripting language 1105 such as JavaScript. 1107 As a redirection-based flow, the client must be capable of 1108 interacting with the resource owner's user-agent (typically a web 1109 browser) and capable of receiving incoming requests (via redirection) 1110 from the authorization server. 1112 Unlike the authorization code grant type in which the client makes 1113 separate requests for authorization and access token, the client 1114 receives the access token as the result of the authorization request. 1116 The implicit grant type does not include client authentication, and 1117 relies on the presence of the resource owner and the registration of 1118 the redirection URI. Because the access token is encoded into the 1119 redirection URI, it may be exposed to the resource owner and other 1120 applications residing on its device. 1122 +----------+ 1123 | Resource | 1124 | Owner | 1125 | | 1126 +----------+ 1127 ^ 1128 | 1129 (B) 1130 +----|-----+ Client Identifier +---------------+ 1131 | -+----(A)-- & Redirection URI --->| | 1132 | User- | | Authorization | 1133 | Agent -|----(B)-- User authenticates -->| Server | 1134 | | | | 1135 | |<---(C)--- Redirection URI ----<| | 1136 | | with Access Token +---------------+ 1137 | | in Fragment 1138 | | +---------------+ 1139 | |----(D)--- Redirection URI ---->| Web-Hosted | 1140 | | without Fragment | Client | 1141 | | | Resource | 1142 | (F) |<---(E)------- Script ---------<| | 1143 | | +---------------+ 1144 +-|--------+ 1145 | | 1146 (A) (G) Access Token 1147 | | 1148 ^ v 1149 +---------+ 1150 | | 1151 | Client | 1152 | | 1153 +---------+ 1155 Figure 4: Implicit Grant Flow 1157 The flow illustrated in Figure 4 includes the following steps: 1159 (A) The client initiates the flow by directing the resource owner's 1160 user-agent to the authorization endpoint. The client includes 1161 its client identifier, requested scope, local state, and a 1162 redirection URI to which the authorization server will send the 1163 user-agent back once access is granted (or denied). 1164 (B) The authorization server authenticates the resource owner (via 1165 the user-agent) and establishes whether the resource owner 1166 grants or denies the client's access request. 1168 (C) Assuming the resource owner grants access, the authorization 1169 server redirects the user-agent back to the client using the 1170 redirection URI provided earlier. The redirection URI includes 1171 the access token in the URI fragment. 1172 (D) The user-agent follows the redirection instructions by making a 1173 request to the web-hosted client resource (which does not 1174 include the fragment). The user-agent retains the fragment 1175 information locally. 1176 (E) The web-hosted client resource returns a web page (typically an 1177 HTML document with an embedded script) capable of accessing the 1178 full redirection URI including the fragment retained by the 1179 user-agent, and extracting the access token (and other 1180 parameters) contained in the fragment. 1181 (F) The user-agent executes the script provided by the web-hosted 1182 client resource locally, which extracts the access token and 1183 passes it to the client. 1185 4.2.1. Authorization Request 1187 The client constructs the request URI by adding the following 1188 parameters to the query component of the authorization endpoint URI 1189 using the "application/x-www-form-urlencoded" format: 1191 response_type 1192 REQUIRED. Value MUST be set to "token". 1193 client_id 1194 REQUIRED. The client identifier as described in Section 2.3. 1195 redirect_uri 1196 OPTIONAL, as described in Section 3.1.2. 1197 scope 1198 OPTIONAL. The scope of the access request expressed as a list 1199 of space-delimited, case sensitive strings. The value is 1200 defined by the authorization server. If the value contains 1201 multiple space-delimited strings, their order does not matter, 1202 and each string adds an additional access range to the 1203 requested scope. 1204 state 1205 OPTIONAL. An opaque value used by the client to maintain state 1206 between the request and callback. The authorization server 1207 includes this value when redirecting the user-agent back to the 1208 client. 1210 The client directs the resource owner to the constructed URI using an 1211 HTTP redirection response, or by other means available to it via the 1212 user-agent. 1214 For example, the client directs the user-agent to make the following 1215 HTTP request using transport-layer security (extra line breaks are 1216 for display purposes only): 1218 GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz 1219 &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1220 Host: server.example.com 1222 The authorization server validates the request to ensure all required 1223 parameters are present and valid. The authorization server MUST 1224 verify that the redirection URI to which it will redirect the access 1225 token matches a redirection URI registered by the client as described 1226 in Section 3.1.2. 1228 If the request is valid, the authorization server authenticates the 1229 resource owner and obtains an authorization decision (by asking the 1230 resource owner or by establishing approval via other means). 1232 When a decision is established, the authorization server directs the 1233 user-agent to the provided client redirection URI using an HTTP 1234 redirection response, or by other means available to it via the user- 1235 agent. 1237 4.2.2. Access Token Response 1239 If the resource owner grants the access request, the authorization 1240 server issues an access token and delivers it to the client by adding 1241 the following parameters to the fragment component of the redirection 1242 URI using the "application/x-www-form-urlencoded" format: 1244 access_token 1245 REQUIRED. The access token issued by the authorization server. 1246 token_type 1247 REQUIRED. The type of the token issued as described in 1248 Section 7.1. Value is case insensitive. 1249 expires_in 1250 OPTIONAL. The lifetime in seconds of the access token. For 1251 example, the value "3600" denotes that the access token will 1252 expire in one hour from the time the response was generated. 1253 scope 1254 OPTIONAL. The scope of the access token expressed as a list of 1255 space-delimited, case sensitive strings. The value is defined 1256 by the authorization server. If the value contains multiple 1257 space-delimited strings, their order does not matter, and each 1258 string adds an additional access range to the requested scope. 1259 The authorization server SHOULD include the parameter if the 1260 access token scope is different from the one requested by the 1261 client. 1262 state 1263 REQUIRED if the "state" parameter was present in the client 1264 authorization request. Set to the exact value received from 1265 the client. 1267 For example, the authorization server redirects the user-agent by 1268 sending the following HTTP response (URI extra line breaks are for 1269 display purposes only): 1271 HTTP/1.1 302 Found 1272 Location: http://example.com/rd#access_token=2YotnFZFEjr1zCsicMWpAA 1273 &state=xyz&token_type=example&expires_in=3600 1275 Developers should note that some HTTP client implementations do not 1276 support the inclusion of a fragment component in the HTTP "Location" 1277 response header field. Such client will require using other methods 1278 for redirecting the client than a 3xx redirection response. For 1279 example, returning an HTML page which includes a 'continue' button 1280 with an action linked to the redirection URI. 1282 The client SHOULD ignore unrecognized response parameters. The 1283 access token string size is left undefined by this specification. 1284 The client should avoid making assumptions about value sizes. The 1285 authorization server should document the size of any value it issues. 1287 4.2.2.1. Error Response 1289 If the request fails due to a missing, invalid, or mismatching 1290 redirection URI, or if the client identifier provided is invalid, the 1291 authorization server SHOULD inform the resource owner of the error, 1292 and MUST NOT automatically redirect the user-agent to the invalid 1293 redirection URI. 1295 If the resource owner denies the access request or if the request 1296 fails for reasons other than a missing or invalid redirection URI, 1297 the authorization server informs the client by adding the following 1298 parameters to the fragment component of the redirection URI using the 1299 "application/x-www-form-urlencoded" format: 1301 error 1302 REQUIRED. A single error code from the following: 1304 invalid_request 1305 The request is missing a required parameter, includes an 1306 unsupported parameter or parameter value, or is otherwise 1307 malformed. 1308 unauthorized_client 1309 The client is not authorized to request an access token 1310 using this method. 1311 access_denied 1312 The resource owner or authorization server denied the 1313 request. 1314 unsupported_response_type 1315 The authorization server does not support obtaining an 1316 access token using this method. 1317 invalid_scope 1318 The requested scope is invalid, unknown, or malformed. 1319 server_error 1320 The authorization server encountered an unexpected 1321 condition which prevented it from fulfilling the request. 1322 temporarily_unavailable 1323 The authorization server is currently unable to handle 1324 the request due to a temporary overloading or maintenance 1325 of the server. 1326 error_description 1327 OPTIONAL. A human-readable UTF-8 encoded text providing 1328 additional information, used to assist the client developer in 1329 understanding the error that occurred. 1330 error_uri 1331 OPTIONAL. A URI identifying a human-readable web page with 1332 information about the error, used to provide the client 1333 developer with additional information about the error. 1334 state 1335 REQUIRED if a valid "state" parameter was present in the client 1336 authorization request. Set to the exact value received from 1337 the client. 1339 For example, the authorization server redirects the user-agent by 1340 sending the following HTTP response: 1342 HTTP/1.1 302 Found 1343 Location: https://client.example.com/cb#error=access_denied&state=xyz 1345 4.3. Resource Owner Password Credentials 1347 The resource owner password credentials grant type is suitable in 1348 cases where the resource owner has a trust relationship with the 1349 client, such as its device operating system or a highly privileged 1350 application. The authorization server should take special care when 1351 enabling the grant type, and only when other flows are not viable. 1353 The grant type is suitable for clients capable of obtaining the 1354 resource owner credentials (username and password, typically using an 1355 interactive form). It is also used to migrate existing clients using 1356 direct authentication schemes such as HTTP Basic or Digest 1357 authentication to OAuth by converting the stored credentials to an 1358 access token. 1360 +----------+ 1361 | Resource | 1362 | Owner | 1363 | | 1364 +----------+ 1365 v 1366 | Resource Owner 1367 (A) Password Credentials 1368 | 1369 v 1370 +---------+ +---------------+ 1371 | |>--(B)---- Resource Owner ------->| | 1372 | | Password Credentials | Authorization | 1373 | Client | | Server | 1374 | |<--(C)---- Access Token ---------<| | 1375 | | (w/ Optional Refresh Token) | | 1376 +---------+ +---------------+ 1378 Figure 5: Resource Owner Password Credentials Flow 1380 The flow illustrated in Figure 5 includes the following steps: 1382 (A) The resource owner provides the client with its username and 1383 password. 1384 (B) The client requests an access token from the authorization 1385 server's token endpoint by including the credentials received 1386 from the resource owner. When making the request, the client 1387 authenticates with the authorization server. 1388 (C) The authorization server authenticates the client and validates 1389 the resource owner credentials, and if valid issues an access 1390 token. 1392 4.3.1. Authorization Request and Response 1394 The method through which the client obtains the resource owner 1395 credentials is beyond the scope of this specification. The client 1396 MUST discard the credentials once an access token has been obtained. 1398 4.3.2. Access Token Request 1400 The client makes a request to the token endpoint by adding the 1401 following parameters using the "application/x-www-form-urlencoded" 1402 format in the HTTP request entity-body: 1404 grant_type 1405 REQUIRED. Value MUST be set to "password". 1406 username 1407 REQUIRED. The resource owner username, encoded as UTF-8. 1408 password 1409 REQUIRED. The resource owner password, encoded as UTF-8. 1410 scope 1411 OPTIONAL. The scope of the access request expressed as a list 1412 of space-delimited, case sensitive strings. The value is 1413 defined by the authorization server. If the value contains 1414 multiple space-delimited strings, their order does not matter, 1415 and each string adds an additional access range to the 1416 requested scope. 1418 If the client type is private or was issued client credentials (or 1419 assigned other authentication requirements), the client MUST 1420 authenticate with the authorization server as described in 1421 Section 3.2.1. 1423 For example, the client makes the following HTTP request using 1424 transport-layer security (extra line breaks are for display purposes 1425 only): 1427 POST /token HTTP/1.1 1428 Host: server.example.com 1429 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1430 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1432 grant_type=password&username=johndoe&password=A3ddj3w 1434 The authorization server MUST: 1436 o require client authentication for private clients or for any 1437 client issued client credentials (or with other authentication 1438 requirements), 1439 o authenticate the client if client authentication is included, and 1440 o validate the resource owner password credentials. 1442 Since this access token request utilizes the resource owner's 1443 password, the authorization server MUST protect the endpoint against 1444 brute force attacks. 1446 4.3.3. Access Token Response 1448 If the access token request is valid and authorized, the 1449 authorization server issues an access token and optional refresh 1450 token as described in Section 5.1. If the request failed client 1451 authentication or is invalid, the authorization server returns an 1452 error response as described in Section 5.2. 1454 An example successful response: 1456 HTTP/1.1 200 OK 1457 Content-Type: application/json;charset=UTF-8 1458 Cache-Control: no-store 1459 Pragma: no-cache 1461 { 1462 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1463 "token_type":"example", 1464 "expires_in":3600, 1465 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1466 "example_parameter":"example_value" 1467 } 1469 4.4. Client Credentials 1471 The client can request an access token using only its client 1472 credentials (or other supported means of authentication) when the 1473 client is requesting access to the protected resources under its 1474 control, or those of another resource owner which has been previously 1475 arranged with the authorization server (the method of which is beyond 1476 the scope of this specification). 1478 The client credentials grant type MUST only be used by private 1479 clients. 1481 +---------+ +---------------+ 1482 | | | | 1483 | |>--(A)- Client Authentication --->| Authorization | 1484 | Client | | Server | 1485 | |<--(B)---- Access Token ---------<| | 1486 | | | | 1487 +---------+ +---------------+ 1489 Figure 6: Client Credentials Flow 1491 The flow illustrated in Figure 6 includes the following steps: 1493 (A) The client authenticates with the authorization server and 1494 requests an access token from the token endpoint. 1495 (B) The authorization server authenticates the client, and if valid 1496 issues an access token. 1498 4.4.1. Authorization Request and Response 1500 Since the client authentication is used as the authorization grant, 1501 no additional authorization request is needed. 1503 4.4.2. Access Token Request 1505 The client makes a request to the token endpoint by adding the 1506 following parameters using the "application/x-www-form-urlencoded" 1507 format in the HTTP request entity-body: 1509 grant_type 1510 REQUIRED. Value MUST be set to "client_credentials". 1511 scope 1512 OPTIONAL. The scope of the access request expressed as a list 1513 of space-delimited, case sensitive strings. The value is 1514 defined by the authorization server. If the value contains 1515 multiple space-delimited strings, their order does not matter, 1516 and each string adds an additional access range to the 1517 requested scope. 1519 The client MUST authenticate with the authorization server as 1520 described in Section 3.2.1. 1522 For example, the client makes the following HTTP request using 1523 transport-layer security (extra line breaks are for display purposes 1524 only): 1526 POST /token HTTP/1.1 1527 Host: server.example.com 1528 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1529 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1531 grant_type=client_credentials 1533 The authorization server MUST authenticate the client. 1535 4.4.3. Access Token Response 1537 If the access token request is valid and authorized, the 1538 authorization server issues an access token as described in 1539 Section 5.1. A refresh token SHOULD NOT be included. If the request 1540 failed client authentication or is invalid, the authorization server 1541 returns an error response as described in Section 5.2. 1543 An example successful response: 1545 HTTP/1.1 200 OK 1546 Content-Type: application/json;charset=UTF-8 1547 Cache-Control: no-store 1548 Pragma: no-cache 1550 { 1551 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1552 "token_type":"example", 1553 "expires_in":3600, 1554 "example_parameter":"example_value" 1555 } 1557 4.5. Extensions 1559 The client uses an extension grant type by specifying the grant type 1560 using an absolute URI (defined by the authorization server) as the 1561 value of the "grant_type" parameter of the token endpoint, and by 1562 adding any additional parameters necessary. 1564 For example, to request an access token using a SAML 2.0 assertion 1565 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1566 makes the following HTTP request using transport-layer security (line 1567 breaks are for display purposes only): 1569 POST /token HTTP/1.1 1570 Host: server.example.com 1571 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1573 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F 1574 saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ 1575 [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1577 If the access token request is valid and authorized, the 1578 authorization server issues an access token and optional refresh 1579 token as described in Section 5.1. If the request failed client 1580 authentication or is invalid, the authorization server returns an 1581 error response as described in Section 5.2. 1583 5. Issuing an Access Token 1585 If the access token request is valid and authorized, the 1586 authorization server issues an access token and optional refresh 1587 token as described in Section 5.1. If the request failed client 1588 authentication or is invalid, the authorization server returns an 1589 error response as described in Section 5.2. 1591 5.1. Successful Response 1593 The authorization server issues an access token and optional refresh 1594 token, and constructs the response by adding the following parameters 1595 to the entity body of the HTTP response with a 200 (OK) status code: 1597 access_token 1598 REQUIRED. The access token issued by the authorization server. 1599 token_type 1600 REQUIRED. The type of the token issued as described in 1601 Section 7.1. Value is case insensitive. 1602 expires_in 1603 OPTIONAL. The lifetime in seconds of the access token. For 1604 example, the value "3600" denotes that the access token will 1605 expire in one hour from the time the response was generated. 1607 refresh_token 1608 OPTIONAL. The refresh token which can be used to obtain new 1609 access tokens using the same authorization grant as described 1610 in Section 6. 1611 scope 1612 OPTIONAL. The scope of the access token expressed as a list of 1613 space-delimited, case sensitive strings. The value is defined 1614 by the authorization server. If the value contains multiple 1615 space-delimited strings, their order does not matter, and each 1616 string adds an additional access range to the requested scope. 1617 The authorization server SHOULD include the parameter if the 1618 access token scope is different from the one requested by the 1619 client. 1621 The parameters are included in the entity body of the HTTP response 1622 using the "application/json" media type as defined by [RFC4627]. The 1623 parameters are serialized into a JSON structure by adding each 1624 parameter at the highest structure level. Parameter names and string 1625 values are included as JSON strings. Numerical values are included 1626 as JSON numbers. 1628 The authorization server MUST include the HTTP "Cache-Control" 1629 response header field [RFC2616] with a value of "no-store" in any 1630 response containing tokens, credentials, or other sensitive 1631 information, as well as the "Pragma" response header field [RFC2616] 1632 with a value of "no-cache". 1634 For example: 1636 HTTP/1.1 200 OK 1637 Content-Type: application/json;charset=UTF-8 1638 Cache-Control: no-store 1639 Pragma: no-cache 1641 { 1642 "access_token":"2YotnFZFEjr1zCsicMWpAA", 1643 "token_type":"example", 1644 "expires_in":3600, 1645 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 1646 "example_parameter":"example_value" 1647 } 1649 The client SHOULD ignore unrecognized response parameters. The sizes 1650 of tokens and other values received from the authorization server are 1651 left undefined. The client should avoid making assumptions about 1652 value sizes. The authorization server should document the size of 1653 any value it issues. 1655 5.2. Error Response 1657 The authorization server responds with an HTTP 400 (Bad Request) 1658 status code and includes the following parameters with the response: 1660 error 1661 REQUIRED. A single error code from the following: 1662 invalid_request 1663 The request is missing a required parameter, includes an 1664 unsupported parameter or parameter value, repeats a 1665 parameter, includes multiple credentials, utilizes more 1666 than one mechanism for authenticating the client, or is 1667 otherwise malformed. 1668 invalid_client 1669 Client authentication failed (e.g. unknown client, no 1670 client authentication included, multiple client 1671 authentications included, or unsupported authentication 1672 method). The authorization server MAY return an HTTP 401 1673 (Unauthorized) status code to indicate which HTTP 1674 authentication schemes are supported. If the client 1675 attempted to authenticate via the "Authorization" request 1676 header field, the authorization server MUST respond with 1677 an HTTP 401 (Unauthorized) status code, and include the 1678 "WWW-Authenticate" response header field matching the 1679 authentication scheme used by the client. 1680 invalid_grant 1681 The provided authorization grant is invalid, expired, 1682 revoked, does not match the redirection URI used in the 1683 authorization request, or was issued to another client. 1684 unauthorized_client 1685 The authenticated client is not authorized to use this 1686 authorization grant type. 1687 unsupported_grant_type 1688 The authorization grant type is not supported by the 1689 authorization server. 1690 invalid_scope 1691 The requested scope is invalid, unknown, malformed, or 1692 exceeds the scope granted by the resource owner. 1693 error_description 1694 OPTIONAL. A human-readable UTF-8 encoded text providing 1695 additional information, used to assist the client developer in 1696 understanding the error that occurred. 1698 error_uri 1699 OPTIONAL. A URI identifying a human-readable web page with 1700 information about the error, used to provide the client 1701 developer with additional information about the error. 1703 The parameters are included in the entity body of the HTTP response 1704 using the "application/json" media type as defined by [RFC4627]. The 1705 parameters are serialized into a JSON structure by adding each 1706 parameter at the highest structure level. Parameter names and string 1707 values are included as JSON strings. Numerical values are included 1708 as JSON numbers. 1710 For example: 1712 HTTP/1.1 400 Bad Request 1713 Content-Type: application/json;charset=UTF-8 1714 Cache-Control: no-store 1715 Pragma: no-cache 1717 { 1718 "error":"invalid_request" 1719 } 1721 6. Refreshing an Access Token 1723 If the authorization server issued a refresh token to the client, the 1724 client makes a refresh request to the token endpoint by adding the 1725 following parameters using the "application/x-www-form-urlencoded" 1726 format in the HTTP request entity-body: 1728 grant_type 1729 REQUIRED. Value MUST be set to "refresh_token". 1730 refresh_token 1731 REQUIRED. The refresh token issued to the client. 1732 scope 1733 OPTIONAL. The scope of the access request expressed as a list 1734 of space-delimited, case sensitive strings. The value is 1735 defined by the authorization server. If the value contains 1736 multiple space-delimited strings, their order does not matter, 1737 and each string adds an additional access range to the 1738 requested scope. The requested scope MUST be equal or lesser 1739 than the scope originally granted by the resource owner, and if 1740 omitted is treated as equal to the scope originally granted by 1741 the resource owner. 1743 Because refresh tokens are typically long-lasting credentials used to 1744 request additional access tokens, the refresh token is bound to the 1745 client it was issued. If the client type is private or was issued 1746 client credentials (or assigned other authentication requirements), 1747 the client MUST authenticate with the authorization server as 1748 described in Section 3.2.1. 1750 For example, the client makes the following HTTP request using 1751 transport-layer security (extra line breaks are for display purposes 1752 only): 1754 POST /token HTTP/1.1 1755 Host: server.example.com 1756 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 1757 Content-Type: application/x-www-form-urlencoded;charset=UTF-8 1759 grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA 1761 The authorization server MUST: 1763 o require client authentication for private clients or for any 1764 client issued client credentials (or with other authentication 1765 requirements), 1766 o authenticate the client if client authentication is included and 1767 ensure the refresh token was issued to the authenticated client, 1768 o validate the refresh token, and 1769 o verify that the resource owner's authorization is still valid. 1771 If valid and authorized, the authorization server issues an access 1772 token as described in Section 5.1. If the request failed 1773 verification or is invalid, the authorization server returns an error 1774 response as described in Section 5.2. 1776 The authorization server MAY issue a new refresh token, in which case 1777 the client MUST discard the old refresh token and replace it with the 1778 new refresh token. The authorization server MAY revoke the old 1779 refresh token after issuing a new refresh token to the client. If a 1780 new refresh token is issued, its scope MUST be identical to that of 1781 the refresh token included in the request. 1783 7. Accessing Protected Resources 1785 The client accesses protected resources by presenting the access 1786 token to the resource server. The resource server MUST validate the 1787 access token and ensure it has not expired and that its scope covers 1788 the requested resource. The methods used by the resource server to 1789 validate the access token (as well as any error responses) are beyond 1790 the scope of this specification, but generally involve an interaction 1791 or coordination between the resource server and the authorization 1792 server. 1794 The method in which the client utilized the access token to 1795 authenticate with the resource server depends on the type of access 1796 token issued by the authorization server. Typically, it involves 1797 using the HTTP "Authorization" request header field [RFC2617] with an 1798 authentication scheme defined by the access token type specification. 1800 7.1. Access Token Types 1802 The access token type provides the client with the information 1803 required to successfully utilize the access token to make a protected 1804 resource request (along with type-specific attributes). The client 1805 MUST NOT use an access token if it does not understand or does not 1806 trust the token type. 1808 For example, the "bearer" token type defined in 1809 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1810 token string in the request: 1812 GET /resource/1 HTTP/1.1 1813 Host: example.com 1814 Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw 1816 while the "mac" token type defined in [I-D.ietf-oauth-v2-http-mac] is 1817 utilized by issuing a MAC key together with the access token which is 1818 used to sign certain components of the HTTP requests: 1820 GET /resource/1 HTTP/1.1 1821 Host: example.com 1822 Authorization: MAC id="h480djs93hd8", 1823 nonce="274312:dj83hs9s", 1824 mac="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1826 The above examples are provided for illustration purposes only. 1827 Developers are advised to consult the [I-D.ietf-oauth-v2-bearer] and 1828 [I-D.ietf-oauth-v2-http-mac] specifications before use. 1830 Each access token type definition specifies the additional attributes 1831 (if any) sent to the client together with the "access_token" response 1832 parameter. It also defines the HTTP authentication method used to 1833 include the access token when making a protected resource request. 1835 8. Extensibility 1837 8.1. Defining Access Token Types 1839 Access token types can be defined in one of two ways: registered in 1840 the access token type registry (following the procedures in 1841 Section 11.1), or use a unique absolute URI as its name. 1843 Types utilizing a URI name SHOULD be limited to vendor-specific 1844 implementations that are not commonly applicable, and are specific to 1845 the implementation details of the resource server where they are 1846 used. 1848 All other types MUST be registered. Type names MUST conform to the 1849 type-name ABNF. If the type definition includes a new HTTP 1850 authentication scheme, the type name SHOULD be identical to the HTTP 1851 authentication scheme name (as defined by [RFC2617]). 1853 type-name = 1*name-char 1854 name-char = "-" / "." / "_" / DIGIT / ALPHA 1856 8.2. Defining New Endpoint Parameters 1858 New request or response parameters for use with the authorization 1859 endpoint or the token endpoint are defined and registered in the 1860 parameters registry following the procedure in Section 11.2. 1862 Parameter names MUST conform to the param-name ABNF and parameter 1863 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1864 to the syntax of an existing parameter). 1866 param-name = 1*name-char 1867 name-char = "-" / "." / "_" / DIGIT / ALPHA 1869 Unregistered vendor-specific parameter extensions that are not 1870 commonly applicable, and are specific to the implementation details 1871 of the authorization server where they are used SHOULD utilize a 1872 vendor-specific prefix that is not likely to conflict with other 1873 registered values (e.g. begin with 'companyname_'). 1875 8.3. Defining New Authorization Grant Types 1877 New authorization grant types can be defined by assigning them a 1878 unique absolute URI for use with the "grant_type" parameter. If the 1879 extension grant type requires additional token endpoint parameters, 1880 they MUST be registered in the OAuth parameters registry as described 1881 by Section 11.2. 1883 8.4. Defining New Authorization Endpoint Response Types 1885 [[ Pending consensus ]] 1887 New response types for use with the authorization endpoint are 1888 defined and registered in the authorization endpoint response type 1889 registry following the procedure in Section 11.3. Response type 1890 names MUST conform to the response-type ABNF. 1892 response-type = response-name *( "+" response-name ) 1893 response-name = 1*response-char 1894 response-char = "_" / DIGIT / ALPHA 1896 The "+" character is reserved for defining composite response types 1897 made up of two or more existing registered response types. Only one 1898 response type of each combination may be registered and used for 1899 making requests. Composite response types are treated and compared 1900 in the same as manner as non-composite response types. The "+" 1901 notation is meant only to improve human readability and is not used 1902 for machine parsing. 1904 For example, an extension can define and register the "token+code" 1905 response type. However, once registered, the same combination cannot 1906 be registered as "code+token", or used to make an authorization 1907 request. 1909 8.5. Defining Additional Error Codes 1911 In cases where protocol extensions (i.e. access token types, 1912 extension parameters, or extension grant types) require additional 1913 error codes to be used with the authorization code grant error 1914 response (Section 4.1.2.1), the implicit grant error response 1915 (Section 4.2.2.1), or the token error response (Section 5.2), such 1916 error codes MAY be defined. 1918 Extension error codes MUST be registered (following the procedures in 1919 Section 11.4) if the extension they are used in conjunction with is a 1920 registered access token type, a registered endpoint parameter, or an 1921 extension grant type. Error codes used with unregistered extensions 1922 MAY be registered. 1924 Error codes MUST conform to the error-code ABNF, and SHOULD be 1925 prefixed by an identifying name when possible. For example, an error 1926 identifying an invalid value set to the extension parameter "example" 1927 should be named "example_invalid". 1929 error-code = ALPHA *error-char 1930 error-char = "-" / "." / "_" / DIGIT / ALPHA 1932 9. Native Applications 1934 Native applications are clients installed and executed on the 1935 resource owner's device (i.e. desktop application, native mobile 1936 application). Native applications may require special consideration 1937 related to security, platform capabilities, and overall end-user 1938 experience. 1940 The authorization endpoint requires interaction between the client 1941 and the resource owner's user-agent. Native applications can invoke 1942 an external user-agent or embed a user-agent within the application. 1943 For example: 1945 o External user-agent - the native application can capture the 1946 response from the authorization server using a redirection URI 1947 with an scheme registered with the operating system to invoke the 1948 client as the handler, manual copy-and-paste of the credentials, 1949 running a local web server, installing a user-agent extension, or 1950 by providing a redirection URI identifying a server-hosted 1951 resource under the client's control, which in turn makes the 1952 response available to the native application. 1953 o Embedded user-agent - the native application obtains the response 1954 by directly communicating with the embedded user-agent by 1955 monitoring state changes emitted during the resource load, or 1956 accessing the user-agent's cookies storage. 1958 When choosing between an external or embedded user-agent, developers 1959 should consider: 1961 o External user-agents may improve completion rate as the resource 1962 owner may already have an active session with the authorization 1963 server removing the need to re-authenticate. It provides a 1964 familiar end-user experience and functionality. The resource 1965 owner may also rely on user-agent features or extensions to assist 1966 with authentication (e.g. password manager, 2-factor device 1967 reader). 1968 o Embedded user-agents may offer an improved usability, as they 1969 remove the need to switch context and open new windows. 1970 o Embedded user-agents pose a security challenge because resource 1971 owners are authenticating in an unidentified window without access 1972 to the visual protections found in most external user-agents. 1973 Embedded user-agents educate end-user to trust unidentified 1974 requests for authentication (making phishing attacks easier to 1975 execute). 1977 When choosing between the implicit grant type and the authorization 1978 code grant type, the following should be considered: 1980 o Native applications that use the authorization code grant type 1981 SHOULD do so without using client credentials, due to the native 1982 application's inability to keep credentials confidential. 1983 o When using the implicit grant type flow a refresh token is not 1984 returned. 1986 10. Security Considerations 1988 As a flexible and extensible framework, OAuth's security 1989 considerations depend on many factors. The following sections 1990 provide implementers with security guidelines focused on three common 1991 client types: 1993 Web Application 1994 A web application is a client running on a web server. Resource 1995 owners access the client via an HTML user interface rendered in a 1996 user-agent on the resource-owner's device. The client credentials 1997 as well as any access token issued to the client are stored on the 1998 web server and are not exposed to or accessible by the resource 1999 owner. 2000 User-Agent-based Application 2001 A user-agent-based application is a client in which the client 2002 code is downloaded from a web server and executes within a user- 2003 agent on the resource owner's device. Protocol data and 2004 credentials are easily accessible (and often visible) to the 2005 resource owner. Since such applications reside within the user- 2006 agent, they can make seamless use of the user-agent capabilities 2007 when requesting authorization. 2008 Native Application 2009 A native application is a client installed and executed on the 2010 resource owner's device. Protocol data and credentials are 2011 accessible to the resource owner. It is assumed that any client 2012 authentication credentials included in the application can be 2013 extracted, and furthermore that rotation of the client 2014 authentication credentials is impractical. On the other hand, 2015 dynamically issued credentials such access tokens or refresh 2016 tokens, can receive an acceptable level of protection. At a 2017 minimum, these credentials are protected from hostile servers 2018 which the application may interact with. On some platform these 2019 credentials might be protected from other applications residing on 2020 the same device. 2022 A comprehensive OAuth security model and analysis, as well as 2023 background for the protocol design is provided by 2024 [I-D.lodderstedt-oauth-security]. 2026 10.1. Client Authentication 2028 The authorization server establishes client credentials with web 2029 application clients for the purpose of client authentication. The 2030 authorization server is encouraged to consider stronger client 2031 authentication means than a client password. Web application clients 2032 MUST ensure confidentiality of client passwords and other client 2033 credentials. 2035 The authorization server MUST NOT issue client passwords or other 2036 client credentials to native application or user-agent-based 2037 application clients for the purpose of client authentication. The 2038 authorization server MAY issue a client password or other credentials 2039 for a specific installation of a native application client on a 2040 specific device. 2042 10.2. Client Impersonation 2044 A malicious client can impersonate another client and obtain access 2045 to protected resources, if the impersonated client fails to, or is 2046 unable to, keep is client credentials confidential. 2048 The authorization server MUST authenticate the client whenever 2049 possible. If the authorization server cannot authenticate the client 2050 due to the client nature, the authorization server MUST require the 2051 registration of any redirection URI used for receiving authorization, 2052 and SHOULD utilize other means to protect resource owners from such 2053 malicious clients. For example, engage the resource owner to assist 2054 in identifying the client and its origin. 2056 The authorization server SHOULD enforce explicit resource owner 2057 authentication and provide the resource owner with information about 2058 the client and the requested authorization scope and lifetime. It is 2059 up to the resource owner to review the information in the context of 2060 the current client, and authorize the request. 2062 The authorization server SHOULD NOT process repeated authorization 2063 requests automatically (without active resource owner interaction) 2064 without authenticating the client or relying on other measures to 2065 ensure the repeated request comes from an authentic client and not an 2066 impersonator. 2068 10.3. Access Tokens 2070 Access token (as well as any type-specific attributes) MUST be kept 2071 confidential in transit and storage, and only shared among the 2072 authorization server, the resource servers the access token is valid 2073 for, and the client to whom the access token is issued. 2075 When using the implicit grant type, the access token is transmitted 2076 in the URI fragment, which can expose it to unauthorized parties. 2078 The authorization server MUST ensure that access tokens cannot be 2079 generated, modified, or guessed to produce valid access tokens. 2081 The client SHOULD request access tokens with the minimal scope and 2082 lifetime necessary. The authorization server SHOULD take the client 2083 identity into account when choosing how to honor the requested scope 2084 and lifetime, and MAY issue an access token with a less rights than 2085 requested. 2087 10.4. Refresh Tokens 2089 Authorization servers MAY issue refresh tokens to web application 2090 clients and native application clients. 2092 Refresh tokens MUST be kept confidential in transit and storage, and 2093 shared only among the authorization server and the client to whom the 2094 refresh tokens were issued. The authorization server MUST maintain 2095 the binding between a refresh token and the client to whom it was 2096 issued. 2098 The authorization server MUST verify the binding between the refresh 2099 token and client identity whenever the client identity can be 2100 authenticated. When client authentication is not possible, the 2101 authorization server SHOULD deploy other means to detect refresh 2102 token abuse [[ add example ]]. 2104 The authorization server MUST ensure that refresh tokens cannot be 2105 generated, modified, or guessed to produce valid refresh tokens. 2107 10.5. Authorization Codes 2109 The transmission of authorization codes SHOULD be made over a secure 2110 channel, and the client SHOULD implement TLS for use with its 2111 redirection URI if the URI identifies a network resource. Effort 2112 should be made to keep authorization codes confidential. Since 2113 authorization codes are transmitted via user-agent redirections, they 2114 could potentially be disclosed through user-agent history and HTTP 2115 referrer headers. 2117 Authorization codes operate as plaintext bearer credentials, used to 2118 verify that the resource owner who granted authorization at the 2119 authorization server, is the same resource owner returning to the 2120 client to complete the process. Therefore, if the client relies on 2121 the authorization code for its own resource owner authentication, the 2122 client redirection endpoint MUST require TLS. 2124 Authorization codes MUST be short lived and single use. If the 2125 authorization server observes multiple attempts to exchange an 2126 authorization code for an access token, the authorization server 2127 SHOULD attempt to revoke all access tokens already granted based on 2128 the compromised authorization code. 2130 If the client can be authenticated, the authorization servers MUST 2131 authenticate the client and ensure that the authorization code was 2132 issued to the same client. 2134 10.6. Authorization Code Leakage 2136 Session fixation attacks leverage the authorization code grant type, 2137 by tricking a resource owner to authorize access to a legitimate 2138 client, but using a client account under the control of the attacker. 2139 The only difference between a valid request and the attack request is 2140 in how the victim reached the authorization server to grant access. 2142 Once at the authorization server, the victim is prompted with a 2143 normal, valid request on behalf of a legitimate and familiar client. 2144 The attacker then uses the victim's authorization to gain access to 2145 the information authorized by the victim (via the client). 2147 In order to prevent such an attack, authorization servers MUST ensure 2148 that the redirection URI used to obtain the authorization code, is 2149 the same as the redirection URI provided when exchanging the 2150 authorization code for an access token. The authorization server 2151 SHOULD require the client to register their redirection URI and if 2152 provided, MUST validate the redirection URI received in the 2153 authorization request against the registered value. 2155 10.7. Resource Owner Password Credentials 2157 The resource owner password credentials grant type is often used for 2158 legacy or migration reasons. It reduces the overall risk of storing 2159 username and password by the client, but does not eliminate the need 2160 to expose highly privileged credentials to the client. 2162 This grant type carries a higher risk than other grant types because 2163 it maintains the password anti-pattern this protocol seeks to avoid. 2164 The client could abuse the password or the password could 2165 unintentionally be disclosed to an attacker (e.g. via log files or 2166 other records kept by the client). 2168 Additionally, because the resource owner does not have control over 2169 the authorization process (the resource owner involvement ends when 2170 it hands over its credentials to the client), the client can obtain 2171 access tokens with a broader scope and longer lifetime than desired 2172 by the resource owner. The authorization server SHOULD restrict the 2173 scope and lifetime of access tokens issued via this grant type. 2175 The authorization server and client SHOULD minimize use of this grant 2176 type and utilize other grant types whenever possible. 2178 10.8. Request Confidentiality 2180 Access tokens, refresh tokens, resource owner passwords, and client 2181 credentials MUST NOT be transmitted in the clear. Authorization 2182 codes SHOULD NOT be transmitted in the clear. 2184 10.9. Endpoints Authenticity 2186 In order to prevent man-in-the-middle and phishing attacks, the 2187 authorization server MUST implement and require TLS with server 2188 authentication as defined by [RFC2818] for any request sent to the 2189 authorization and token endpoints. The client MUST validate the 2190 authorization server's TLS certificate in accordance with its 2191 requirements for server identity authentication. 2193 10.10. Credentials Guessing Attacks 2195 The authorization server MUST prevent attackers from guessing access 2196 tokens, authorization codes, refresh tokens, resource owner 2197 passwords, and client credentials. 2199 When generating tokens and other credentials not intended for 2200 handling by end-users, the authorization server MUST use a reasonable 2201 level of entropy in order to mitigate the risk of guessing attacks. 2202 The authorization server MUST utilize other means to protect 2203 credentials intended for end-user usage. 2205 10.11. Phishing Attacks 2207 Wide deployment of this and similar protocols may cause end-users to 2208 become inured to the practice of being redirected to websites where 2209 they are asked to enter their passwords. If end-users are not 2210 careful to verify the authenticity of these websites before entering 2211 their credentials, it will be possible for attackers to exploit this 2212 practice to steal resource owners' passwords. 2214 Service providers should attempt to educate end-users about the risks 2215 phishing attacks pose, and should provide mechanisms that make it 2216 easy for end-users to confirm the authenticity of their sites. 2217 Client developers should consider the security implications of how 2218 they interact with the user-agent (e.g., external, embedded), and the 2219 ability of the end-user to verify the authenticity of the 2220 authorization server. 2222 To reduce the risk of phishing attacks, the authorization servers 2223 MUST utilize TLS on every endpoint used for end-user interaction. 2225 10.12. Cross-Site Request Forgery 2227 Cross-site request forgery (CSRF) is a web-based attack whereby HTTP 2228 requests are transmitted from the user-agent of an end-user the 2229 server trusts or has authenticated. CSRF attacks on the 2230 authorization endpoint can allow an attacker to obtain authorization 2231 without the consent of the resource owner. 2233 The "state" request parameter SHOULD be used to mitigate against CSRF 2234 attacks, particularly for login CSRF attacks. CSRF attacks against 2235 the client's redirection URI allow an attacker to inject their own 2236 authorization code or access token, which can result in the client 2237 using an access token associated with the attacker's account rather 2238 than the victim's. Depending on the nature of the client and the 2239 protected resources, this can have undesirable and damaging effects. 2241 It is strongly RECOMMENDED that the client includes the "state" 2242 request parameter with authorization requests to the authorization 2243 server. The "state" request parameter MUST contain a non-guessable 2244 value, and the client MUST keep it in a location accessible only by 2245 the client or the user-agent (i.e., protected by same-origin policy). 2247 For example, using a DOM variable (protected by JavaScript or other 2248 DOM-binding language's enforcement of SOP [[ add reference ]]), HTTP 2249 cookie, or HTML5 client-side storage. The authorization server 2250 includes the value of the "state" parameter when redirecting the 2251 user-agent back to the client which MUST then ensure the received 2252 value matches the stored value. 2254 10.13. Clickjacking 2256 [[ Rework to use specification terminology ]] 2258 Clickjacking is the process of tricking end-users into revealing 2259 confidential information or taking control of their device while 2260 clicking on seemingly innocuous web pages. In more detail, a 2261 malicious site loads the target site in a transparent iframe overlaid 2262 on top of a set of dummy buttons which are carefully constructed to 2263 be placed directly under important buttons on the target site. When 2264 a user clicks a visible button, they are actually clicking a button 2265 (such as an "Authorize" button) on the hidden page. 2267 To prevent clickjacking (and phishing attacks), native applications 2268 SHOULD use external browsers instead of embedding browsers in an 2269 iframe when requesting end-user authorization. For newer browsers, 2270 avoidance of iframes can be enforced by the authorization server 2271 using the "x-frame-options" header [[ Add reference ]]. This header 2272 can have two values, "deny" and "sameorigin", which will block any 2273 framing or framing by sites with a different origin, respectively. 2274 For older browsers, javascript framebusting techniques can be used 2275 but may not be effective in all browsers. 2277 11. IANA Considerations 2279 11.1. The OAuth Access Token Type Registry 2281 This specification establishes the OAuth access token type registry. 2283 Access token types are registered on the advice of one or more 2284 Designated Experts (appointed by the IESG or their delegate), with a 2285 Specification Required (using terminology from [RFC5226]). However, 2286 to allow for the allocation of values prior to publication, the 2287 Designated Expert(s) may approve registration once they are satisfied 2288 that such a specification will be published. 2290 Registration requests should be sent to the [TBD]@ietf.org mailing 2291 list for review and comment, with an appropriate subject (e.g., 2292 "Request for access toke type: example"). [[ Note to RFC-EDITOR: The 2293 name of the mailing list should be determined in consultation with 2294 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2296 Within at most 14 days of the request, the Designated Expert(s) will 2297 either approve or deny the registration request, communicating this 2298 decision to the review list and IANA. Denials should include an 2299 explanation and, if applicable, suggestions as to how to make the 2300 request successful. 2302 Decisions (or lack thereof) made by the Designated Expert can be 2303 first appealed to Application Area Directors (contactable using 2304 app-ads@tools.ietf.org email address or directly by looking up their 2305 email addresses on http://www.iesg.org/ website) and, if the 2306 appellant is not satisfied with the response, to the full IESG (using 2307 the iesg@iesg.org mailing list). 2309 IANA should only accept registry updates from the Designated 2310 Expert(s), and should direct all requests for registration to the 2311 review mailing list. 2313 11.1.1. Registration Template 2315 Type name: 2316 The name requested (e.g., "example"). 2317 Additional Token Endpoint Response Parameters: 2318 Additional response parameters returned together with the 2319 "access_token" parameter. New parameters MUST be separately 2320 registered in the OAuth parameters registry as described by 2321 Section 11.2. 2322 HTTP Authentication Scheme(s): 2323 The HTTP authentication scheme name(s), if any, used to 2324 authenticate protected resources requests using access token of 2325 this type. 2326 Change controller: 2327 For standards-track RFCs, state "IETF". For others, give the name 2328 of the responsible party. Other details (e.g., postal address, 2329 e-mail address, home page URI) may also be included. 2330 Specification document(s): 2331 Reference to document that specifies the parameter, preferably 2332 including a URI that can be used to retrieve a copy of the 2333 document. An indication of the relevant sections may also be 2334 included, but is not required. 2336 11.2. The OAuth Parameters Registry 2338 This specification establishes the OAuth parameters registry. 2340 Additional parameters for inclusion in the authorization endpoint 2341 request, the authorization endpoint response, the token endpoint 2342 request, or the token endpoint response, are registered on the advice 2343 of one or more Designated Experts (appointed by the IESG or their 2344 delegate), with a Specification Required (using terminology from 2345 [RFC5226]). However, to allow for the allocation of values prior to 2346 publication, the Designated Expert(s) may approve registration once 2347 they are satisfied that such a specification will be published. 2349 Registration requests should be sent to the [TBD]@ietf.org mailing 2350 list for review and comment, with an appropriate subject (e.g., 2351 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 2352 the mailing list should be determined in consultation with the IESG 2353 and IANA. Suggested name: oauth-ext-review. ]] 2355 Within at most 14 days of the request, the Designated Expert(s) will 2356 either approve or deny the registration request, communicating this 2357 decision to the review list and IANA. Denials should include an 2358 explanation and, if applicable, suggestions as to how to make the 2359 request successful. 2361 Decisions (or lack thereof) made by the Designated Expert can be 2362 first appealed to Application Area Directors (contactable using 2363 app-ads@tools.ietf.org email address or directly by looking up their 2364 email addresses on http://www.iesg.org/ website) and, if the 2365 appellant is not satisfied with the response, to the full IESG (using 2366 the iesg@iesg.org mailing list). 2368 IANA should only accept registry updates from the Designated 2369 Expert(s), and should direct all requests for registration to the 2370 review mailing list. 2372 11.2.1. Registration Template 2374 Parameter name: 2375 The name requested (e.g., "example"). 2376 Parameter usage location: 2377 The location(s) where parameter can be used. The possible 2378 locations are: authorization request, authorization response, 2379 token request, or token response. 2380 Change controller: 2381 For standards-track RFCs, state "IETF". For others, give the name 2382 of the responsible party. Other details (e.g., postal address, 2383 e-mail address, home page URI) may also be included. 2384 Specification document(s): 2385 Reference to document that specifies the parameter, preferably 2386 including a URI that can be used to retrieve a copy of the 2387 document. An indication of the relevant sections may also be 2388 included, but is not required. 2390 11.2.2. Initial Registry Contents 2392 The OAuth Parameters Registry's initial contents are: 2394 o Parameter name: client_id 2395 o Parameter usage location: authorization request, token request 2396 o Change controller: IETF 2397 o Specification document(s): [[ this document ]] 2399 o Parameter name: client_secret 2400 o Parameter usage location: token request 2401 o Change controller: IETF 2402 o Specification document(s): [[ this document ]] 2404 o Parameter name: response_type 2405 o Parameter usage location: authorization request 2406 o Change controller: IETF 2407 o Specification document(s): [[ this document ]] 2409 o Parameter name: redirect_uri 2410 o Parameter usage location: authorization request, token request 2411 o Change controller: IETF 2412 o Specification document(s): [[ this document ]] 2414 o Parameter name: scope 2415 o Parameter usage location: authorization request, authorization 2416 response, token request, token response 2417 o Change controller: IETF 2418 o Specification document(s): [[ this document ]] 2420 o Parameter name: state 2421 o Parameter usage location: authorization request, authorization 2422 response 2423 o Change controller: IETF 2424 o Specification document(s): [[ this document ]] 2426 o Parameter name: code 2427 o Parameter usage location: authorization response, token request 2428 o Change controller: IETF 2429 o Specification document(s): [[ this document ]] 2431 o Parameter name: error_description 2432 o Parameter usage location: authorization response, token response 2433 o Change controller: IETF 2434 o Specification document(s): [[ this document ]] 2436 o Parameter name: error_uri 2437 o Parameter usage location: authorization response, token response 2438 o Change controller: IETF 2439 o Specification document(s): [[ this document ]] 2440 o Parameter name: grant_type 2441 o Parameter usage location: token request 2442 o Change controller: IETF 2443 o Specification document(s): [[ this document ]] 2445 o Parameter name: access_token 2446 o Parameter usage location: authorization response, token response 2447 o Change controller: IETF 2448 o Specification document(s): [[ this document ]] 2450 o Parameter name: token_type 2451 o Parameter usage location: authorization response, token response 2452 o Change controller: IETF 2453 o Specification document(s): [[ this document ]] 2455 o Parameter name: expires_in 2456 o Parameter usage location: authorization response, token response 2457 o Change controller: IETF 2458 o Specification document(s): [[ this document ]] 2460 o Parameter name: username 2461 o Parameter usage location: token request 2462 o Change controller: IETF 2463 o Specification document(s): [[ this document ]] 2465 o Parameter name: password 2466 o Parameter usage location: token request 2467 o Change controller: IETF 2468 o Specification document(s): [[ this document ]] 2470 o Parameter name: refresh_token 2471 o Parameter usage location: token request, token response 2472 o Change controller: IETF 2473 o Specification document(s): [[ this document ]] 2475 11.3. The OAuth Authorization Endpoint Response Type Registry 2477 This specification establishes the OAuth authorization endpoint 2478 response type registry. 2480 Additional response type for use with the authorization endpoint are 2481 registered on the advice of one or more Designated Experts (appointed 2482 by the IESG or their delegate), with a Specification Required (using 2483 terminology from [RFC5226]). However, to allow for the allocation of 2484 values prior to publication, the Designated Expert(s) may approve 2485 registration once they are satisfied that such a specification will 2486 be published. 2488 Registration requests should be sent to the [TBD]@ietf.org mailing 2489 list for review and comment, with an appropriate subject (e.g., 2490 "Request for response type: example"). [[ Note to RFC-EDITOR: The 2491 name of the mailing list should be determined in consultation with 2492 the IESG and IANA. Suggested name: oauth-ext-review. ]] 2494 Within at most 14 days of the request, the Designated Expert(s) will 2495 either approve or deny the registration request, communicating this 2496 decision to the review list and IANA. Denials should include an 2497 explanation and, if applicable, suggestions as to how to make the 2498 request successful. 2500 Decisions (or lack thereof) made by the Designated Expert can be 2501 first appealed to Application Area Directors (contactable using 2502 app-ads@tools.ietf.org email address or directly by looking up their 2503 email addresses on http://www.iesg.org/ website) and, if the 2504 appellant is not satisfied with the response, to the full IESG (using 2505 the iesg@iesg.org mailing list). 2507 IANA should only accept registry updates from the Designated 2508 Expert(s), and should direct all requests for registration to the 2509 review mailing list. 2511 11.3.1. Registration Template 2513 Response type name: 2514 The name requested (e.g., "example"). 2515 Change controller: 2516 For standards-track RFCs, state "IETF". For others, give the name 2517 of the responsible party. Other details (e.g., postal address, 2518 e-mail address, home page URI) may also be included. 2519 Specification document(s): 2520 Reference to document that specifies the type, preferably 2521 including a URI that can be used to retrieve a copy of the 2522 document. An indication of the relevant sections may also be 2523 included, but is not required. 2525 11.3.2. Initial Registry Contents 2527 The OAuth Authorization Endpoint Response Type Registry's initial 2528 contents are: 2530 o Response type name: code 2531 o Change controller: IETF 2532 o Specification document(s): [[ this document ]] 2533 o Response type name: token 2534 o Change controller: IETF 2535 o Specification document(s): [[ this document ]] 2537 11.4. The OAuth Extensions Error Registry 2539 This specification establishes the OAuth extensions error registry. 2541 Additional error codes used together with other protocol extensions 2542 (i.e. extension grant types, access token types, or extension 2543 parameters) are registered on the advice of one or more Designated 2544 Experts (appointed by the IESG or their delegate), with a 2545 Specification Required (using terminology from [RFC5226]). However, 2546 to allow for the allocation of values prior to publication, the 2547 Designated Expert(s) may approve registration once they are satisfied 2548 that such a specification will be published. 2550 Registration requests should be sent to the [TBD]@ietf.org mailing 2551 list for review and comment, with an appropriate subject (e.g., 2552 "Request for error code: example"). [[ Note to RFC-EDITOR: The name 2553 of the mailing list should be determined in consultation with the 2554 IESG and IANA. Suggested name: oauth-ext-review. ]] 2556 Within at most 14 days of the request, the Designated Expert(s) will 2557 either approve or deny the registration request, communicating this 2558 decision to the review list and IANA. Denials should include an 2559 explanation and, if applicable, suggestions as to how to make the 2560 request successful. 2562 Decisions (or lack thereof) made by the Designated Expert can be 2563 first appealed to Application Area Directors (contactable using 2564 app-ads@tools.ietf.org email address or directly by looking up their 2565 email addresses on http://www.iesg.org/ website) and, if the 2566 appellant is not satisfied with the response, to the full IESG (using 2567 the iesg@iesg.org mailing list). 2569 IANA should only accept registry updates from the Designated 2570 Expert(s), and should direct all requests for registration to the 2571 review mailing list. 2573 11.4.1. Registration Template 2575 Error name: 2576 The name requested (e.g., "example"). 2578 Error usage location: 2579 The location(s) where the error can be used. The possible 2580 locations are: authorization code grant error response 2581 (Section 4.1.2.1), implicit grant error response 2582 (Section 4.2.2.1), or token error response (Section 5.2). 2583 Related protocol extension: 2584 The name of the extension grant type, access token type, or 2585 extension parameter, the error code is used in conjunction with. 2586 Change controller: 2587 For standards-track RFCs, state "IETF". For others, give the name 2588 of the responsible party. Other details (e.g., postal address, 2589 e-mail address, home page URI) may also be included. 2590 Specification document(s): 2591 Reference to document that specifies the error code, preferably 2592 including a URI that can be used to retrieve a copy of the 2593 document. An indication of the relevant sections may also be 2594 included, but is not required. 2596 12. Acknowledgements 2598 The initial OAuth 2.0 protocol specification was edited by David 2599 Recordon, based on two previous publications: the OAuth 1.0 community 2600 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 2601 Authorization Profiles) [I-D.draft-hardt-oauth-01]. The Security 2602 Considerations section was drafted by Torsten Lodderstedt, Mark 2603 McGloin, Phil Hunt, and Anthony Nadalin. 2605 The OAuth 1.0 community specification was edited by Eran Hammer-Lahav 2606 and authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 2607 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 2608 Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, 2609 Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran 2610 Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy 2611 Smith. 2613 The OAuth WRAP specification was edited by Dick Hardt and authored by 2614 Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. 2616 This specification is the work of the OAuth Working Group which 2617 includes dozens of active and dedicated participants. In particular, 2618 the following individuals contributed ideas, feedback, and wording 2619 which shaped and formed the final specification: 2621 Michael Adams, Andrew Arnott, Dirk Balfanz, Scott Cantor, Blaine 2622 Cook, Brian Campbell, Brian Eaton, Leah Culver, Bill de hOra, Brian 2623 Eaton, Brian Ellin, Igor Faynberg, George Fletcher, Tim Freeman, Evan 2624 Gilbert, Yaron Goland, Brent Goldman, Kristoffer Gronowski, Justin 2625 Hart, Dick Hardt, Craig Heath, Phil Hunt, Michael B. Jones, John 2626 Kemp, Mark Kent, Raffi Krikorian, Chasen Le Hara, Rasmus Lerdorf, 2627 Torsten Lodderstedt, Hui-Lan Lu, Paul Madsen, Alastair Mair, Eve 2628 Maler, James Manger, Mark McGloin, Laurence Miao, Chuck Mortimore, 2629 Anthony Nadalin, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob 2630 Sayre, Marius Scurtescu, Naitik Shah, Luke Shepard, Vlad Skvortsov, 2631 Justin Smith, Jeremy Suriel, Christian Stuebner, Paul Tarjan, Allen 2632 Tom, Franklin Tse, Nick Walker, Shane Weeden, and Skylar Woodward. 2634 Appendix A. Editor's Notes 2636 While many people contributed to this specification throughout its 2637 long journey, the editor would like to acknowledge and thank a few 2638 individuals for their outstanding and invaluable efforts leading up 2639 to the publication of this specification. It is these individuals 2640 without whom this work would not have existed or reached its 2641 successful conclusion. 2643 David Recordon for continuously being one of OAuth's most valuable 2644 assets, bringing pragmatism and urgency to the work, and helping 2645 shape it from its very beginning, as well as being one of the best 2646 collaborators I had the pleasure of working with. 2648 Mark Nottingham for introducing OAuth to the IETF and setting the 2649 community on this course. Lisa Dusseault for her support and 2650 guidance as the Application area director. Blaine Cook, Peter Saint- 2651 Andre, and Hannes Tschofenig for their work as working group chairs. 2653 James Manger for his creative ideas and always insightful feedback. 2654 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 2655 Marius Scurtescu, and Luke Shepard for their continued participation 2656 and valuable feedback. 2658 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 2659 support of this work for over three years. 2661 13. References 2663 13.1. Normative References 2665 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2666 Requirement Levels", BCP 14, RFC 2119, March 1997. 2668 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2669 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2670 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2672 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2673 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2674 Authentication: Basic and Digest Access Authentication", 2675 RFC 2617, June 1999. 2677 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 2679 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2680 Resource Identifier (URI): Generic Syntax", STD 66, 2681 RFC 3986, January 2005. 2683 [RFC4627] Crockford, D., "The application/json Media Type for 2684 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2686 [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", 2687 RFC 4949, August 2007. 2689 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2690 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2691 May 2008. 2693 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2694 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2696 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2697 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2699 [W3C.REC-html401-19991224] 2700 Jacobs, I., Hors, A., and D. Raggett, "HTML 4.01 2701 Specification", World Wide Web Consortium 2702 Recommendation REC-html401-19991224, December 1999, 2703 . 2705 13.2. Informative References 2707 [I-D.draft-hardt-oauth-01] 2708 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2709 Web Resource Authorization Profiles", January 2010. 2711 [I-D.ietf-oauth-saml2-bearer] 2712 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 2713 Grant Type Profile for OAuth 2.0", 2714 draft-ietf-oauth-saml2-bearer-03 (work in progress), 2715 February 2011. 2717 [I-D.ietf-oauth-v2-bearer] 2718 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2719 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-04 2720 (work in progress), March 2011. 2722 [I-D.ietf-oauth-v2-http-mac] 2723 Hammer-Lahav, E., Barth, A., and B. Adida, "HTTP 2724 Authentication: MAC Access Authentication", 2725 draft-ietf-oauth-v2-http-mac-00 (work in progress), 2726 May 2011. 2728 [I-D.lodderstedt-oauth-security] 2729 Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 2730 Threat Model and Security Considerations", 2731 draft-lodderstedt-oauth-security-01 (work in progress), 2732 March 2011. 2734 [OASIS.saml-core-2.0-os] 2735 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2736 "Assertions and Protocol for the OASIS Security Assertion 2737 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2738 2.0-os, March 2005. 2740 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2741 April 2010. 2743 Authors' Addresses 2745 Eran Hammer-Lahav (editor) 2746 Yahoo! 2748 Email: eran@hueniverse.com 2749 URI: http://hueniverse.com 2751 David Recordon 2752 Facebook 2754 Email: dr@fb.com 2755 URI: http://www.davidrecordon.com/ 2757 Dick Hardt 2758 Microsoft 2760 Email: dick.hardt@gmail.com 2761 URI: http://dickhardt.org/