idnits 2.17.1 draft-ietf-oauth-v2-15.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 (April 6, 2011) is 4763 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 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) == Outdated reference: A later version (-05) exists of draft-hammer-oauth-v2-mac-token-02 == 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-02 -- Obsolete informational reference (is this intentional?): RFC 5849 (Obsoleted by RFC 6749) Summary: 5 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: October 8, 2011 D. Hardt 7 Microsoft 8 April 6, 2011 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-15 13 Abstract 15 The OAuth 2.0 authorization protocol enables granting third-party 16 applications limited access to HTTP service on behalf of an end-user 17 by orchestrating an approval interaction between the end-user and the 18 HTTP service. 20 Status of this Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on October 8, 2011. 37 Copyright Notice 39 Copyright (c) 2011 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 4 57 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . . 5 58 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 6 59 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 8 60 1.6. Document Structure . . . . . . . . . . . . . . . . . . . . 10 61 1.7. Notational Conventions . . . . . . . . . . . . . . . . . . 10 62 2. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 10 63 2.1. Authorization Endpoint . . . . . . . . . . . . . . . . . . 11 64 2.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . 12 65 3. Client Authentication . . . . . . . . . . . . . . . . . . . . 13 66 3.1. Client Password Authentication . . . . . . . . . . . . . . 14 67 3.2. Other Client Authentication Methods . . . . . . . . . . . 14 68 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 15 69 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . . 15 70 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . . 21 71 4.3. Resource Owner Password Credentials . . . . . . . . . . . 27 72 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . . 29 73 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . . 31 74 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 32 75 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 32 76 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . . 33 77 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 35 78 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 36 79 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . . 36 80 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 37 81 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 37 82 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . . 37 83 8.3. Defining New Authorization Grant Types . . . . . . . . . . 38 84 8.4. Defining Additional Error Codes . . . . . . . . . . . . . 38 85 9. Security Considerations . . . . . . . . . . . . . . . . . . . 39 86 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 87 10.1. The OAuth Access Token Type Registry . . . . . . . . . . . 39 88 10.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 40 89 10.3. The OAuth Extensions Error Registry . . . . . . . . . . . 43 90 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 44 91 Appendix A. Editor's Notes . . . . . . . . . . . . . . . . . . . 45 92 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 46 93 12.1. Normative References . . . . . . . . . . . . . . . . . . . 46 94 12.2. Informative References . . . . . . . . . . . . . . . . . . 46 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47 97 1. Introduction 99 In the traditional client-server authentication model, the client 100 accesses a protected resource on the server by authenticating with 101 the server using the resource owner's credentials. In order to 102 provide third-party applications access to protected resources, the 103 resource owner shares its credentials with the third-party. This 104 creates several problems and limitations: 106 o Third-party applications are required to store the resource- 107 owner's credentials for future use, typically a password in clear- 108 text. 109 o Servers are required to support password authentication, despite 110 the security weaknesses created by passwords. 111 o Third-party applications gain overly broad access to the resource- 112 owner's protected resources, leaving resource owners without any 113 ability to restrict duration or access to a limited subset of 114 resources. 115 o Resource owners cannot revoke access to an individual third-party 116 without revoking access to all third-parties, and must do so by 117 changing their password. 119 OAuth addresses these issues by introducing an authorization layer 120 and separating the role of the client from that of the resource 121 owner. In OAuth, the client requests access to resources controlled 122 by the resource owner and hosted by the resource server, and is 123 issued a different set of credentials than those of the resource 124 owner. 126 Instead of using the resource owner's credentials to access protected 127 resources, the client obtains an access token - a string denoting a 128 specific scope, duration, and other access attributes. Access tokens 129 are issued to third-party clients by an authorization server with the 130 approval of the resource owner. The client uses the access token to 131 access the protected resources hosted by the resource server. 133 For example, a web end-user (resource owner) can grant a printing 134 service (client) access to her protected photos stored at a photo 135 sharing service (resource server), without sharing her username and 136 password with the printing service. Instead, she authenticates 137 directly with a server trusted by the photo sharing service 138 (authorization server) which issues the printing service delegation- 139 specific credentials (access token). 141 This specification is designed for use with HTTP [RFC2616]. The use 142 of OAuth with any transport protocol other than HTTP is undefined. 144 1.1. Roles 146 OAuth includes four roles working together to grant and provide 147 access to protected resources - access restricted resources which 148 require authentication to access: 150 resource owner 151 An entity capable of granting access to a protected resource. 152 When the resource owner is a person, it is referred to as an end- 153 user. 154 resource server 155 The server hosting the protected resources, capable of accepting 156 and responding to protected resource requests using access tokens. 157 client 158 An application making protected resource requests on behalf of the 159 resource owner and with its authorization. 160 authorization server 161 The server issuing access tokens to the client after successfully 162 authenticating the resource owner and obtaining authorization. 164 The interaction between the authorization server and resource server 165 is beyond the scope of this specification. The authorization server 166 may be the same server as the resource server or a separate entity. 167 A single authorization server may issue access tokens accepted by 168 multiple resource servers. 170 1.2. Protocol Flow 172 When interacting with the authorization server, the client identifies 173 itself using a set of client credentials which include a client 174 identifier and other authentication attributes. The means through 175 which the client obtains its credentials are beyond the scope of this 176 specification, but typically involve registration with the 177 authorization server. 179 +--------+ +---------------+ 180 | |--(A)- Authorization Request ->| Resource | 181 | | | Owner | 182 | |<-(B)-- Authorization Grant ---| | 183 | | +---------------+ 184 | | 185 | | Authorization Grant & +---------------+ 186 | |--(C)--- Client Credentials -->| Authorization | 187 | Client | | Server | 188 | |<-(D)----- Access Token -------| | 189 | | +---------------+ 190 | | 191 | | +---------------+ 192 | |--(E)----- Access Token ------>| Resource | 193 | | | Server | 194 | |<-(F)--- Protected Resource ---| | 195 +--------+ +---------------+ 197 Figure 1: Abstract Protocol Flow 199 The abstract flow illustrated in Figure 1 describes the interaction 200 between the four roles and includes the following steps: 202 (A) The client requests authorization from the resource owner. The 203 authorization request can be made directly to the resource owner 204 (as shown), or preferably indirectly via an intermediary such as 205 an authorization server. 206 (B) The client receives an authorization grant which represents the 207 authorization provided by the resource owner. The authorization 208 grant type depends on the method used by the client and 209 supported by the authorization server to obtain it. 210 (C) The client requests an access token by authenticating with the 211 authorization server using its client credentials (prearranged 212 between the client and authorization server) and presenting the 213 authorization grant. 214 (D) The authorization server validates the client credentials and 215 the authorization grant, and if valid issues an access token. 216 (E) The client requests the protected resource from the resource 217 server and authenticates by presenting the access token. 218 (F) The resource server validates the access token, and if valid, 219 serves the request. 221 1.3. Access Token 223 An access token is a string representing an authorization issued to 224 the client. The string is usually opaque to the client. Tokens 225 represent specific scopes and durations of access, granted by the 226 resource owner, and enforced by the resource server and authorization 227 server. 229 The token may denote an identifier used to retrieve the authorization 230 information, or self-contain the authorization information in a 231 verifiable manner (i.e. a token string consisting of some data and a 232 signature). Additional authentication credentials may be required in 233 order for the client to use a token. 235 The access token provides an abstraction layer, replacing different 236 authorization constructs (e.g. username and password) with a single 237 token understood by the resource server. This abstraction enables 238 issuing access tokens more restrictive than the authorization grant 239 used to obtain them, as well as removing the resource server's need 240 to understand a wide range of authentication methods. 242 Access tokens can have different formats, structures, and methods of 243 utilization (e.g. cryptographic properties) based on the resource 244 server security requirements. Access token attributes and the 245 methods used to access protected resources are beyond the scope of 246 this specification and are defined by companion specifications. 248 1.4. Authorization Grant 250 An authorization grant is a general term used to describe the 251 intermediate credentials representing the resource owner 252 authorization (to access its protected resources), and serves as an 253 abstraction layer. An authorization grant is used by the client to 254 obtain an access token. 256 This specification defines four grant types: authorization code, 257 implicit, resource owner password credentials, and client 258 credentials, as well as an extensibility mechanism for defining 259 additional types. 261 1.4.1. Authorization Code 263 The authorization code is obtained by using an authorization server 264 as an intermediary between the client and resource owner. Instead of 265 requesting authorization directly from the resource owner, the client 266 directs the resource owner to an authorization server (via its user- 267 agent as defined in [RFC2616]), which in turns directs the resource 268 owner back to the client with the authorization code. 270 Before directing the resource owner back to the client with the 271 authorization code, the authorization server authenticates the 272 resource owner and obtains authorization. Because the resource owner 273 only authenticates with the authorization server, the resource 274 owner's credentials are never shared with the client. 276 The authorization code provides a few important security benefits 277 such as the ability to authenticate the client and issuing the access 278 token directly to the client without potentially exposing it to 279 others, including the resource owner. 281 1.4.2. Implicit 283 When an access token is issued to the client directly as the result 284 of the resource owner authorization, without an intermediary 285 authorization grant (such as an authorization code), the grant is 286 considered implicit. 288 When issuing an implicit grant, the authorization server cannot 289 verify the identity of the client, and the access token may be 290 exposed to the resource owner or other applications with access to 291 the resource owner's user-agent. 293 Implicit grants improve the responsiveness and efficiency of some 294 clients (such as a client implemented as an in-browser application) 295 since it reduces the number of round trips required to obtain an 296 access token. 298 1.4.3. Resource Owner Password Credentials 300 The resource owner password credentials (e.g. a username and 301 password) can be used directly as an authorization grant to obtain an 302 access token. The credentials should only be used when there is a 303 high degree of trust between the resource owner and the client (e.g. 304 its computer operating system or a highly privileged application), 305 and when other authorization grant types are not available (such as 306 an authorization code). 308 Even though this grant type requires direct client access to the 309 resource owner credentials, the resource owner credentials are used 310 for a single request and are exchanged for an access token. Unlike 311 the HTTP Basic authentication scheme defined in [RFC2617], this grant 312 type (when combined with a refresh token) eliminates the need for the 313 client to store the resource-owner credentials for future use. 315 1.4.4. Client Credentials 317 The client credentials can be used as an authorization grant when the 318 authorization scope is limited to the protected resources under the 319 control of the client, or to protected resources previously arranged 320 with the authorization server. Client credentials are used as an 321 authorization grant typically when the client is acting on its own 322 behalf (the client is also the resource owner). 324 1.4.5. Extensions 326 Additional grant types may be defined to provide a bridge between 327 OAuth and other protocols. For example, 328 [I-D.ietf-oauth-saml2-bearer] defines a SAML 2.0 329 [OASIS.saml-core-2.0-os] bearer assertion grant type, which can be 330 used to obtain an access token. 332 1.5. Refresh Token 334 A refresh token is optionally issued by the authorization server to 335 the client together with an access token. The client can use the 336 refresh token to request another access token based on the same 337 authorization, without having to involve the resource owner again, or 338 having to retain the original authorization grant used to obtain the 339 initial access token. 341 A refresh token is a string representing the authorization granted to 342 the client by the resource owner. The string is usually opaque to 343 the client. The token may denote an identifier used to retrieve the 344 authorization information, or self-contain the authorization 345 information in a verifiable manner. The refresh token is bound to 346 the client it was issued to, and its usage requires client 347 authentication. 349 The refresh token can be used to obtain a new access token when the 350 current access token expires (access tokens may have a shorter 351 lifetime than authorized by the resource owner), no longer valid, or 352 to obtain additional access tokens with identical or narrower scope. 354 +--------+ Authorization Grant & +---------------+ 355 | |--(A)-------- Client Credentials --------->| | 356 | | | | 357 | |<-(B)----------- Access Token -------------| | 358 | | & Refresh Token | | 359 | | | | 360 | | +----------+ | | 361 | |--(C)---- Access Token ---->| | | | 362 | | | | | | 363 | |<-(D)- Protected Resource --| Resource | | Authorization | 364 | Client | | Server | | Server | 365 | |--(E)---- Access Token ---->| | | | 366 | | | | | | 367 | |<-(F)- Invalid Token Error -| | | | 368 | | +----------+ | | 369 | | | | 370 | | Refresh Token & | | 371 | |--(G)-------- Client Credentials --------->| | 372 | | | | 373 | |<-(H)----------- Access Token -------------| | 374 +--------+ & Optional Refresh Token +---------------+ 376 Figure 2: Refreshing an Expired Access Token 378 The flow illustrated in Figure 2 includes the following steps: 380 (A) The client requests an access token by authenticating with the 381 authorization server using its client credentials, and 382 presenting an authorization grant. 383 (B) The authorization server validates the client credentials and 384 the authorization grant, and if valid issues an access token and 385 a refresh token. 386 (C) The client makes a protected resource requests to the resource 387 server by presenting the access token. 388 (D) The resource server validates the access token, and if valid, 389 serves the request. 390 (E) Steps (C) and (D) repeat until the access token expires. If the 391 client knows the access token expired, it skips to step (G), 392 otherwise it makes another protected resource request. 393 (F) Since the access token is invalid, the resource server returns 394 an invalid token error. 395 (G) The client requests a new access token by authenticating with 396 the authorization server using its client credentials, and 397 presenting the refresh token. 399 (H) The authorization server validates the client credentials and 400 the refresh token, and if valid issues a new access token (and 401 optionally, a new refresh token). 403 1.6. Document Structure 405 This specification is organized into the following sections: 407 o Section 2 - describes the two endpoints used to obtain and utilize 408 the various authorization grant types. 409 o Section 3 - describes client identification and authentication in 410 general, and provides one such method for client authentication 411 using password credentials. 412 o Section 4 - describes the complete flow for each authorization 413 grant type, including requesting authorization, authorization 414 response, and requesting an access token. 415 o Section 5 - describes the common access token response used for 416 all non-implicit authorization grant types. 417 o Section 6 - describes the use of a refresh token to obtain 418 additional access tokens using the same resource owner 419 authorization. 420 o Section 7 - describes how access tokens are used to access 421 protected resources. 422 o Section 8 - describes how to extend certain elements of the 423 protocol. 424 o Section 9 - provides a security analysis of the protocol. 426 1.7. Notational Conventions 428 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 429 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 430 specification are to be interpreted as described in [RFC2119]. 432 This specification uses the Augmented Backus-Naur Form (ABNF) 433 notation of [RFC5234]. 435 Unless otherwise noted, all the protocol parameter names and values 436 are case sensitive. 438 2. Protocol Endpoints 440 The authorization process utilizes two endpoints (HTTP resources): 442 o Authorization endpoint - used to obtain authorization from the 443 resource owner via user-agent redirection. 445 o Token endpoint - used to exchange an authorization grant for an 446 access token, typically with client authentication. 448 Not every authorization grant type utilizes both endpoints. 449 Extension grant types MAY define additional endpoints as needed. 451 2.1. Authorization Endpoint 453 The authorization endpoint is used to interact with the resource 454 owner and obtain authorization which is expressed explicitly as an 455 authorization code (exchanged for an access token), or implicitly by 456 direct issuance of an access token. 458 The authorization server MUST first verify the identity of the 459 resource owner. The way in which the authorization server 460 authenticates the resource owner (e.g. username and password login, 461 session cookies) is beyond the scope of this specification. 463 The means through which the client obtains the location of the 464 authorization endpoint are beyond the scope of this specification but 465 is typically provided in the service documentation. The endpoint URI 466 MAY include a query component as defined by [RFC3986] section 3, 467 which MUST be retained when adding additional query parameters. 469 Since requests to the authorization endpoint result in user 470 authentication and the transmission of clear-text credentials (in the 471 HTTP response), the authorization server MUST require the use of a 472 transport-layer security mechanism when sending requests to the token 473 endpoints. The authorization server MUST support TLS 1.2 as defined 474 in [RFC5246], and MAY support additional transport-layer mechanisms 475 meeting its security requirements. 477 The authorization server MUST support the use of the HTTP "GET" 478 method [RFC2616] for the authorization endpoint, and MAY support the 479 use of the "POST" method as well. 481 The REQUIRED "response_type" request parameter is used to identify 482 which grant type the client is requesting: authorization code or 483 implicit, described in Section 4.1.1 and Section 4.2.1 respectively. 484 If the request is missing the "response_type" parameter, the 485 authorization server SHOULD return an error response as described in 486 Section 4.1.2.1. 488 Parameters sent without a value MUST be treated as if they were 489 omitted from the request. The authorization server SHOULD ignore 490 unrecognized request parameters. 492 Request and response parameters MUST NOT repeat more than once, 493 unless noted otherwise. 495 2.1.1. Redirection URI 497 The client directs the resource owner's user-agent to the 498 authorization endpoint and includes a redirection URI to which the 499 authorization server will redirect the user-agent back once 500 authorization has been obtained (or denied). The client MAY omit the 501 redirection URI if one has been established between the client and 502 authorization server via other means, such as during the client 503 registration process. 505 The redirection URI MUST be an absolute URI and MAY include a query 506 component, which MUST be retained by the authorization server when 507 adding additional query parameters. 509 The authorization server SHOULD require the client to pre-register 510 their redirection URI or at least certain components such as the 511 scheme, host, port and path. If a redirection URI was registered, 512 the authorization server MUST compare any redirection URI received at 513 the authorization endpoint with the registered URI. 515 The authorization server SHOULD NOT redirect the user-agent to 516 unregistered or untrusted URIs to prevent the endpoint from being 517 used as an open redirector. If no valid redirection URI is 518 available, the authorization server SHOULD inform the resource owner 519 directly of the error. 521 2.2. Token Endpoint 523 The token endpoint is used by the client to obtain an access token by 524 authenticating with the authorization server and presenting its 525 authorization grant or refresh token. The token endpoint is used 526 with every authorization grant except for the implicit grant type 527 (since an access token is issued directly). 529 The means through which the client obtains the location of the token 530 endpoint are beyond the scope of this specification but is typically 531 provided in the service documentation. The endpoint URI MAY include 532 a query component, which MUST be retained when adding additional 533 query parameters. 535 Since requests to the token endpoint result in the transmission of 536 clear-text credentials (in the HTTP request and response), the 537 authorization server MUST require the use of a transport-layer 538 security mechanism when sending requests to the token endpoints. The 539 authorization server MUST support TLS 1.2 as defined in [RFC5246], 540 and MAY support additional transport-layer mechanisms meeting its 541 security requirements. 543 The token endpoint requires client authentication as described in 544 Section 3. The authorization server MAY accept any form of client 545 authentication meeting its security requirements. The client MUST 546 NOT use more than one authentication method in each request. 548 The client MUST use the HTTP "POST" method when making access token 549 requests. 551 Parameters sent without a value MUST be treated as if they were 552 omitted from the request. The authorization server SHOULD ignore 553 unrecognized request parameters. 555 Request and response parameters MUST NOT repeat more than once, 556 unless noted otherwise. 558 3. Client Authentication 560 Client credentials are used to identify and authenticate the client. 561 The client credentials include a client identifier - a unique string 562 issued to the client to identify itself to the authorization server. 563 The client identifier is not a secret, it is exposed to the resource 564 owner, and MUST NOT be used alone for client authentication. Client 565 authentication is accomplished via additional means such as a 566 matching client password. 568 The methods through which the client obtains its client credentials 569 are beyond the scope of this specification. However, the client 570 registration process typically includes gathering relevant 571 information used to inform the resource owner about the client when 572 requesting authorization. 574 Due to the nature of some clients, the authorization server should 575 not make assumptions about the confidentiality of client credentials 576 without establishing trust with the client. The authorization server 577 SHOULD NOT issue client credentials to clients incapable of keeping 578 their credentials confidential (typically determined during the 579 client registration process). 581 In addition, the authorization server MAY allow unauthenticated 582 access token requests when the client identity does not matter (e.g. 583 anonymous client) or when the client identity is established via 584 other means. For readability purposes only, this specification is 585 written under the assumption that the authorization server requires 586 some form of client authentication. However, such language does not 587 affect the authorization server's discretion in allowing 588 unauthenticated client requests. 590 3.1. Client Password Authentication 592 The client password authentication uses a shared symmetric secret to 593 authenticate the client. The client identifier and password are 594 included in the request using the following parameters: 596 client_id 597 REQUIRED. The client identifier. 598 client_secret 599 REQUIRED. The client password. 601 For example (line breaks are for display purposes only): 603 POST /token HTTP/1.1 604 Host: server.example.com 605 Content-Type: application/x-www-form-urlencoded 607 grant_type=authorization_code&client_id=s6BhdRkqt3& 608 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 609 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 611 3.2. Other Client Authentication Methods 613 In cases where client password authentication is not suitable or 614 sufficient, the authorization server MAY support other existing HTTP 615 authentication schemes or define new methods. 617 For example, the authorization server MAY support using the HTTP 618 Basic authentication scheme as defined in [RFC2617] to include the 619 client identifier as the username and client password as the password 620 (line breaks are for display purposes only): 622 POST /token HTTP/1.1 623 Host: server.example.com 624 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 625 Content-Type: application/x-www-form-urlencoded 627 grant_type=authorization_code&code=i1WsRn1uB1& 628 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 630 When using a method other than client password authentication to 631 exchange an authorization code grant type, the authorization server 632 MUST define a method for mapping the client credentials to the client 633 identifier used to obtain the authorization code. 635 4. Obtaining Authorization 637 To request an access token, the client obtains authorization from the 638 resource owner. The authorization is expressed in the form of an 639 authorization grant which the client uses to request the access 640 token. OAuth defines four grant types: authorization code, implicit, 641 resource owner password credentials, and client credentials. It also 642 provides an extension mechanism for defining additional grant types. 644 4.1. Authorization Code 646 The authorization code grant type is suitable for clients capable of 647 maintaining their client credentials confidential (for authenticating 648 with the authorization server) such as a client implemented on a 649 secure server. As a redirection-based flow, the client must be 650 capable of interacting with the resource owner's user-agent 651 (typically a web browser) and capable of receiving incoming requests 652 (via redirection) from the authorization server. 654 +----------+ 655 | resource | 656 | owner | 657 | | 658 +----------+ 659 ^ 660 | 661 (B) 662 +----|-----+ Client Identifier +---------------+ 663 | -+----(A)--- & Redirect URI ------>| | 664 | User- | | Authorization | 665 | Agent -+----(B)-- User authenticates --->| Server | 666 | | | | 667 | -+----(C)-- Authorization Code ---<| | 668 +-|----|---+ +---------------+ 669 | | ^ v 670 (A) (C) | | 671 | | | | 672 ^ v | | 673 +---------+ | | 674 | |>---(D)-- Client Credentials, --------' | 675 | | Authorization Code, | 676 | Client | & Redirect URI | 677 | | | 678 | |<---(E)----- Access Token -------------------' 679 +---------+ (w/ Optional Refresh Token) 681 Figure 3: Authorization Code Flow 683 The flow illustrated in Figure 3 includes the following steps: 685 (A) The client initiates the flow by directing the resource owner's 686 user-agent to the authorization endpoint. The client includes 687 its client identifier, requested scope, local state, and a 688 redirection URI to which the authorization server will send the 689 user-agent back once access is granted (or denied). 690 (B) The authorization server authenticates the resource owner (via 691 the user-agent) and establishes whether the resource owner 692 grants or denies the client's access request. 693 (C) Assuming the resource owner grants access, the authorization 694 server redirects the user-agent back to the client using the 695 redirection URI provided earlier. The redirection URI includes 696 an authorization code and any local state provided by the client 697 earlier. 699 (D) The client requests an access token from the authorization 700 server's token endpoint by authenticating using its client 701 credentials, and includes the authorization code received in the 702 previous step. The client includes the redirection URI used to 703 obtain the authorization code for verification. 704 (E) The authorization server validates the client credentials, the 705 authorization code, and ensures the redirection URI received 706 matches the URI used to redirect the client in step (C). If 707 valid, responds back with an access token. 709 4.1.1. Authorization Request 711 The client constructs the request URI by adding the following 712 parameters to the query component of the authorization endpoint URI 713 using the "application/x-www-form-urlencoded" format as defined by 714 [W3C.REC-html401-19991224]: 716 response_type 717 REQUIRED. Value MUST be set to "code". 718 client_id 719 REQUIRED. The client identifier as described in Section 3. 720 redirect_uri 721 REQUIRED, unless a redirection URI has been established between 722 the client and authorization server via other means. Described 723 in Section 2.1.1. 724 scope 725 OPTIONAL. The scope of the access request expressed as a list 726 of space-delimited, case sensitive strings. The value is 727 defined by the authorization server. If the value contains 728 multiple space-delimited strings, their order does not matter, 729 and each string adds an additional access range to the 730 requested scope. 731 state 732 OPTIONAL. An opaque value used by the client to maintain state 733 between the request and callback. The authorization server 734 includes this value when redirecting the user-agent back to the 735 client. 737 The client directs the resource owner to the constructed URI using an 738 HTTP redirection response, or by other means available to it via the 739 user-agent. 741 For example, the client directs the user-agent to make the following 742 HTTP request using transport-layer security (line breaks are for 743 display purposes only): 745 GET /authorize?response_type=code&client_id=s6BhdRkqt3& 746 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 747 Host: server.example.com 749 The authorization server validates the request to ensure all required 750 parameters are present and valid. If the request is valid, the 751 authorization server authenticates the resource owner and obtains an 752 authorization decision (by asking the resource owner or by 753 establishing approval via other means). 755 When a decision is established, the authorization server directs the 756 user-agent to the provided client redirection URI using an HTTP 757 redirection response, or by other means available to it via the user- 758 agent. 760 4.1.2. Authorization Response 762 If the resource owner grants the access request, the authorization 763 server issues an authorization code and delivers it to the client by 764 adding the following parameters to the query component of the 765 redirection URI using the "application/x-www-form-urlencoded" format: 767 code 768 REQUIRED. The authorization code generated by the 769 authorization server. The authorization code SHOULD expire 770 shortly after it is issued to minimize the risk of leaks. The 771 client MUST NOT reuse the authorization code. If an 772 authorization code is used more than once, the authorization 773 server MAY revoke all tokens previously issued based on that 774 authorization code. The authorization code is bound to the 775 client identifier and redirection URI. 776 state 777 REQUIRED if the "state" parameter was present in the client 778 authorization request. Set to the exact value received from 779 the client. 781 For example, the authorization server redirects the user-agent by 782 sending the following HTTP response: 784 HTTP/1.1 302 Found 785 Location: https://client.example.com/cb?code=i1WsRn1uB1 787 The client SHOULD ignore unrecognized response parameters. The 788 authorization code string size is left undefined by this 789 specification. The client should avoid making assumptions about code 790 value sizes. The authorization server should document the size of 791 any value it issues. 793 4.1.2.1. Error Response 795 If the request fails due to a missing, invalid, or mismatching 796 redirection URI, or if the client identifier provided is invalid, the 797 authorization server SHOULD inform the resource owner of the error, 798 and MUST NOT redirect the user-agent to the invalid redirection URI. 800 If the resource owner denies the access request or if the request 801 fails for reasons other than a missing or invalid redirection URI, 802 the authorization server informs the client by adding the following 803 parameters to the query component of the redirection URI using the 804 "application/x-www-form-urlencoded" format: 806 error 807 REQUIRED. A single error code from the following: 808 invalid_request 809 The request is missing a required parameter, includes an 810 unsupported parameter or parameter value, or is otherwise 811 malformed. 812 unauthorized_client 813 The client is not authorized to request an authorization 814 code using this method. 815 access_denied 816 The resource owner or authorization server denied the 817 request. 818 unsupported_response_type 819 The authorization server does not support obtaining an 820 authorization code using this method. 821 invalid_scope 822 The requested scope is invalid, unknown, or malformed. 823 a 4xx or 5xx HTTP status code (except for 400 and 401) 824 [[ Pending Consensus ]] The authorization server MAY set 825 the "error" parameter value to a numerical HTTP status 826 code from the 4xx or 5xx range, with the exception of the 827 400 (Bad Request) and 401 (Unauthorized) status codes. 828 For example, if the service is temporarily unavailable, 829 the authorization server MAY return an error response 830 with "error" set to "503". 831 error_description 832 OPTIONAL. A human-readable text providing additional 833 information, used to assist in the understanding and resolution 834 of the error occurred. 836 error_uri 837 OPTIONAL. A URI identifying a human-readable web page with 838 information about the error, used to provide the resource owner 839 with additional information about the error. 840 state 841 REQUIRED if a valid "state" parameter was present in the client 842 authorization request. Set to the exact value received from 843 the client. 845 For example, the authorization server redirects the user-agent by 846 sending the following HTTP response: 848 HTTP/1.1 302 Found 849 Location: https://client.example.com/cb?error=access_denied 851 4.1.3. Access Token Request 853 The client makes a request to the token endpoint by adding the 854 following parameter using the "application/x-www-form-urlencoded" 855 format in the HTTP request entity-body: 857 grant_type 858 REQUIRED. Value MUST be set to "authorization_code". 859 code 860 REQUIRED. The authorization code received from the 861 authorization server. 862 redirect_uri 863 REQUIRED. The redirection URI used by the authorization server 864 to return the authorization response in the previous step. 866 The client includes its authentication credentials as described in 867 Section 3 869 For example, the client makes the following HTTP request by including 870 its client credentials via the "client_id" and "client_secret" 871 parameters, and using transport-layer security (line breaks are for 872 display purposes only): 874 POST /token HTTP/1.1 875 Host: server.example.com 876 Content-Type: application/x-www-form-urlencoded 878 grant_type=authorization_code&client_id=s6BhdRkqt3& 879 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 880 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 882 The authorization server MUST: 884 o Validate the client credentials and ensure that the authorization 885 code was issued to that client. 886 o Verify that the authorization code is valid, and that the 887 redirection URI matches the redirection URI used by the 888 authorization server to deliver the authorization code. 890 4.1.4. Access Token Response 892 If the access token request is valid and authorized, the 893 authorization server issues an access token and optional refresh 894 token as described in Section 5.1. If the request client 895 authentication failed or is invalid, the authorization server returns 896 an error response as described in Section 5.2. 898 An example successful response: 900 HTTP/1.1 200 OK 901 Content-Type: application/json 902 Cache-Control: no-store 904 { 905 "access_token":"SlAV32hkKG", 906 "token_type":"example", 907 "expires_in":3600, 908 "refresh_token":"8xLOxBtZp8", 909 "example_parameter":"example_value" 910 } 912 4.2. Implicit Grant 914 The implicit grant type is suitable for clients incapable of 915 maintaining their client credentials confidential (for authenticating 916 with the authorization server) such as client applications residing 917 in a user-agent, typically implemented in a browser using a scripting 918 language such as JavaScript. 920 As a redirection-based flow, the client must be capable of 921 interacting with the resource owner's user-agent (typically a web 922 browser) and capable of receiving incoming requests (via redirection) 923 from the authorization server. 925 Unlike the authorization code grant type in which the client makes 926 separate requests for authorization and access token, the client 927 receives the access token as the result of the authorization request. 929 Using the implicit grant type does not include client authentication 930 since the client is unable to maintain their credential 931 confidentiality (the client resides on the resource owner's computer 932 or device which makes the client credentials accessible and 933 exploitable). Because the access token is encoded into the 934 redirection URI, it may be exposed to the resource owner and other 935 applications residing on its computer or device. 937 +----------+ 938 | Resource | 939 | Owner | 940 | | 941 +----------+ 942 ^ 943 | 944 (B) 945 +----|-----+ Client Identifier +---------------+ 946 | -+----(A)--- & Redirect URI ----->| | 947 | User- | | Authorization | 948 | Agent -|----(B)-- User authenticates -->| Server | 949 | | | | 950 | |<---(C)---- Redirect URI ------<| | 951 | | with Access Token +---------------+ 952 | | in Fragment 953 | | +---------------+ 954 | |----(D)---- Redirect URI ------>| Web Server | 955 | | without Fragment | with Client | 956 | | | Resource | 957 | (F) |<---(E)------- Script ---------<| | 958 | | +---------------+ 959 +-|--------+ 960 | | 961 (A) (G) Access Token 962 | | 963 ^ v 964 +---------+ 965 | | 966 | Client | 967 | | 968 +---------+ 970 Figure 4: Implicit Grant Flow 972 The flow illustrated in Figure 4 includes the following steps: 974 (A) The client initiates the flow by directing the resource owner's 975 user-agent to the authorization endpoint. The client includes 976 its client identifier, requested scope, local state, and a 977 redirection URI to which the authorization server will send the 978 user-agent back once access is granted (or denied). 979 (B) The authorization server authenticates the resource owner (via 980 the user-agent) and establishes whether the resource owner 981 grants or denies the client's access request. 982 (C) Assuming the resource owner grants access, the authorization 983 server redirects the user-agent back to the client using the 984 redirection URI provided earlier. The redirection URI includes 985 the access token in the URI fragment. 986 (D) The user-agent follows the redirection instructions by making a 987 request to the web server (does not include the fragment). The 988 user-agent retains the fragment information locally. 989 (E) The web server returns a web page (typically an HTML document 990 with an embedded script) capable of accessing the full 991 redirection URI including the fragment retained by the user- 992 agent, and extracting the access token (and other parameters) 993 contained in the fragment. 994 (F) The user-agent executes the script provided by the web server 995 locally, which extracts the access token and passes it to the 996 client. 998 4.2.1. Authorization Request 1000 The client constructs the request URI by adding the following 1001 parameters to the query component of the authorization endpoint URI 1002 using the "application/x-www-form-urlencoded" format: 1004 response_type 1005 REQUIRED. Value MUST be set to "token". 1006 client_id 1007 REQUIRED. The client identifier as described in Section 3. 1008 redirect_uri 1009 REQUIRED, unless a redirection URI has been established between 1010 the client and authorization server via other means. Described 1011 in Section 2.1.1. 1012 scope 1013 OPTIONAL. The scope of the access request expressed as a list 1014 of space-delimited, case sensitive strings. The value is 1015 defined by the authorization server. If the value contains 1016 multiple space-delimited strings, their order does not matter, 1017 and each string adds an additional access range to the 1018 requested scope. 1020 state 1021 OPTIONAL. An opaque value used by the client to maintain state 1022 between the request and callback. The authorization server 1023 includes this value when redirecting the user-agent back to the 1024 client. 1026 The client directs the resource owner to the constructed URI using an 1027 HTTP redirection response, or by other means available to it via the 1028 user-agent. 1030 For example, the client directs the user-agent to make the following 1031 HTTP request using transport-layer security (line breaks are for 1032 display purposes only): 1034 GET /authorize?response_type=token&client_id=s6BhdRkqt3& 1035 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 1036 Host: server.example.com 1038 The authorization server validates the request to ensure all required 1039 parameters are present and valid. If the request is valid, the 1040 authorization server authenticates the resource owner and obtains an 1041 authorization decision (by asking the resource owner or by 1042 establishing approval via other means). 1044 When a decision is established, the authorization server directs the 1045 user-agent to the provided client redirection URI using an HTTP 1046 redirection response, or by other means available to it via the user- 1047 agent. 1049 4.2.2. Access Token Response 1051 If the resource owner grants the access request, the authorization 1052 server issues an access token and delivers it to the client by adding 1053 the following parameters to the fragment component of the redirection 1054 URI using the "application/x-www-form-urlencoded" format: 1056 access_token 1057 REQUIRED. The access token issued by the authorization server. 1058 token_type 1059 REQUIRED. The type of the token issued as described in 1060 Section 7.1. Value is case insensitive. 1061 expires_in 1062 OPTIONAL. The duration in seconds of the access token 1063 lifetime. For example, the value "3600" denotes that the 1064 access token will expire in one hour from the time the response 1065 was generated. 1067 scope 1068 OPTIONAL. The scope of the access request expressed as a list 1069 of space-delimited, case sensitive strings. The value is 1070 defined by the authorization server. If the value contains 1071 multiple space-delimited strings, their order does not matter, 1072 and each string adds an additional access range to the 1073 requested scope. The authorization server SHOULD include the 1074 parameter if the requested scope is different from the one 1075 requested by the client. 1076 state 1077 REQUIRED if the "state" parameter was present in the client 1078 authorization request. Set to the exact value received from 1079 the client. 1081 For example, the authorization server redirects the user-agent by 1082 sending the following HTTP response (URI line breaks are for display 1083 purposes only): 1085 HTTP/1.1 302 Found 1086 Location: http://example.com/rd#access_token=FJQbwq9& 1087 token_type=example&expires_in=3600 1089 The client SHOULD ignore unrecognized response parameters. The 1090 access token string size is left undefined by this specification. 1091 The client should avoid making assumptions about value sizes. The 1092 authorization server should document the size of any value it issues. 1094 4.2.2.1. Error Response 1096 If the request fails due to a missing, invalid, or mismatching 1097 redirection URI, or if the client identifier provided is invalid, the 1098 authorization server SHOULD inform the resource owner of the error, 1099 and MUST NOT redirect the user-agent to the invalid redirection URI. 1101 If the resource owner denies the access request or if the request 1102 fails for reasons other than a missing or invalid redirection URI, 1103 the authorization server informs the client by adding the following 1104 parameters to the fragment component of the redirection URI using the 1105 "application/x-www-form-urlencoded" format: 1107 error 1108 REQUIRED. A single error code from the following: 1110 invalid_request 1111 The request is missing a required parameter, includes an 1112 unsupported parameter or parameter value, or is otherwise 1113 malformed. 1114 unauthorized_client 1115 The client is not authorized to request an access token 1116 using this method. 1117 access_denied 1118 The resource owner or authorization server denied the 1119 request. 1120 unsupported_response_type 1121 The authorization server does not support obtaining an 1122 access token using this method. 1123 invalid_scope 1124 The requested scope is invalid, unknown, or malformed. 1125 a 4xx or 5xx HTTP status code (except for 400 and 401) 1126 [[ Pending Consensus ]] The authorization server MAY set 1127 the "error" parameter value to a numerical HTTP status 1128 code from the 4xx or 5xx range, with the exception of the 1129 400 (Bad Request) and 401 (Unauthorized) status codes. 1130 For example, if the service is temporarily unavailable, 1131 the authorization server MAY return an error response 1132 with "error" set to "503". 1133 error_description 1134 OPTIONAL. A human-readable text providing additional 1135 information, used to assist in the understanding and resolution 1136 of the error occurred. 1137 error_uri 1138 OPTIONAL. A URI identifying a human-readable web page with 1139 information about the error, used to provide the resource owner 1140 with additional information about the error. 1141 state 1142 REQUIRED if a valid "state" parameter was present in the client 1143 authorization request. Set to the exact value received from 1144 the client. 1146 For example, the authorization server redirects the user-agent by 1147 sending the following HTTP response: 1149 HTTP/1.1 302 Found 1150 Location: https://client.example.com/cb#error=access_denied 1152 4.3. Resource Owner Password Credentials 1154 The resource owner password credentials grant type is suitable in 1155 cases where the resource owner has a trust relationship with the 1156 client, such as its computer operating system or a highly privileged 1157 application. The authorization server should take special care when 1158 enabling the grant type, and only when other flows are not viable. 1160 The grant type is suitable for clients capable of obtaining the 1161 resource owner credentials (username and password, typically using an 1162 interactive form). It is also used to migrate existing clients using 1163 direct authentication schemes such as HTTP Basic or Digest 1164 authentication to OAuth by converting the stored credentials with an 1165 access token. 1167 +----------+ 1168 | Resource | 1169 | Owner | 1170 | | 1171 +----------+ 1172 v 1173 | 1174 (A) Password Credentials 1175 | 1176 v 1177 +---------+ +---------------+ 1178 | | Client Credentials | | 1179 | |>--(B)---- & Resource Owner ----->| | 1180 | Client | Password Credentials | Authorization | 1181 | | | Server | 1182 | |<--(C)---- Access Token ---------<| | 1183 | | (w/ Optional Refresh Token) | | 1184 +---------+ +---------------+ 1186 Figure 5: Resource Owner Password Credentials Flow 1188 The flow illustrated in Figure 5 includes the following steps: 1190 (A) The resource owner provides the client with its username and 1191 password. 1192 (B) The client requests an access token from the authorization 1193 server's token endpoint by authenticating using its client 1194 credentials, and includes the credentials received from the 1195 resource owner. 1197 (C) The authorization server validates the resource owner 1198 credentials and the client credentials and issues an access 1199 token. 1201 4.3.1. Authorization Request and Response 1203 The method through which the client obtains the resource owner 1204 credentials is beyond the scope of this specification. The client 1205 MUST discard the credentials once an access token has been obtained. 1207 4.3.2. Access Token Request 1209 The client makes a request to the token endpoint by adding the 1210 following parameter using the "application/x-www-form-urlencoded" 1211 format in the HTTP request entity-body: 1213 grant_type 1214 REQUIRED. Value MUST be set to "password". 1215 username 1216 REQUIRED. The resource owner username. 1217 password 1218 REQUIRED. The resource owner password. 1219 scope 1220 OPTIONAL. The scope of the access request expressed as a list 1221 of space-delimited, case sensitive strings. The value is 1222 defined by the authorization server. If the value contains 1223 multiple space-delimited strings, their order does not matter, 1224 and each string adds an additional access range to the 1225 requested scope. 1227 The client includes its authentication credentials as described in 1228 Section 3 1230 For example, the client makes the following HTTP request by including 1231 its client credentials via the "client_id" and "client_secret" 1232 parameters, and using transport-layer security (line breaks are for 1233 display purposes only): 1235 POST /token HTTP/1.1 1236 Host: server.example.com 1237 Content-Type: application/x-www-form-urlencoded 1239 grant_type=password&client_id=s6BhdRkqt3& 1240 client_secret=47HDu8s&username=johndoe&password=A3ddj3w 1242 The authorization server MUST: 1244 o Validate the client credentials. 1245 o Validate the resource owner password credentials. 1247 4.3.3. Access Token Response 1249 If the access token request is valid and authorized, the 1250 authorization server issues an access token and optional refresh 1251 token as described in Section 5.1. If the request failed client 1252 authentication or is invalid, the authorization server returns an 1253 error response as described in Section 5.2. 1255 An example successful response: 1257 HTTP/1.1 200 OK 1258 Content-Type: application/json 1259 Cache-Control: no-store 1261 { 1262 "access_token":"SlAV32hkKG", 1263 "token_type":"example", 1264 "expires_in":3600, 1265 "refresh_token":"8xLOxBtZp8", 1266 "example_parameter":"example_value" 1267 } 1269 4.4. Client Credentials 1271 The client can request an access token using only its client 1272 credentials when the client is requesting access to the protected 1273 resources under its control, or those of another resource owner which 1274 has been previously arranged with the authorization server (the 1275 method of which is beyond the scope of this specification). 1277 +---------+ +---------------+ 1278 | | | | 1279 | |>--(A)--- Client Credentials ---->| Authorization | 1280 | Client | | Server | 1281 | |<--(B)---- Access Token ---------<| | 1282 | | (w/ Optional Refresh Token) | | 1283 +---------+ +---------------+ 1285 Figure 6: Client Credentials Flow 1287 The flow illustrated in Figure 6 includes the following steps: 1289 (A) The client requests an access token from the token endpoint by 1290 authenticating using its client credentials. 1291 (B) The authorization server validates the client credentials and 1292 issues an access token. 1294 4.4.1. Authorization Request and Response 1296 Since the client credentials are used as the authorization grant, no 1297 additional authorization request is needed as the client is already 1298 in the possession of its client credentials. 1300 4.4.2. Access Token Request 1302 The client makes a request to the token endpoint by adding the 1303 following parameter using the "application/x-www-form-urlencoded" 1304 format in the HTTP request entity-body: 1306 grant_type 1307 REQUIRED. Value MUST be set to "client_credentials". 1308 scope 1309 OPTIONAL. The scope of the access request expressed as a list 1310 of space-delimited, case sensitive strings. The value is 1311 defined by the authorization server. If the value contains 1312 multiple space-delimited strings, their order does not matter, 1313 and each string adds an additional access range to the 1314 requested scope. 1316 The client includes its authentication credentials as described in 1317 Section 3 1319 For example, the client makes the following HTTP request by including 1320 its client credentials via the "client_id" and "client_secret" 1321 parameters, and using transport-layer security (line breaks are for 1322 display purposes only): 1324 POST /token HTTP/1.1 1325 Host: server.example.com 1326 Content-Type: application/x-www-form-urlencoded 1328 grant_type=client_credentials&client_id=s6BhdRkqt3& 1329 client_secret=47HDu8s 1331 The authorization server MUST validate the client credentials. 1333 4.4.3. Access Token Response 1335 If the access token request is valid and authorized, the 1336 authorization server issues an access token and optional refresh 1337 token as described in Section 5.1. If the request failed client 1338 authentication or is invalid, the authorization server returns an 1339 error response as described in Section 5.2. 1341 An example successful response: 1343 HTTP/1.1 200 OK 1344 Content-Type: application/json 1345 Cache-Control: no-store 1347 { 1348 "access_token":"SlAV32hkKG", 1349 "token_type":"example", 1350 "expires_in":3600, 1351 "refresh_token":"8xLOxBtZp8", 1352 "example_parameter":"example_value" 1353 } 1355 4.5. Extensions 1357 The client uses an extension grant type by specifying the grant type 1358 using an absolute URI (defined by the authorization server) as the 1359 value of the "grant_type" parameter of the token endpoint, and by 1360 adding any additional parameters necessary. 1362 For example, to request an access token using a SAML 2.0 assertion 1363 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1364 makes the following HTTP request using transport-layer security (line 1365 breaks are for display purposes only): 1367 POST /token HTTP/1.1 1368 Host: server.example.com 1369 Content-Type: application/x-www-form-urlencoded 1371 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F 1372 saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ 1373 [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1375 5. Issuing an Access Token 1377 If the access token request is valid and authorized, the 1378 authorization server issues an access token and optional refresh 1379 token as described in Section 5.1. If the request failed client 1380 authentication or is invalid, the authorization server returns an 1381 error response as described in Section 5.2. 1383 5.1. Successful Response 1385 The authorization server issues an access token and optional refresh 1386 token, and constructs the response by adding the following parameters 1387 to the entity body of the HTTP response with a 200 (OK) status code: 1389 access_token 1390 REQUIRED. The access token issued by the authorization server. 1391 token_type 1392 REQUIRED. The type of the token issued as described in 1393 Section 7.1. Value is case insensitive. 1394 expires_in 1395 OPTIONAL. The duration in seconds of the access token 1396 lifetime. For example, the value "3600" denotes that the 1397 access token will expire in one hour from the time the response 1398 was generated. 1399 refresh_token 1400 OPTIONAL. The refresh token which can be used to obtain new 1401 access tokens using the same authorization grant as described 1402 in Section 6. 1403 scope 1404 OPTIONAL. The scope of the access request expressed as a list 1405 of space-delimited, case sensitive strings. The value is 1406 defined by the authorization server. If the value contains 1407 multiple space-delimited strings, their order does not matter, 1408 and each string adds an additional access range to the 1409 requested scope. The authorization server SHOULD include the 1410 parameter if the requested scope is different from the one 1411 requested by the client. 1413 The parameters are included in the entity body of the HTTP response 1414 using the "application/json" media type as defined by [RFC4627]. The 1415 parameters are serialized into a JSON structure by adding each 1416 parameter at the highest structure level. Parameter names and string 1417 values are included as JSON strings. Numerical values are included 1418 as JSON numbers. 1420 The authorization server MUST include the HTTP "Cache-Control" 1421 response header field [RFC2616] with a value of "no-store" in any 1422 response containing tokens, secrets, or other sensitive information. 1424 For example: 1426 HTTP/1.1 200 OK 1427 Content-Type: application/json 1428 Cache-Control: no-store 1430 { 1431 "access_token":"SlAV32hkKG", 1432 "token_type":"example", 1433 "expires_in":3600, 1434 "refresh_token":"8xLOxBtZp8", 1435 "example_parameter":"example_value" 1436 } 1438 The client SHOULD ignore unrecognized response parameters. The sizes 1439 of tokens and other values received from the authorization server are 1440 left undefined. The client should avoid making assumptions about 1441 value sizes. The authorization server should document the size of 1442 any value it issues. 1444 5.2. Error Response 1446 The authorization server responds with an HTTP 400 (Bad Request) 1447 status code and includes the following parameters with the response: 1449 error 1450 REQUIRED. A single error code from the following: 1451 invalid_request 1452 The request is missing a required parameter, includes an 1453 unsupported parameter or parameter value, repeats a 1454 parameter, includes multiple credentials, utilizes more 1455 than one mechanism for authenticating the client, or is 1456 otherwise malformed. 1457 invalid_client 1458 Client authentication failed (e.g. unknown client, no 1459 client credentials included, multiple client credentials 1460 included, or unsupported credentials type). The 1461 authorization server MAY return an HTTP 401 1462 (Unauthorized) status code to indicate which HTTP 1463 authentication schemes are supported. If the client 1464 attempted to authenticate via the "Authorization" request 1465 header field, the authorization server MUST respond with 1466 an HTTP 401 (Unauthorized) status code, and include the 1467 "WWW-Authenticate" response header field matching the 1468 authentication scheme used by the client. 1470 invalid_grant 1471 The provided authorization grant is invalid, expired, 1472 revoked, does not match the redirection URI used in the 1473 authorization request, or was issued to another client. 1474 unauthorized_client 1475 The authenticated client is not authorized to use this 1476 authorization grant type. 1477 unsupported_grant_type 1478 The authorization grant type is not supported by the 1479 authorization server. 1480 invalid_scope 1481 The requested scope is invalid, unknown, malformed, or 1482 exceeds the scope granted by the resource owner. 1483 error_description 1484 OPTIONAL. A human-readable text providing additional 1485 information, used to assist in the understanding and resolution 1486 of the error occurred. 1487 error_uri 1488 OPTIONAL. A URI identifying a human-readable web page with 1489 information about the error, used to provide the resource owner 1490 with additional information about the error. 1492 The parameters are included in the entity body of the HTTP response 1493 using the "application/json" media type as defined by [RFC4627]. The 1494 parameters are serialized into a JSON structure by adding each 1495 parameter at the highest structure level. Parameter names and string 1496 values are included as JSON strings. Numerical values are included 1497 as JSON numbers. 1499 For example: 1501 HTTP/1.1 400 Bad Request 1502 Content-Type: application/json 1503 Cache-Control: no-store 1505 { 1506 "error":"invalid_request" 1507 } 1509 [[ Pending Consensus ]] If the authorization server encounters an 1510 error condition other than the 400 (Bad Request) and 401 1511 (Unauthorized) responses described above (e.g. the service is 1512 temporarily unavailable), the authorization server SHOULD include an 1513 error response in the entity body, and set the "error" parameter 1514 value to the numerical HTTP status code returned. 1516 For example: 1518 HTTP/1.1 503 Service Unavailable 1519 Content-Type: application/json 1521 { 1522 "error":"503" 1523 } 1525 6. Refreshing an Access Token 1527 The client makes a request to the token endpoint by adding the 1528 following parameter using the "application/x-www-form-urlencoded" 1529 format in the HTTP request entity-body: 1531 grant_type 1532 REQUIRED. Value MUST be set to "refresh_token". 1533 refresh_token 1534 REQUIRED. The refresh token issued to the client. 1535 scope 1536 OPTIONAL. The scope of the access request expressed as a list 1537 of space-delimited, case sensitive strings. The value is 1538 defined by the authorization server. If the value contains 1539 multiple space-delimited strings, their order does not matter, 1540 and each string adds an additional access range to the 1541 requested scope. The requested scope MUST be equal or lesser 1542 than the scope originally granted by the resource owner, and if 1543 omitted is treated as equal to the scope originally granted by 1544 the resource owner. 1546 The client includes its authentication credentials as described in 1547 Section 3. 1549 For example, the client makes the following HTTP request by including 1550 its client credentials via the "client_id" and "client_secret" 1551 parameters, and using transport-layer security (line breaks are for 1552 display purposes only): 1554 POST /token HTTP/1.1 1555 Host: server.example.com 1556 Content-Type: application/x-www-form-urlencoded 1558 grant_type=refresh_token&client_id=s6BhdRkqt3& 1559 client_secret=8eSEIpnqmM&refresh_token=n4E9O119d 1561 The authorization server MUST validate the client credentials, ensure 1562 that the refresh token was issued to the authenticated client, 1563 validate the refresh token, and verify that the resource owner's 1564 authorization is still valid. If valid and authorized, the 1565 authorization server issues an access token as described in 1566 Section 5.1. If the request failed verification or is invalid, the 1567 authorization server returns an error response as described in 1568 Section 5.2. 1570 The authorization server MAY issue a new refresh token, in which 1571 case, the client MUST discard the old refresh token and replace it 1572 with the new refresh token. 1574 7. Accessing Protected Resources 1576 The client accesses protected resources by presenting the access 1577 token to the resource server. The resource server MUST validate the 1578 access token and ensure it has not expired and that its scope covers 1579 the requested resource. The methods used by the resource server to 1580 validate the access token (as well as any error responses) are beyond 1581 the scope of this specification, but generally involve an interaction 1582 or coordination between the resource server and the authorization 1583 server. 1585 The method in which the client utilized the access token to 1586 authenticate with the resource server depends on the type of access 1587 token issued by the authorization server. Typically, it involves 1588 using the HTTP "Authorization" request header field [RFC2617] with an 1589 authentication scheme defined by the access token type specification. 1591 7.1. Access Token Types 1593 The access token type provides the client with the information 1594 required to successfully utilize the access token to make a protected 1595 resource request (along with type-specific attributes). 1597 For example, the "bearer" token type defined in 1598 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1599 token string in the request: 1601 GET /resource/1 HTTP/1.1 1602 Host: example.com 1603 Authorization: Bearer h480djs93hd8 1605 while the "mac" token type defined in [I-D.hammer-oauth-v2-mac-token] 1606 is utilized by issuing a token secret together with the access token 1607 which is used to sign certain components of the HTTP requests: 1609 GET /resource/1 HTTP/1.1 1610 Host: example.com 1611 Authorization: MAC token="h480djs93hd8", 1612 timestamp="137131200", 1613 nonce="dj83hs9s", 1614 signature="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1616 Each access token type definition specifies the additional attributes 1617 (if any) sent to the client together with the "access_token" response 1618 parameter. It also defines the HTTP authentication method used to 1619 include the access token when making a protected resource request. 1621 8. Extensibility 1623 8.1. Defining Access Token Types 1625 Access token types can be defined in one of two ways: registered in 1626 the access token type registry (following the procedures in 1627 Section 10.1), or use a unique absolute URI as its name. 1629 Types utilizing a URI name SHOULD be limited to vendor-specific 1630 implementations that are not commonly applicable, and are specific to 1631 the implementation details of the resource server where they are 1632 used. 1634 All other types MUST be registered. Type names MUST conform to the 1635 type-name ABNF. If the type definition includes a new HTTP 1636 authentication scheme, the type name SHOULD be identical to the HTTP 1637 authentication scheme name (as defined by [RFC2617]). 1639 type-name = 1*name-char 1640 name-char = "-" / "." / "_" / DIGIT / ALPHA 1642 8.2. Defining New Endpoint Parameters 1644 New request or response parameters for use with the authorization 1645 endpoint or the token endpoint are defined and registered in the 1646 parameters registry following the procedure in Section 10.2. 1648 Parameter names MUST conform to the param-name ABNF and parameter 1649 values syntax MUST be well-defined (e.g., using ABNF, or a reference 1650 to the syntax of an existing parameter). 1652 param-name = 1*name-char 1653 name-char = "-" / "." / "_" / DIGIT / ALPHA 1655 Unregistered vendor-specific parameter extensions that are not 1656 commonly applicable, and are specific to the implementation details 1657 of the authorization server where they are used SHOULD utilize a 1658 vendor-specific prefix that is not likely to conflict with other 1659 registered values (e.g. begin with 'companyname_'). 1661 8.3. Defining New Authorization Grant Types 1663 New authorization grant types can be defined by assigning them a 1664 unique absolute URI for use with the "grant_type" parameter. If the 1665 extension grant type requires additional token endpoint parameters, 1666 they MUST be registered in the OAuth parameters registry as described 1667 by Section 10.2. 1669 8.4. Defining Additional Error Codes 1671 [[ Pending Consensus ]] 1673 In cases where protocol extensions (i.e. access token types, 1674 extension parameters, or extension grant types) require additional 1675 error codes to be used with the authorization code grant error 1676 response (Section 4.1.2.1), the implicit grant error response 1677 (Section 4.2.2.1), or the token error response (Section 5.2), such 1678 error codes MAY be defined. 1680 Extension error codes MUST be registered (following the procedures in 1681 Section 10.3) if the extension they are used in conjunction with is 1682 registered. Additional error codes used with unregistered extensions 1683 MAY be registered. 1685 Error codes MUST conform to the error-code ABNF, and SHOULD be 1686 prefixed by an identifying name when possible. For example, an error 1687 identifying an invalid value set to the extension parameter "example" 1688 should be named "example_invalid". 1690 error-code = ALPHA *error-char 1691 error-char = "-" / "." / "_" / DIGIT / ALPHA 1693 9. Security Considerations 1695 [[ TBD ]] 1697 10. IANA Considerations 1699 10.1. The OAuth Access Token Type Registry 1701 This specification establishes the OAuth access token type registry. 1703 Access token types are registered on the advice of one or more 1704 Designated Experts (appointed by the IESG or their delegate), with a 1705 Specification Required (using terminology from [RFC5226]). However, 1706 to allow for the allocation of values prior to publication, the 1707 Designated Expert(s) may approve registration once they are satisfied 1708 that such a specification will be published. 1710 Registration requests should be sent to the [TBD]@ietf.org mailing 1711 list for review and comment, with an appropriate subject (e.g., 1712 "Request for access toke type: example"). [[ Note to RFC-EDITOR: The 1713 name of the mailing list should be determined in consultation with 1714 the IESG and IANA. Suggested name: oauth-ext-review. ]] 1716 Within at most 14 days of the request, the Designated Expert(s) will 1717 either approve or deny the registration request, communicating this 1718 decision to the review list and IANA. Denials should include an 1719 explanation and, if applicable, suggestions as to how to make the 1720 request successful. 1722 Decisions (or lack thereof) made by the Designated Expert can be 1723 first appealed to Application Area Directors (contactable using 1724 app-ads@tools.ietf.org email address or directly by looking up their 1725 email addresses on http://www.iesg.org/ website) and, if the 1726 appellant is not satisfied with the response, to the full IESG (using 1727 the iesg@iesg.org mailing list). 1729 IANA should only accept registry updates from the Designated 1730 Expert(s), and should direct all requests for registration to the 1731 review mailing list. 1733 10.1.1. Registration Template 1735 Type name: 1736 The name requested (e.g., "example"). 1738 Additional Token Endpoint Response Parameters: 1739 Additional response parameters returned together with the 1740 "access_token" parameter. New parameters MUST be separately 1741 registered in the OAuth parameters registry as described by 1742 Section 10.2. 1743 HTTP Authentication Scheme(s): 1744 The HTTP authentication scheme name(s), if any, used to 1745 authenticate protected resources requests using access token of 1746 this type. 1747 Change controller: 1748 For standards-track RFCs, state "IETF". For others, give the name 1749 of the responsible party. Other details (e.g., postal address, 1750 e-mail address, home page URI) may also be included. 1751 Specification document(s): 1752 Reference to document that specifies the parameter, preferably 1753 including a URI that can be used to retrieve a copy of the 1754 document. An indication of the relevant sections may also be 1755 included, but is not required. 1757 10.2. The OAuth Parameters Registry 1759 This specification establishes the OAuth parameters registry. 1761 Additional parameters for inclusion in the authorization endpoint 1762 request, the authorization endpoint response, the token endpoint 1763 request, or the token endpoint response, are registered on the advice 1764 of one or more Designated Experts (appointed by the IESG or their 1765 delegate), with a Specification Required (using terminology from 1766 [RFC5226]). However, to allow for the allocation of values prior to 1767 publication, the Designated Expert(s) may approve registration once 1768 they are satisfied that such a specification will be published. 1770 Registration requests should be sent to the [TBD]@ietf.org mailing 1771 list for review and comment, with an appropriate subject (e.g., 1772 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 1773 the mailing list should be determined in consultation with the IESG 1774 and IANA. Suggested name: oauth-ext-review. ]] 1776 Within at most 14 days of the request, the Designated Expert(s) will 1777 either approve or deny the registration request, communicating this 1778 decision to the review list and IANA. Denials should include an 1779 explanation and, if applicable, suggestions as to how to make the 1780 request successful. 1782 Decisions (or lack thereof) made by the Designated Expert can be 1783 first appealed to Application Area Directors (contactable using 1784 app-ads@tools.ietf.org email address or directly by looking up their 1785 email addresses on http://www.iesg.org/ website) and, if the 1786 appellant is not satisfied with the response, to the full IESG (using 1787 the iesg@iesg.org mailing list). 1789 IANA should only accept registry updates from the Designated 1790 Expert(s), and should direct all requests for registration to the 1791 review mailing list. 1793 10.2.1. Registration Template 1795 Parameter name: 1796 The name requested (e.g., "example"). 1797 Parameter usage location: 1798 The location(s) where parameter can be used. The possible 1799 locations are: authorization request, authorization response, 1800 token request, or token response. 1801 Change controller: 1802 For standards-track RFCs, state "IETF". For others, give the name 1803 of the responsible party. Other details (e.g., postal address, 1804 e-mail address, home page URI) may also be included. 1805 Specification document(s): 1806 Reference to document that specifies the parameter, preferably 1807 including a URI that can be used to retrieve a copy of the 1808 document. An indication of the relevant sections may also be 1809 included, but is not required. 1811 10.2.2. Initial Registry Contents 1813 The OAuth Parameters Registry's initial contents are: 1815 o Parameter name: client_id 1816 o Parameter usage location: authorization request, token request 1817 o Change controller: IETF 1818 o Specification document(s): [[ this document ]] 1820 o Parameter name: client_secret 1821 o Parameter usage location: token request 1822 o Change controller: IETF 1823 o Specification document(s): [[ this document ]] 1825 o Parameter name: response_type 1826 o Parameter usage location: authorization request 1827 o Change controller: IETF 1828 o Specification document(s): [[ this document ]] 1830 o Parameter name: redirect_uri 1831 o Parameter usage location: authorization request, token request 1832 o Change controller: IETF 1833 o Specification document(s): [[ this document ]] 1835 o Parameter name: scope 1836 o Parameter usage location: authorization request, authorization 1837 response, token request, token response 1838 o Change controller: IETF 1839 o Specification document(s): [[ this document ]] 1841 o Parameter name: state 1842 o Parameter usage location: authorization request, authorization 1843 response 1844 o Change controller: IETF 1845 o Specification document(s): [[ this document ]] 1847 o Parameter name: code 1848 o Parameter usage location: authorization response, token request 1849 o Change controller: IETF 1850 o Specification document(s): [[ this document ]] 1852 o Parameter name: error_description 1853 o Parameter usage location: authorization response, token response 1854 o Change controller: IETF 1855 o Specification document(s): [[ this document ]] 1857 o Parameter name: error_uri 1858 o Parameter usage location: authorization response, token response 1859 o Change controller: IETF 1860 o Specification document(s): [[ this document ]] 1862 o Parameter name: grant_type 1863 o Parameter usage location: token request 1864 o Change controller: IETF 1865 o Specification document(s): [[ this document ]] 1867 o Parameter name: access_token 1868 o Parameter usage location: authorization response, token response 1869 o Change controller: IETF 1870 o Specification document(s): [[ this document ]] 1872 o Parameter name: token_type 1873 o Parameter usage location: authorization response, token response 1874 o Change controller: IETF 1875 o Specification document(s): [[ this document ]] 1877 o Parameter name: expires_in 1878 o Parameter usage location: authorization response, token response 1879 o Change controller: IETF 1880 o Specification document(s): [[ this document ]] 1882 o Parameter name: username 1883 o Parameter usage location: token request 1884 o Change controller: IETF 1885 o Specification document(s): [[ this document ]] 1887 o Parameter name: password 1888 o Parameter usage location: token request 1889 o Change controller: IETF 1890 o Specification document(s): [[ this document ]] 1892 o Parameter name: refresh_token 1893 o Parameter usage location: token request, token response 1894 o Change controller: IETF 1895 o Specification document(s): [[ this document ]] 1897 10.3. The OAuth Extensions Error Registry 1899 [[ Pending Consensus ]] 1901 This specification establishes the OAuth extensions error registry. 1903 Additional error codes used together with other protocol extensions 1904 (i.e. extension grant types, access token types, or extension 1905 parameters) are registered on the advice of one or more Designated 1906 Experts (appointed by the IESG or their delegate), with a 1907 Specification Required (using terminology from [RFC5226]). However, 1908 to allow for the allocation of values prior to publication, the 1909 Designated Expert(s) may approve registration once they are satisfied 1910 that such a specification will be published. 1912 Registration requests should be sent to the [TBD]@ietf.org mailing 1913 list for review and comment, with an appropriate subject (e.g., 1914 "Request for error code: example"). [[ Note to RFC-EDITOR: The name 1915 of the mailing list should be determined in consultation with the 1916 IESG and IANA. Suggested name: oauth-ext-review. ]] 1918 Within at most 14 days of the request, the Designated Expert(s) will 1919 either approve or deny the registration request, communicating this 1920 decision to the review list and IANA. Denials should include an 1921 explanation and, if applicable, suggestions as to how to make the 1922 request successful. 1924 Decisions (or lack thereof) made by the Designated Expert can be 1925 first appealed to Application Area Directors (contactable using 1926 app-ads@tools.ietf.org email address or directly by looking up their 1927 email addresses on http://www.iesg.org/ website) and, if the 1928 appellant is not satisfied with the response, to the full IESG (using 1929 the iesg@iesg.org mailing list). 1931 IANA should only accept registry updates from the Designated 1932 Expert(s), and should direct all requests for registration to the 1933 review mailing list. 1935 10.3.1. Registration Template 1937 Error name: 1938 The name requested (e.g., "example"). 1939 Error usage location: 1940 The location(s) where the error can be used. The possible 1941 locations are: authorization code grant error response 1942 (Section 4.1.2.1), implicit grant error response 1943 (Section 4.2.2.1), or token error response (Section 5.2). 1944 Related protocol extension: 1945 The name of the extension grant type, access token type, or 1946 extension parameter, the error code is used in conjunction with. 1947 Change controller: 1948 For standards-track RFCs, state "IETF". For others, give the name 1949 of the responsible party. Other details (e.g., postal address, 1950 e-mail address, home page URI) may also be included. 1951 Specification document(s): 1952 Reference to document that specifies the error code, preferably 1953 including a URI that can be used to retrieve a copy of the 1954 document. An indication of the relevant sections may also be 1955 included, but is not required. 1957 11. Acknowledgements 1959 This specification is the work of the OAuth Working Group which 1960 includes dozens of active and dedicated participants. In particular, 1961 the following individuals contributed ideas, feedback, and wording 1962 which shaped and formed the final specification: 1964 Michael Adams, Andrew Arnott, Dirk Balfanz, Blaine Cook, Brian 1965 Campbell, Leah Culver, Bill de hOra, Brian Eaton, Brian Ellin, Igor 1966 Faynberg, George Fletcher, Tim Freeman, Evan Gilbert, Yaron Goland, 1967 Brent Goldman, Kristoffer Gronowski, Justin Hart, Craig Heath, Phil 1968 Hunt, Michael B. Jones, John Kemp, Mark Kent, Raffi Krikorian, Chasen 1969 Le Hara, Rasmus Lerdorf, Torsten Lodderstedt, Hui-Lan Lu, Paul 1970 Madsen, Alastair Mair, Eve Maler, James Manger, Laurence Miao, Chuck 1971 Mortimore, Justin Richer, Peter Saint-Andre, Nat Sakimura, Rob Sayre, 1972 Marius Scurtescu, Naitik Shah, Luke Shepard, Justin Smith, Jeremy 1973 Suriel, Christian Stuebner, Paul Tarjan, Allen Tom, Franklin Tse, 1974 Nick Walker, Skylar Woodward. 1976 The initial OAuth 2.0 protocol specification was edited by David 1977 Recordon, based on two previous publications: the OAuth 1.0 community 1978 specification [RFC5849], and OAuth WRAP (OAuth Web Resource 1979 Authorization Profiles) [I-D.draft-hardt-oauth-01]. 1981 The OAuth 1.0 community specification was edited by Eran Hammer-Lahav 1982 and authored by Mark Atwood, Dirk Balfanz, Darren Bounds, Richard M. 1983 Conlan, Blaine Cook, Leah Culver, Breno de Medeiros, Brian Eaton, 1984 Kellan Elliott-McCrea, Larry Halff, Eran Hammer-Lahav, Ben Laurie, 1985 Chris Messina, John Panzer, Sam Quigley, David Recordon, Eran 1986 Sandler, Jonathan Sergent, Todd Sieling, Brian Slesinsky, and Andy 1987 Smith. 1989 The OAuth WRAP specification was edited by Dick Hardt and authored by 1990 Brian Eaton, Yaron Goland, Dick Hardt, and Allen Tom. 1992 Appendix A. Editor's Notes 1994 While many people contributed to this specification throughout its 1995 long journey, the editor would like to acknowledge and thank a few 1996 individuals for their outstanding and invaluable efforts leading up 1997 to the publication of this specification. It is these individuals 1998 without whom this work would not have existed, or reached its 1999 successful conclusion. 2001 David Recordon for continuously being one of OAuth's most valuable 2002 assets, bringing pragmatism and urgency to the work, and helping 2003 shape it from its very beginning, as well as being one of the best 2004 collaborators I had the pleasure of working with. 2006 Mark Nottingham for introducing OAuth to the IETF and setting the 2007 community on this course. Lisa Dusseault for her support and 2008 guidance as the Application area director. Blaine Cook, Peter Saint- 2009 Andre, and Hannes Tschofenig for their work as working group chairs. 2011 James Manger for his creative ideas and always insightful feedback. 2012 Brian Campbell, Torsten Lodderstedt, Chuck Mortimore, Justin Richer, 2013 Marius Scurtescu, and Luke Shepard for their continued participation 2014 and valuable feedback. 2016 Special thanks goes to Mike Curtis and Yahoo! for their unconditional 2017 support of this work for over three years. 2019 12. References 2021 12.1. Normative References 2023 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2024 Requirement Levels", BCP 14, RFC 2119, March 1997. 2026 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2027 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2028 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2030 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 2031 Leach, P., Luotonen, A., and L. Stewart, "HTTP 2032 Authentication: Basic and Digest Access Authentication", 2033 RFC 2617, June 1999. 2035 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2036 Resource Identifier (URI): Generic Syntax", STD 66, 2037 RFC 3986, January 2005. 2039 [RFC4627] Crockford, D., "The application/json Media Type for 2040 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 2042 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2043 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2044 May 2008. 2046 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2047 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2049 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2050 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2052 [W3C.REC-html401-19991224] 2053 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 2054 Specification", World Wide Web Consortium 2055 Recommendation REC-html401-19991224, December 1999, 2056 . 2058 12.2. Informative References 2060 [I-D.draft-hardt-oauth-01] 2061 Hardt, D., Ed., Tom, A., Eaton, B., and Y. Goland, "OAuth 2062 Web Resource Authorization Profiles", January 2010. 2064 [I-D.hammer-oauth-v2-mac-token] 2065 Hammer-Lahav, E., "HTTP Authentication: MAC 2066 Authentication", draft-hammer-oauth-v2-mac-token-02 (work 2067 in progress), January 2011. 2069 [I-D.ietf-oauth-saml2-bearer] 2070 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 2071 Grant Type Profile for OAuth 2.0", 2072 draft-ietf-oauth-saml2-bearer-03 (work in progress), 2073 February 2011. 2075 [I-D.ietf-oauth-v2-bearer] 2076 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 2077 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-02 2078 (work in progress), January 2011. 2080 [OASIS.saml-core-2.0-os] 2081 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 2082 "Assertions and Protocol for the OASIS Security Assertion 2083 Markup Language (SAML) V2.0", OASIS Standard saml-core- 2084 2.0-os, March 2005. 2086 [RFC5849] Hammer-Lahav, E., "The OAuth 1.0 Protocol", RFC 5849, 2087 April 2010. 2089 Authors' Addresses 2091 Eran Hammer-Lahav (editor) 2092 Yahoo! 2094 Email: eran@hueniverse.com 2095 URI: http://hueniverse.com 2097 David Recordon 2098 Facebook 2100 Email: dr@fb.com 2101 URI: http://www.davidrecordon.com/ 2103 Dick Hardt 2104 Microsoft 2106 Email: dick.hardt@gmail.com 2107 URI: http://dickhardt.org/