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