idnits 2.17.1 draft-ietf-oauth-v2-13.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 (February 16, 2011) is 4817 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 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 Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 2 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: August 20, 2011 D. Hardt 7 Microsoft 8 February 16, 2011 10 The OAuth 2.0 Authorization Protocol 11 draft-ietf-oauth-v2-13 13 Abstract 15 This specification describes the OAuth 2.0 authorization protocol. 17 Status of this Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on August 20, 2011. 34 Copyright Notice 36 Copyright (c) 2011 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 1.1. Roles . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.2. Protocol Flow . . . . . . . . . . . . . . . . . . . . . . 4 54 1.3. Access Token . . . . . . . . . . . . . . . . . . . . . . . 5 55 1.4. Authorization Grant . . . . . . . . . . . . . . . . . . . 6 56 1.5. Refresh Token . . . . . . . . . . . . . . . . . . . . . . 8 57 1.6. Document Structure . . . . . . . . . . . . . . . . . . . . 10 58 1.7. Notational Conventions . . . . . . . . . . . . . . . . . . 10 59 2. Protocol Endpoints . . . . . . . . . . . . . . . . . . . . . . 10 60 2.1. Authorization Endpoint . . . . . . . . . . . . . . . . . . 11 61 2.2. Token Endpoint . . . . . . . . . . . . . . . . . . . . . . 12 62 3. Client Authentication . . . . . . . . . . . . . . . . . . . . 13 63 3.1. Client Password Authentication . . . . . . . . . . . . . . 13 64 3.2. Other Client Authentication Methods . . . . . . . . . . . 13 65 4. Obtaining Authorization . . . . . . . . . . . . . . . . . . . 14 66 4.1. Authorization Code . . . . . . . . . . . . . . . . . . . . 14 67 4.2. Implicit Grant . . . . . . . . . . . . . . . . . . . . . . 20 68 4.3. Resource Owner Password Credentials . . . . . . . . . . . 25 69 4.4. Client Credentials . . . . . . . . . . . . . . . . . . . . 28 70 4.5. Extensions . . . . . . . . . . . . . . . . . . . . . . . . 30 71 5. Issuing an Access Token . . . . . . . . . . . . . . . . . . . 30 72 5.1. Successful Response . . . . . . . . . . . . . . . . . . . 31 73 5.2. Error Response . . . . . . . . . . . . . . . . . . . . . . 32 74 6. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 33 75 7. Accessing Protected Resources . . . . . . . . . . . . . . . . 34 76 7.1. Access Token Types . . . . . . . . . . . . . . . . . . . . 35 77 8. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 36 78 8.1. Defining Access Token Types . . . . . . . . . . . . . . . 36 79 8.2. Defining New Endpoint Parameters . . . . . . . . . . . . . 36 80 8.3. Defining New Authorization Grant Types . . . . . . . . . . 36 81 9. Security Considerations . . . . . . . . . . . . . . . . . . . 37 82 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 83 10.1. The OAuth Access Token Type Registry . . . . . . . . . . . 37 84 10.2. The OAuth Parameters Registry . . . . . . . . . . . . . . 38 85 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 41 86 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 41 87 Appendix C. Document History . . . . . . . . . . . . . . . . . . 41 88 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 89 11.1. Normative References . . . . . . . . . . . . . . . . . . . 42 90 11.2. Informative References . . . . . . . . . . . . . . . . . . 42 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 43 93 1. Introduction 95 In the traditional client-server authentication model, the client 96 accesses a protected resource on the server by authenticating with 97 the server using the resource owner's credentials. In order to 98 provide third-party applications access to protected resources, the 99 resource owner shares its credentials with the third-party. This 100 creates several problems and limitations: 102 o Third-party applications are required to store the resource- 103 owner's credentials for future use, typically a password in clear- 104 text. 105 o Servers are required to support password authentication, despite 106 the security weaknesses created by passwords. 107 o Third-party applications gain overly broad access to the resource- 108 owner's protected resources, leaving resource owners without any 109 ability to restrict duration or access to a limited subset of 110 resources. 111 o Resource owners cannot revoke access to an individual third-party 112 without revoking access to all third-parties, and must do so by 113 changing their password. 115 OAuth addresses these issues by introducing an authorization layer 116 and separating the role of the client from that of the resource 117 owner. In OAuth, the client requests access to resources controlled 118 by the resource owner and hosted by the resource server, and is 119 issued a different set of credentials than those of the resource 120 owner. 122 Instead of using the resource owner's credentials to access protected 123 resources, the client obtains an access token - a string denoting a 124 specific scope, duration, and other access attributes. Access tokens 125 are issued to third-party clients by an authorization server with the 126 approval of the resource owner. The client uses the access token to 127 access the protected resources hosted by the resource server. 129 For example, a web user (resource owner) can grant a printing service 130 (client) access to her protected photos stored at a photo sharing 131 service (resource server), without sharing her username and password 132 with the printing service. Instead, she authenticates directly with 133 a server trusted by the photo sharing service (authorization server) 134 which issues the printing service delegation-specific credentials 135 (access token). 137 1.1. Roles 139 OAuth includes four roles working together to grant and provide 140 access to protected resources - access restricted resources which 141 require authentication to access: 143 resource owner 144 An entity capable of granting access to a protected resource. 145 When the resource owner is a person, it is referred to as an end- 146 user. 147 resource server 148 The server hosting the protected resources, capable of accepting 149 and responding to protected resource requests using access tokens. 150 client 151 An application making protected resource requests on behalf of the 152 resource owner and with its authorization. 153 authorization server 154 The server issuing access tokens to the client after successfully 155 authenticating the resource owner and obtaining authorization. 157 The interaction between the authorization server and resource server 158 is beyond the scope of this specification. The authorization server 159 may be the same server as the resource server or a separate entity. 160 A single authorization server may issue access tokens accepted by 161 multiple resource servers. 163 1.2. Protocol Flow 165 When interacting with the authorization server, the client identifies 166 itself using a set of client credentials which include a client 167 identifier and other authentication attributes. The means through 168 which the client obtains its credentials are beyond the scope of this 169 specification, but typically involve registration with the 170 authorization server. 172 +--------+ +---------------+ 173 | |--(A)- Authorization Request ->| Resource | 174 | | | Owner | 175 | |<-(B)-- Authorization Grant ---| | 176 | | +---------------+ 177 | | 178 | | Authorization Grant & +---------------+ 179 | |--(C)--- Client Credentials -->| Authorization | 180 | Client | | Server | 181 | |<-(D)----- Access Token -------| | 182 | | +---------------+ 183 | | 184 | | +---------------+ 185 | |--(E)----- Access Token ------>| Resource | 186 | | | Server | 187 | |<-(F)--- Protected Resource ---| | 188 +--------+ +---------------+ 190 Figure 1: Abstract Protocol Flow 192 The abstract flow illustrated in Figure 1 describes the interaction 193 between the four roles and includes the following steps: 195 (A) The client requests authorization from the resource owner. The 196 authorization request can be made directly to the resource owner 197 (as shown), or preferably indirectly via an intermediary such as 198 an authorization server. 199 (B) The client receives an authorization grant which represents the 200 authorization provided by the resource owner. The authorization 201 grant type depends on the method used by the client and 202 supported by the authorization server to obtain it. 203 (C) The client requests an access token by authenticating with the 204 authorization server using its client credentials (prearranged 205 between the client and authorization server) and presenting the 206 authorization grant. 207 (D) The authorization server validates the client credentials and 208 the authorization grant, and if valid issues an access token. 209 (E) The client requests the protected resource from the resource 210 server and authenticates by presenting the access token. 211 (F) The resource server validates the access token, and if valid, 212 serves the request. 214 1.3. Access Token 216 An access token is a string representing an authorization issued to 217 the client. The string is usually opaque to the client. Tokens 218 represent specific scopes and durations of access, granted by the 219 resource owner, and enforced by the resource server and authorization 220 server. 222 The token may denote an identifier used to retrieve the authorization 223 information, or self-contain the authorization information in a 224 verifiable manner (i.e. a token string consisting of some data and a 225 signature). Additional authentication credentials may be required in 226 order for the client to use a token. 228 The access token provides an abstraction layer, replacing different 229 authorization constructs (e.g. username and password) with a single 230 token understood by the resource server. This abstraction enables 231 issuing access tokens more restrictive than the authorization grant 232 used to obtain them, as well as removing the resource server's need 233 to understand a wide range of authentication methods. 235 Access tokens can have different formats, structures, and methods of 236 utilization (e.g. cryptographic properties) based on the resource 237 server security requirements. Access token attributes and the 238 methods used to access protected resources are beyond the scope of 239 this specification and are defined by companion specifications. 241 1.4. Authorization Grant 243 An authorization grant is a general term used to describe the 244 intermediate credentials representing the resource owner 245 authorization, and serves as an abstraction layer. An authorization 246 grant is used by the client to obtain an access token. 248 1.4.1. Authorization Code 250 The authorization code is obtained by using an authorization server 251 as an intermediary between the client and resource owner. Instead of 252 requesting authorization directly from the resource owner, the client 253 directs the resource owner to an authorization server (via its user- 254 agent), which in turns directs the resource owner back to the client 255 with the authorization code. 257 Before directing the resource owner back to the client with the 258 authorization code, the authorization server authenticates the 259 resource owner and obtains authorization. Because the resource owner 260 only authenticates with the authorization server, the resource 261 owner's credentials are never shared with the client. 263 The authorization code provides a few important security benefits 264 such as the ability to authenticate the client and issuing the access 265 token directly to the client without potentially exposing it to 266 others, including the resource owner. 268 1.4.2. Implicit 270 An implicit grant is issued when the resource owner's authorization 271 is expressed directly as an access token, without using an 272 intermediate credential. The implicit grant is issued in a similar 273 manner as an authorization code, but instead of the resource owner 274 being redirected back to the client with the authorization code, it 275 is redirected back with an access token and its related attributes. 277 When issuing an implicit grant, the authorization server cannot 278 verify the identity of the client, and the access token may be 279 exposed to the resource owner or other applications with access to 280 the resource owner's user-agent. 282 Implicit grants improve the responsiveness and efficiency of some 283 clients (such as a client implemented as an in-browser application) 284 since it reduces the number of round trips required to obtain an 285 access token. 287 1.4.3. Resource Owner Password Credentials 289 The resource owner password credentials (e.g. a username and 290 password) can be used directly as an authorization grant to obtain an 291 access token. The credentials should only be used when there is a 292 high degree of trust between the resource owner and the client (e.g. 293 its computer operating system or a highly privileged application), 294 and when other authorization grant types are not available (such as 295 an authorization code). 297 Even though this grant type requires direct client access to the 298 resource owner credentials, the resource owner credentials are used 299 for a single request and are exchanged for an access token. Unlike 300 the HTTP Basic authentication scheme defined in [RFC2617], this grant 301 type eliminates the need for the client to store the resource-owner 302 credentials for future use. 304 1.4.4. Client Credentials 306 The client credentials can be used as an authorization grant when the 307 authorization scope is limited to the protected resources under the 308 control of the client, or to protected resources previously arranged 309 with the authorization server. Client credentials are used as an 310 authorization grant typically when the client is acting on its own 311 behalf (the client is also the resource owner). 313 1.4.5. Extensions 315 Additional grant types may be defined to provide a bridge between 316 OAuth and other trust frameworks. For example, 317 [I-D.ietf-oauth-saml2-bearer] defines a SAML 2.0 318 [OASIS.saml-core-2.0-os] bearer assertion grant type, which can be 319 used to obtain an access token. 321 1.5. Refresh Token 323 A refresh token is optionally issued by the authorization server to 324 the client together with an access token. The client can use the 325 refresh token to request another access token based on the same 326 authorization, without having to involve the resource owner again, or 327 having to retain the original authorization grant used to obtain the 328 initial access token. 330 A refresh token is a string representing the authorization granted to 331 the client by the resource owner. The string is usually opaque to 332 the client. The token may denote an identifier used to retrieve the 333 authorization information, or self-contain the authorization 334 information in a verifiable manner. 336 The refresh token can be used to obtain a new access token when the 337 current access token expires (access tokens may have a shorter 338 lifetime than authorized by the resource owner), or to obtain 339 additional access tokens with identical or narrower scope. 341 +--------+ Authorization Grant & +---------------+ 342 | |--(A)-------- Client Credentials --------->| | 343 | | | | 344 | |<-(B)----------- Access Token -------------| | 345 | | & Refresh Token | | 346 | | | | 347 | | +----------+ | | 348 | |--(C)---- Access Token ---->| | | | 349 | | | | | | 350 | |<-(D)- Protected Resource --| Resource | | Authorization | 351 | Client | | Server | | Server | 352 | |--(E)---- Access Token ---->| | | | 353 | | | | | | 354 | |<-(F)- Invalid Token Error -| | | | 355 | | +----------+ | | 356 | | | | 357 | | Refresh Token & | | 358 | |--(G)-------- Client Credentials --------->| | 359 | | | | 360 | |<-(H)----------- Access Token -------------| | 361 +--------+ & Optional Refresh Token +---------------+ 363 Figure 2: Refreshing an Expired Access Token 365 The flow illustrated in Figure 2 includes the following steps: 367 (A) The client requests an access token by authenticating with the 368 authorization server using its client credentials, and 369 presenting an authorization grant. 370 (B) The authorization server validates the client credentials and 371 the authorization grant, and if valid issues an access token and 372 a refresh token. 373 (C) The client makes a protected resource requests to the resource 374 server by presenting the access token. 375 (D) The resource server validates the access token, and if valid, 376 serves the request. 377 (E) Steps (C) and (D) repeat until the access token expires. If the 378 client knows the access token expired, it skips to step (G), 379 otherwise it makes another protected resource request. 380 (F) Since the access token is invalid (expired), the resource server 381 returns an invalid token error. 382 (G) The client requests a new access token by authenticating with 383 the authorization server using its client credentials, and 384 presenting the refresh token. 386 (H) The authorization server validates the client credentials and 387 the refresh token, and if valid issues a new access token (and 388 optionally, a new refresh token). 390 1.6. Document Structure 392 This specification is organized into the following sections: 394 o Section 2 - describes the two endpoints used to obtain and utilize 395 the various authorization grant types. 396 o Section 3 - describes client identification and authentication in 397 general, and provides one such method for client authentication 398 using password credentials. 399 o Section 4 - describes the complete flow for each authorization 400 grant type, including requesting authorization, authorization 401 response, and requesting an access token. 402 o Section 5 - describes the common access token response used for 403 all non-implicit authorization grant types. 404 o Section 6 - describes the use of a refresh token to obtain 405 additional access tokens using the same resource owner 406 authorization. 407 o Section 7 - describes how access tokens are used to access 408 protected resources. 409 o Section 8 - describes how to extend certain elements of the 410 protocol. 411 o Section 9 - provides a security analysis of the protocol. 413 1.7. Notational Conventions 415 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 416 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this 417 specification are to be interpreted as described in [RFC2119]. 419 This specification uses the Augmented Backus-Naur Form (ABNF) 420 notation of [RFC5234]. 422 Unless otherwise noted, all the protocol parameter names and values 423 are case sensitive. 425 2. Protocol Endpoints 427 The authorization process utilizes two endpoints: 429 o Authorization endpoint - used to obtain authorization from the 430 resource owner via user-agent redirection. 432 o Token endpoint - used to exchange an authorization grant for an 433 access token, typically with client authentication. 435 Not every authorization grant type utilizes both endpoints. 436 Extension grant types MAY define additional endpoints as needed. 438 2.1. Authorization Endpoint 440 The authorization endpoint is used to interact with the resource 441 owner and obtain authorization which is expressed explicitly as an 442 authorization code (exchanged for an access token), or implicitly by 443 direct issuance of an access token. 445 The authorization server MUST first verify the identity of the 446 resource owner. The way in which the authorization server 447 authenticates the resource owner (e.g. username and password login, 448 session cookies) is beyond the scope of this specification. 450 The location of the authorization endpoint can be found in the 451 service documentation. The endpoint URI MAY include a query 452 component as defined by [RFC3986] section 3, which MUST be retained 453 when adding additional query parameters. 455 Requests to the authorization endpoint result in user authentication 456 and the transmission of sensitive information. If the response 457 includes an access token, the authorization server MUST require TLS 458 1.2 as defined in [RFC5246] and MAY support additional transport- 459 layer mechanisms meeting its security requirements. If the response 460 does not include an access token, the authorization server SHOULD 461 require TLS 1.2 and any additional transport-layer mechanism meeting 462 its security requirements. 464 The authorization server MUST support the use of the HTTP "GET" 465 method for the authorization endpoint, and MAY support the use of the 466 "POST" method as well. 468 Parameters sent without a value MUST be treated as if they were 469 omitted from the request. The authorization server SHOULD ignore 470 unrecognized request parameters. 472 2.1.1. Redirection URI 474 The client directs the resource owner's user-agent to the 475 authorization endpoint and includes a redirection URI to which the 476 authorization server will redirect the user-agent back once 477 authorization has been obtained (or denied). The client MAY omit the 478 redirection URI if one has been established between the client and 479 authorization server via other means, such as during the client 480 registration process. 482 The redirection URI MUST be an absolute URI and MAY include a query 483 component, which MUST be retained by the authorization server when 484 adding additional query parameters. 486 The authorization server SHOULD require the client to pre-register 487 their redirection URI or at least certain components such as the 488 scheme, host, port and path. If a redirection URI was registered, 489 the authorization server MUST compare any redirection URI received at 490 the authorization endpoint with the registered URI. 492 The authorization server SHOULD NOT redirect the user-agent to 493 unregistered or untrusted URIs to prevent the endpoint from being 494 used as an open redirector. If no valid redirection URI is 495 available, the authorization server SHOULD inform the resource owner 496 directly of the error. 498 2.2. Token Endpoint 500 The token endpoint is used by the client to obtain an access token by 501 authenticating with the authorization server and presenting its 502 authorization grant. The token endpoint is used with every 503 authorization grant except for the implicit grant type (since an 504 access token is issued directly). 506 The location of the token endpoint can be found in the service 507 documentation. The endpoint URI MAY include a query component, which 508 MUST be retained when adding additional query parameters. 510 Since requests to the token endpoint result in the transmission of 511 clear-text credentials (in the HTTP request and response), the 512 authorization server MUST require the use of a transport-layer 513 security mechanism when sending requests to the token endpoints. The 514 authorization server MUST support TLS 1.2 as defined in [RFC5246], 515 and MAY support additional transport-layer mechanisms meeting its 516 security requirements. 518 The token endpoint requires client authentication as described in 519 Section 3. The authorization server MAY accept any form of client 520 authentication meeting its security requirements. The client MUST 521 NOT use more than one authentication method in each request. 523 The client MUST use the HTTP "POST" method when making access token 524 requests. 526 Parameters sent without a value MUST be treated as if they were 527 omitted from the request. The authorization server SHOULD ignore 528 unrecognized request parameters. 530 3. Client Authentication 532 Client credentials are used to identify and authenticate the client. 533 The client credentials include a client identifier - a unique string 534 issued to the client to identify itself to the authorization server. 535 The methods through which the client obtains its client credentials 536 are beyond the scope of this specification. 538 Due to the nature of some clients, the authorization server should 539 not make assumptions about the confidentiality of client credentials 540 without establishing trust with the client. The authorization server 541 SHOULD NOT issue client credentials to clients incapable of keeping 542 their secrets confidential. 544 3.1. Client Password Authentication 546 The client password authentication uses a shared symmetric secret to 547 authenticate the client. The client identifier and password are 548 included in the request using the following parameters: 550 client_id 551 REQUIRED. The client identifier. 552 client_secret 553 REQUIRED. The client password. 555 For example (line breaks are for display purposes only): 557 POST /token HTTP/1.1 558 Host: server.example.com 559 Content-Type: application/x-www-form-urlencoded 561 grant_type=authorization_code&client_id=s6BhdRkqt3& 562 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 563 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 565 3.2. Other Client Authentication Methods 567 In cases where client password authentication is not suitable or 568 sufficient, the authorization server MAY support other existing HTTP 569 authentication schemes or define new methods. In addition, the 570 authorization server MAY allow unauthenticated access token requests 571 when the client identity does not matter (e.g. anonymous client) or 572 when the client identity is established via other means. 574 For example, the authorization server MAY support using the HTTP 575 Basic authentication scheme as defined in [RFC2617] to include the 576 client identifier as the username and client password as the password 577 (line breaks are for display purposes only): 579 POST /token HTTP/1.1 580 Host: server.example.com 581 Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW 582 Content-Type: application/x-www-form-urlencoded 584 grant_type=authorization_code&code=i1WsRn1uB1& 585 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 587 When using a method other than client password authentication to 588 exchange an authorization code grant type, the authorization server 589 MUST define a method for mapping the client credentials to the client 590 identifier used to obtain the authorization code. 592 4. Obtaining Authorization 594 To request an access token, the client obtains authorization from the 595 resource owner. The authorization is expressed in the form of an 596 authorization grant which the client uses to requesting the access 597 token. OAuth defines four grant types: authorization code, implicit, 598 resource owner password credentials, and client credentials. It also 599 provides an extension mechanism for defining additional grant types. 601 4.1. Authorization Code 603 The authorization code grant type is suitable for clients capable of 604 maintaining their client credentials confidential (for authenticating 605 with the authorization server) such as a client implemented on a 606 secure server. As a redirection-based flow, the client must be 607 capable of interacting with the resource owner's user-agent 608 (typically a web browser) and capable of receiving incoming requests 609 (via redirection) from the authorization server. 611 +----------+ 612 | resource | 613 | owner | 614 | | 615 +----------+ 616 ^ 617 | 618 (B) 619 +----|-----+ Client Identifier +---------------+ 620 | -+----(A)--- & Redirect URI ------>| | 621 | User- | | Authorization | 622 | Agent -+----(B)-- User authenticates --->| Server | 623 | | | | 624 | -+----(C)-- Authorization Code ---<| | 625 +-|----|---+ +---------------+ 626 | | ^ v 627 (A) (C) | | 628 | | | | 629 ^ v | | 630 +---------+ | | 631 | |>---(D)-- Client Credentials, --------' | 632 | | Authorization Code, | 633 | Client | & Redirect URI | 634 | | | 635 | |<---(E)----- Access Token -------------------' 636 +---------+ (w/ Optional Refresh Token) 638 Figure 3: Authorization Code Flow 640 The flow illustrated in Figure 3 includes the following steps: 642 (A) The client initiates the flow by directing the resource owner's 643 user-agent to the authorization endpoint. The client includes 644 its client identifier, requested scope, local state, and a 645 redirection URI to which the authorization server will send the 646 user-agent back once access is granted (or denied). 647 (B) The authorization server authenticates the resource owner (via 648 the user-agent) and establishes whether the resource owner 649 grants or denies the client's access request. 650 (C) Assuming the resource owner grants access, the authorization 651 server redirects the user-agent back to the client using the 652 redirection URI provided earlier. The redirection URI includes 653 an authorization code. 655 (D) The client requests an access token from the authorization 656 server's token endpoint by authenticating using its client 657 credentials, and includes the authorization code received in the 658 previous step. 659 (E) The authorization server validates the client credentials and 660 the authorization code and if valid, responds back with an 661 access token. 663 4.1.1. Authorization Request 665 The client constructs the request URI by adding the following 666 parameters to the query component of the authorization endpoint URI 667 using the "application/x-www-form-urlencoded" format as defined by 668 [W3C.REC-html401-19991224]: 670 response_type 671 REQUIRED. Value MUST be set to "code". 672 client_id 673 REQUIRED. The client identifier as described in Section 3. 674 redirect_uri 675 REQUIRED, unless a redirection URI has been established between 676 the client and authorization server via other means. Described 677 in Section 2.1.1. 678 scope 679 OPTIONAL. The scope of the access request expressed as a list 680 of space-delimited strings. The value is defined by the 681 authorization server. If the value contains multiple space- 682 delimited strings, their order does not matter, and each string 683 adds an additional access range to the requested scope. 684 state 685 OPTIONAL. An opaque value used by the client to maintain state 686 between the request and callback. The authorization server 687 includes this value when redirecting the user-agent back to the 688 client. 690 The client directs the resource owner to the constructed URI using an 691 HTTP redirection response, or by other means available to it via the 692 user-agent. 694 For example, the client directs the user-agent to make the following 695 HTTP request using transport-layer security (line breaks are for 696 display purposes only): 698 GET /authorize?response_type=code&client_id=s6BhdRkqt3& 699 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 700 Host: server.example.com 702 The authorization server validates the request to ensure all required 703 parameters are present and valid. If the request is valid, the 704 authorization server authenticates the resource owner and obtains an 705 authorization decision (by asking the resource owner or by 706 establishing approval via other means). 708 When a decision is established, the authorization server directs the 709 user-agent to the provided client redirection URI using an HTTP 710 redirection response, or by other means available to it via the user- 711 agent. 713 4.1.2. Authorization Response 715 If the resource owner grants the access request, the authorization 716 server issues an authorization code and delivers it to the client by 717 adding the following parameters to the query component of the 718 redirection URI using the "application/x-www-form-urlencoded" format: 720 code 721 REQUIRED. The authorization code generated by the 722 authorization server. The authorization code SHOULD expire 723 shortly after it is issued to minimize the risk of leaks. The 724 client MUST NOT reuse the authorization code. If an 725 authorization code is used more than once, the authorization 726 server MAY revoke all tokens previously issued based on that 727 authorization code. The authorization code is bound to the 728 client identifier and redirection URI. 729 state 730 REQUIRED if the "state" parameter was present in the client 731 authorization request. Set to the exact value received from 732 the client. 734 For example, the authorization server redirects the user-agent by 735 sending the following HTTP response: 737 HTTP/1.1 302 Found 738 Location: https://client.example.com/cb?code=i1WsRn1uB1 740 The client SHOULD ignore unrecognized response parameters. The 741 authorization code string size is left undefined by this 742 specification. The clients should avoid making assumptions about 743 code value sizes. The authorization server should document the size 744 of any value it issues. 746 4.1.2.1. Error Response 748 If the request fails due to a missing, invalid, or mismatching 749 redirection URI, or if the client identifier provided is invalid, the 750 authorization server SHOULD inform the resource owner of the error, 751 and MUST NOT redirect the user-agent to the invalid redirection URI. 753 If the resource owner denies the access request or if the request 754 fails for reasons other than a missing or invalid redirection URI, 755 the authorization server informs the client by adding the following 756 parameters to the query component of the redirection URI using the 757 "application/x-www-form-urlencoded" format: 759 error 760 REQUIRED. A single error code from the following: 761 invalid_request 762 The request is missing a required parameter, includes an 763 unsupported parameter or parameter value, or is otherwise 764 malformed. 765 unauthorized_client 766 The client is not authorized to request an authorization 767 code using this method. 768 access_denied 769 The resource owner or authorization server denied the 770 request. 771 unsupported_response_type 772 The authorization server does not support obtaining an 773 authorization code using this method. 774 invalid_scope 775 The requested scope is invalid, unknown, or malformed. 776 error_description 777 OPTIONAL. A human-readable text providing additional 778 information, used to assist in the understanding and resolution 779 of the error occurred. 780 error_uri 781 OPTIONAL. A URI identifying a human-readable web page with 782 information about the error, used to provide the resource owner 783 with additional information about the error. 784 state 785 REQUIRED if the "state" parameter was present in the client 786 authorization request. Set to the exact value received from 787 the client. 789 For example, the authorization server redirects the user-agent by 790 sending the following HTTP response: 792 HTTP/1.1 302 Found 793 Location: https://client.example.com/cb?error=access_denied 795 4.1.3. Access Token Request 797 The client makes a request to the token endpoint by adding the 798 following parameter using the "application/x-www-form-urlencoded" 799 format in the HTTP request entity-body: 801 grant_type 802 REQUIRED. Value MUST be set to "authorization_code". 803 code 804 REQUIRED. The authorization code received from the 805 authorization server. 806 redirect_uri 807 REQUIRED. The redirection URI used by the authorization server 808 to return the authorization response in the previous step. 810 The client includes its authentication credentials as described in 811 Section 3 813 For example, the client makes the following HTTP request by including 814 its client credentials via the "client_id" and "client_secret" 815 parameters, and using transport-layer security (line breaks are for 816 display purposes only): 818 POST /token HTTP/1.1 819 Host: server.example.com 820 Content-Type: application/x-www-form-urlencoded 822 grant_type=authorization_code&client_id=s6BhdRkqt3& 823 client_secret=gX1fBat3bV&code=i1WsRn1uB1& 824 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 826 The authorization server MUST: 828 o Validate the client credentials and ensure they match the 829 authorization code. 830 o Verify that the authorization code is valid, and that the 831 redirection URI matches the redirection URI used by the 832 authorization server to deliver the authorization code. 834 4.1.4. Access Token Response 836 If the access token request is valid and authorized, the 837 authorization server issues an access token and optional refresh 838 token as described in Section 5.1. If the request failed client 839 authentication or is invalid, the authorization server return an 840 error response as described in Section 5.2. 842 An example successful response: 844 HTTP/1.1 200 OK 845 Content-Type: application/json 846 Cache-Control: no-store 848 { 849 "access_token":"SlAV32hkKG", 850 "token_type":"example", 851 "expires_in":3600, 852 "refresh_token":"8xLOxBtZp8", 853 "example_parameter":"example-value" 854 } 856 4.2. Implicit Grant 858 The implicit grant type is suitable for clients incapable of 859 maintaining their client credentials confidential (for authenticating 860 with the authorization server) such as client applications residing 861 in a user-agent, typically implemented in a browser using a scripting 862 language such as JavaScript, or native applications. These clients 863 cannot keep client secrets confidential and the authentication of the 864 client is based on the user-agent's same-origin policy. 866 As a redirection-based flow, the client must be capable of 867 interacting with the resource owner's user-agent (typically a web 868 browser) and capable of receiving incoming requests (via redirection) 869 from the authorization server. 871 Unlike the authorization code grant type in which the client makes 872 separate requests for authorization and access token, the client 873 receives the access token as the result of the authorization request. 875 Using the implicit grant type does not include client authentication 876 since the client is unable to maintain their credential 877 confidentiality (the client resides on the resource owner's computer 878 or device which makes the client credentials accessible and 879 exploitable). Because the access token is encoded into the 880 redirection URI, it may be exposed to the resource owner and other 881 applications residing on its computer or device. 883 +----------+ 884 | Resource | 885 | Owner | 886 | | 887 +----------+ 888 ^ 889 | 890 (B) 891 +----|-----+ Client Identifier +---------------+ 892 | -+----(A)--- & Redirect URI ----->| | 893 | User- | | Authorization | 894 | Agent -|----(B)-- User authenticates -->| Server | 895 | | | | 896 | |<---(C)---- Redirect URI ------<| | 897 | | with Access Token +---------------+ 898 | | in Fragment 899 | | +---------------+ 900 | |----(D)---- Redirect URI ------>| Web Server | 901 | | without Fragment | with Client | 902 | | | Resource | 903 | (F) |<---(E)------- Script ---------<| | 904 | | +---------------+ 905 +-|--------+ 906 | | 907 (A) (G) Access Token 908 | | 909 ^ v 910 +---------+ 911 | | 912 | Client | 913 | | 914 +---------+ 916 Figure 4: Implicit Grant Flow 918 The flow illustrated in Figure 4 includes the following steps: 920 (A) The client initiates the flow by directing the resource owner's 921 user-agent to the authorization endpoint. The client includes 922 its client identifier, requested scope, local state, and a 923 redirection URI to which the authorization server will send the 924 user-agent back once access is granted (or denied). 925 (B) The authorization server authenticates the resource owner (via 926 the user-agent) and establishes whether the resource owner 927 grants or denies the client's access request. 929 (C) Assuming the resource owner grants access, the authorization 930 server redirects the user-agent back to the client using the 931 redirection URI provided earlier. The redirection URI includes 932 the access token in the URI fragment. 933 (D) The user-agent follows the redirection instructions by making a 934 request to the web server (does not include the fragment). The 935 user-agent retains the fragment information locally. 936 (E) The web server returns a web page (typically an HTML document 937 with an embedded script) capable of accessing the full 938 redirection URI including the fragment retained by the user- 939 agent, and extracting the access token (and other parameters) 940 contained in the fragment. 941 (F) The user-agent executes the script provided by the web server 942 locally, which extracts the access token and passes it to the 943 client. 945 4.2.1. Authorization Request 947 The client constructs the request URI by adding the following 948 parameters to the query component of the authorization endpoint URI 949 using the "application/x-www-form-urlencoded" format: 951 response_type 952 REQUIRED. Value MUST be set to "token". 953 client_id 954 REQUIRED. The client identifier as described in Section 3. 955 Due to lack of client authentication, the client identifier 956 alone MUST NOT be relied upon for client identification. 957 redirect_uri 958 REQUIRED, unless a redirection URI has been established between 959 the client and authorization server via other means. Described 960 in Section 2.1.1. 961 scope 962 OPTIONAL. The scope of the access request expressed as a list 963 of space-delimited strings. The value is defined by the 964 authorization server. If the value contains multiple space- 965 delimited strings, their order does not matter, and each string 966 adds an additional access range to the requested scope. 967 state 968 OPTIONAL. An opaque value used by the client to maintain state 969 between the request and callback. The authorization server 970 includes this value when redirecting the user-agent back to the 971 client. 973 The client directs the resource owner to the constructed URI using an 974 HTTP redirection response, or by other means available to it via the 975 user-agent. 977 For example, the client directs the user-agent to make the following 978 HTTP request using transport-layer security (line breaks are for 979 display purposes only): 981 GET /authorize?response_type=token&client_id=s6BhdRkqt3& 982 redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 983 Host: server.example.com 985 The authorization server validates the request to ensure all required 986 parameters are present and valid. If the request is valid, the 987 authorization server authenticates the resource owner and obtains an 988 authorization decision (by asking the resource owner or by 989 establishing approval via other means). 991 When a decision is established, the authorization server directs the 992 user-agent to the provided client redirection URI using an HTTP 993 redirection response, or by other means available to it via the user- 994 agent. 996 4.2.2. Access Token Response 998 If the resource owner grants the access request, the authorization 999 server issues an access token and delivers it to the client by adding 1000 the following parameters to the fragment component of the redirection 1001 URI using the "application/x-www-form-urlencoded" format: 1003 access_token 1004 REQUIRED. The access token issued by the authorization server. 1005 token_type 1006 REQUIRED. The type of the token issued as described in 1007 Section 7.1. Value is case insensitive. 1008 expires_in 1009 OPTIONAL. The duration in seconds of the access token 1010 lifetime. For example, the value "3600" denotes that the 1011 access token will expire in one hour from the time the response 1012 was generated. 1013 scope 1014 OPTIONAL. The scope of the access request expressed as a list 1015 of space-delimited strings. The value is defined by the 1016 authorization server. If the value contains multiple space- 1017 delimited strings, their order does not matter, and each string 1018 adds an additional access range to the requested scope. The 1019 authorization server SHOULD include the parameter if the 1020 requested scope is different from the one requested by the 1021 client. 1023 state 1024 REQUIRED if the "state" parameter was present in the client 1025 authorization request. Set to the exact value received from 1026 the client. 1028 For example, the authorization server redirects the user-agent by 1029 sending the following HTTP response (URI line breaks are for display 1030 purposes only): 1032 HTTP/1.1 302 Found 1033 Location: http://example.com/rd#access_token=FJQbwq9& 1034 token_type=example&expires_in=3600 1036 The client SHOULD ignore unrecognized response parameters. The 1037 access token string size is left undefined by this specification. 1038 The client should avoid making assumptions about value sizes. The 1039 authorization server should document the size of any value it issues. 1041 4.2.2.1. Error Response 1043 If the request fails due to a missing, invalid, or mismatching 1044 redirection URI, or if the client identifier provided is invalid, the 1045 authorization server SHOULD inform the resource owner of the error, 1046 and MUST NOT redirect the user-agent to the invalid redirection URI. 1048 If the resource owner denies the access request or if the request 1049 fails for reasons other than a missing or invalid redirection URI, 1050 the authorization server informs the client by adding the following 1051 parameters to the fragment component of the redirection URI using the 1052 "application/x-www-form-urlencoded" format: 1054 error 1055 REQUIRED. A single error code from the following: 1056 invalid_request 1057 The request is missing a required parameter, includes an 1058 unsupported parameter or parameter value, or is otherwise 1059 malformed. 1060 unauthorized_client 1061 The client is not authorized to request an access token 1062 using this method. 1063 access_denied 1064 The resource owner or authorization server denied the 1065 request. 1067 unsupported_response_type 1068 The authorization server does not support obtaining an 1069 access token using this method. 1070 invalid_scope 1071 The requested scope is invalid, unknown, or malformed. 1072 error_description 1073 OPTIONAL. A human-readable text providing additional 1074 information, used to assist in the understanding and resolution 1075 of the error occurred. 1076 error_uri 1077 OPTIONAL. A URI identifying a human-readable web page with 1078 information about the error, used to provide the resource owner 1079 with additional information about the error. 1080 state 1081 REQUIRED if the "state" parameter was present in the client 1082 authorization request. Set to the exact value received from 1083 the client. 1085 For example, the authorization server redirects the user-agent by 1086 sending the following HTTP response: 1088 HTTP/1.1 302 Found 1089 Location: https://client.example.com/cb#error=access_denied 1091 4.3. Resource Owner Password Credentials 1093 The resource owner password credentials grant type is suitable in 1094 cases where the resource owner has a trust relationship with the 1095 client, such as its computer operating system or a highly privileged 1096 application. The authorization server should take special care when 1097 enabling the grant type, and only when other flows are not viable. 1099 The grant type is suitable for clients capable of obtaining the 1100 resource owner credentials (username and password, typically using an 1101 interactive form). It is also used to migrate existing clients using 1102 direct authentication schemes such as HTTP Basic or Digest 1103 authentication to OAuth by converting the stored credentials with an 1104 access token. 1106 +----------+ 1107 | Resource | 1108 | Owner | 1109 | | 1110 +----------+ 1111 v 1112 | 1113 (A) Password Credentials 1114 | 1115 v 1116 +---------+ +---------------+ 1117 | | Client Credentials | | 1118 | |>--(B)---- & Resource Owner ----->| | 1119 | Client | Password Credentials | Authorization | 1120 | | | Server | 1121 | |<--(C)---- Access Token ---------<| | 1122 | | (w/ Optional Refresh Token) | | 1123 +---------+ +---------------+ 1125 Figure 5: Resource Owner Password Credentials Flow 1127 The flow illustrated in Figure 5 includes the following steps: 1129 (A) The resource owner provides the client with its username and 1130 password. 1131 (B) The client requests an access token from the authorization 1132 server's token endpoint by authenticating using its client 1133 credentials, and includes the credentials received from the 1134 resource owner. 1135 (C) The authorization server validates the resource owner 1136 credentials and the client credentials and issues an access 1137 token. 1139 4.3.1. Authorization Request and Response 1141 The method through which the client obtains the resource owner 1142 credentials is beyond the scope of this specification. The client 1143 MUST discard the credentials once an access token has been obtained. 1145 4.3.2. Access Token Request 1147 The client makes a request to the token endpoint by adding the 1148 following parameter using the "application/x-www-form-urlencoded" 1149 format in the HTTP request entity-body: 1151 grant_type 1152 REQUIRED. Value MUST be set to "password". 1153 username 1154 REQUIRED. The resource owner username. 1155 password 1156 REQUIRED. The resource owner password. 1157 scope 1158 OPTIONAL. The scope of the access request expressed as a list 1159 of space-delimited strings. The value is defined by the 1160 authorization server. If the value contains multiple space- 1161 delimited strings, their order does not matter, and each string 1162 adds an additional access range to the requested scope. 1164 The client includes its authentication credentials as described in 1165 Section 3 1167 [[ add internationalization consideration for username and password 1168 ]] 1170 For example, the client makes the following HTTP request by including 1171 its client credentials via the "client_id" and "client_secret" 1172 parameters, and using transport-layer security (line breaks are for 1173 display purposes only): 1175 POST /token HTTP/1.1 1176 Host: server.example.com 1177 Content-Type: application/x-www-form-urlencoded 1179 grant_type=password&client_id=s6BhdRkqt3& 1180 client_secret=47HDu8s&username=johndoe&password=A3ddj3w 1182 The authorization server MUST: 1184 o Validate the client credentials. 1185 o Validate the resource owner password credentials. 1187 4.3.3. Access Token Response 1189 If the access token request is valid and authorized, the 1190 authorization server issues an access token and optional refresh 1191 token as described in Section 5.1. If the request failed client 1192 authentication or is invalid, the authorization server return an 1193 error response as described in Section 5.2. 1195 An example successful response: 1197 HTTP/1.1 200 OK 1198 Content-Type: application/json 1199 Cache-Control: no-store 1201 { 1202 "access_token":"SlAV32hkKG", 1203 "token_type":"example", 1204 "expires_in":3600, 1205 "refresh_token":"8xLOxBtZp8", 1206 "example_parameter":"example-value" 1207 } 1209 4.4. Client Credentials 1211 The client can request an access token using only its client 1212 credentials when the client is requesting access to the protected 1213 resources under its control, or those of another resource owner which 1214 has been previously arranged with the authorization server (the 1215 method of which is beyond the scope of this specification). 1217 +---------+ +---------------+ 1218 | | | | 1219 | |>--(A)--- Client Credentials ---->| Authorization | 1220 | Client | | Server | 1221 | |<--(B)---- Access Token ---------<| | 1222 | | (w/ Optional Refresh Token) | | 1223 +---------+ +---------------+ 1225 Figure 6: Client Credentials Flow 1227 The flow illustrated in Figure 6 includes the following steps: 1229 (A) The client requests an access token from the token endpoint by 1230 authenticating using its client credentials. 1231 (B) The authorization server validates the client credentials and 1232 issues an access token. 1234 4.4.1. Authorization Request and Response 1236 Since the client credentials are used as the authorization grant, no 1237 additional authorization request is needed as the client is already 1238 in the possession of its client credentials. 1240 4.4.2. Access Token Request 1242 The client makes a request to the token endpoint by adding the 1243 following parameter using the "application/x-www-form-urlencoded" 1244 format in the HTTP request entity-body: 1246 grant_type 1247 REQUIRED. Value MUST be set to "client_credentials". 1248 scope 1249 OPTIONAL. The scope of the access request expressed as a list 1250 of space-delimited strings. The value is defined by the 1251 authorization server. If the value contains multiple space- 1252 delimited strings, their order does not matter, and each string 1253 adds an additional access range to the requested scope. 1255 The client includes its authentication credentials as described in 1256 Section 3 1258 For example, the client makes the following HTTP request by including 1259 its client credentials via the "client_id" and "client_secret" 1260 parameters, and using transport-layer security (line breaks are for 1261 display purposes only): 1263 POST /token HTTP/1.1 1264 Host: server.example.com 1265 Content-Type: application/x-www-form-urlencoded 1267 grant_type=client_credentials&client_id=s6BhdRkqt3& 1268 client_secret=47HDu8s 1270 The authorization server MUST validate the client credentials. 1272 4.4.3. Access Token Response 1274 If the access token request is valid and authorized, the 1275 authorization server issues an access token and optional refresh 1276 token as described in Section 5.1. If the request failed client 1277 authentication or is invalid, the authorization server return an 1278 error response as described in Section 5.2. 1280 An example successful response: 1282 HTTP/1.1 200 OK 1283 Content-Type: application/json 1284 Cache-Control: no-store 1286 { 1287 "access_token":"SlAV32hkKG", 1288 "token_type":"example", 1289 "expires_in":3600, 1290 "refresh_token":"8xLOxBtZp8", 1291 "example_parameter":"example-value" 1292 } 1294 4.5. Extensions 1296 The client uses an extension grant type by specifying the grant type 1297 using an absolute URI (defined by the authorization server) as the 1298 value of the "grant_type" parameter of the token endpoint, and by 1299 adding any additional parameters necessary. 1301 For example, to request an access token using a SAML 2.0 assertion 1302 grant type as defined by [I-D.ietf-oauth-saml2-bearer], the client 1303 makes the following HTTP request using transport-layer security (line 1304 breaks are for display purposes only): 1306 POST /token HTTP/1.1 1307 Host: server.example.com 1308 Content-Type: application/x-www-form-urlencoded 1310 grant_type=http%3A%2F%2Foauth.net%2Fgrant_type%2Fassertion%2F 1311 saml%2F2.0%2Fbearer&assertion=PEFzc2VydGlvbiBJc3N1ZUluc3RhbnQ 1312 [...omitted for brevity...]V0aG5TdGF0ZW1lbnQ-PC9Bc3NlcnRpb24- 1314 5. Issuing an Access Token 1316 If the access token request is valid and authorized, the 1317 authorization server issues an access token and optional refresh 1318 token as described in Section 5.1. If the request failed client 1319 authentication or is invalid, the authorization server return an 1320 error response as described in Section 5.2. 1322 5.1. Successful Response 1324 The authorization server issues an access token and optional refresh 1325 token, and constructs the response by adding the following parameters 1326 to the entity body of the HTTP response with a 200 (OK) status code: 1328 access_token 1329 REQUIRED. The access token issued by the authorization server. 1330 token_type 1331 REQUIRED. The type of the token issued as described in 1332 Section 7.1. Value is case insensitive. 1333 expires_in 1334 OPTIONAL. The duration in seconds of the access token 1335 lifetime. For example, the value "3600" denotes that the 1336 access token will expire in one hour from the time the response 1337 was generated. 1338 refresh_token 1339 OPTIONAL. The refresh token which can be used to obtain new 1340 access tokens using the same authorization grant as described 1341 in Section 6. 1342 scope 1343 OPTIONAL. The scope of the access request expressed as a list 1344 of space-delimited strings. The value is defined by the 1345 authorization server. If the value contains multiple space- 1346 delimited strings, their order does not matter, and each string 1347 adds an additional access range to the requested scope. The 1348 authorization server SHOULD include the parameter if the 1349 requested scope is different from the one requested by the 1350 client. 1352 The parameters are included in the entity body of the HTTP response 1353 using the "application/json" media type as defined by [RFC4627]. The 1354 parameters are serialized into a JSON structure by adding each 1355 parameter at the highest structure level. Parameter names and string 1356 values are included as JSON strings. Numerical values are included 1357 as JSON numbers. 1359 The authorization server MUST include the HTTP "Cache-Control" 1360 response header field with a value of "no-store" in any response 1361 containing tokens, secrets, or other sensitive information. 1363 For example: 1365 HTTP/1.1 200 OK 1366 Content-Type: application/json 1367 Cache-Control: no-store 1369 { 1370 "access_token":"SlAV32hkKG", 1371 "token_type":"example", 1372 "expires_in":3600, 1373 "refresh_token":"8xLOxBtZp8", 1374 "example_parameter":"example-value" 1375 } 1377 The client SHOULD ignore unrecognized response parameters. The sizes 1378 of tokens and other values received from the authorization server are 1379 left undefined. The client should avoid making assumptions about 1380 value sizes. The authorization server should document the size of 1381 any value it issues. 1383 5.2. Error Response 1385 The authorization server responds with an HTTP 400 (Bad Request) 1386 status code and includes the following parameters with the response: 1388 error 1389 REQUIRED. A single error code from the following: 1390 invalid_request 1391 The request is missing a required parameter, includes an 1392 unsupported parameter or parameter value, repeats a 1393 parameter, includes multiple credentials, utilizes more 1394 than one mechanism for authenticating the client, or is 1395 otherwise malformed. 1396 invalid_client 1397 Client authentication failed (e.g. unknown client, no 1398 client credentials included, multiple client credentials 1399 included, or unsupported credentials type). The 1400 authorization server MAY return an HTTP 401 1401 (Unauthorized) status code to indicate which HTTP 1402 authentication schemes are supported. If the client 1403 attempted to authenticate via the "Authorization" request 1404 header field, the authorization server MUST respond with 1405 an HTTP 401 (Unauthorized) status code, and include the 1406 "WWW-Authenticate" response header field matching the 1407 authentication scheme used by the client. 1409 invalid_grant 1410 The provided authorization grant is invalid, expired, 1411 revoked, or does not match the redirection URI used in 1412 the authorization request. 1413 unauthorized_client 1414 The authenticated client is not authorized to use this 1415 authorization grant type. 1416 unsupported_grant_type 1417 The authorization grant type is not supported by the 1418 authorization server. 1419 invalid_scope 1420 The requested scope is invalid, unknown, malformed, or 1421 exceeds the previously granted scope. 1422 error_description 1423 OPTIONAL. A human-readable text providing additional 1424 information, used to assist in the understanding and resolution 1425 of the error occurred. 1426 error_uri 1427 OPTIONAL. A URI identifying a human-readable web page with 1428 information about the error, used to provide the resource owner 1429 with additional information about the error. 1431 The parameters are included in the entity body of the HTTP response 1432 using the "application/json" media type as defined by [RFC4627]. The 1433 parameters are serialized into a JSON structure by adding each 1434 parameter at the highest structure level. Parameter names and string 1435 values are included as JSON strings. Numerical values are included 1436 as JSON numbers. 1438 For example: 1440 HTTP/1.1 400 Bad Request 1441 Content-Type: application/json 1442 Cache-Control: no-store 1444 { 1445 "error":"invalid_request" 1446 } 1448 6. Refreshing an Access Token 1450 The client makes a request to the token endpoint by adding the 1451 following parameter using the "application/x-www-form-urlencoded" 1452 format in the HTTP request entity-body: 1454 grant_type 1455 REQUIRED. Value MUST be set to "refresh_token". 1456 refresh_token 1457 REQUIRED. The refresh token issued along the access token 1458 being refreshed. 1459 scope 1460 OPTIONAL. The scope of the access request expressed as a list 1461 of space-delimited strings. The value is defined by the 1462 authorization server. If the value contains multiple space- 1463 delimited strings, their order does not matter, and each string 1464 adds an additional access range to the requested scope. The 1465 requested scope MUST be equal or lesser than the scope 1466 originally granted by the resource owner, and if omitted is 1467 treated as equal to the previously approved scope. 1469 The client includes its authentication credentials as described in 1470 Section 3 1472 For example, the client makes the following HTTP request by including 1473 its client credentials via the "client_id" and "client_secret" 1474 parameters, and using transport-layer security (line breaks are for 1475 display purposes only): 1477 POST /token HTTP/1.1 1478 Host: server.example.com 1479 Content-Type: application/x-www-form-urlencoded 1481 grant_type=refresh_token&client_id=s6BhdRkqt3& 1482 client_secret=8eSEIpnqmM&refresh_token=n4E9O119d 1484 The authorization server MUST validate the client credentials, the 1485 refresh token, and verify that the resource owner's authorization is 1486 still valid. If valid and authorized, the authorization server 1487 issues an access token as described in Section 5.1. If the request 1488 failed verification or is invalid, the authorization server return an 1489 error response as described in Section 5.2. 1491 The authorization server MAY issue a new refresh token, in which 1492 case, the client MUST discard the old refresh token and replace it 1493 with the new refresh token. 1495 7. Accessing Protected Resources 1497 The client accesses protected resources by presenting the access 1498 token to the resource server. The resource server MUST validate the 1499 access token and ensure it has not expired and that its scope covers 1500 the requested resource. The methods used by the resource server to 1501 validate the access token are beyond the scope of this specification, 1502 but generally involve an interaction or coordination between the 1503 resource server and the authorization server. 1505 The method in which the client utilized the access token to 1506 authenticate with the resource server depends on the type of access 1507 token issued by the authorization server. Typically, it involves 1508 using the HTTP "Authorization" request header field with an 1509 authentication scheme defined by the access token type specification. 1511 7.1. Access Token Types 1513 The access token type provides the client with the information 1514 required to successfully utilize the access token to make a protected 1515 resource request (along with type-specific attributes). 1517 For example, the "bearer" token type defined in 1518 [I-D.ietf-oauth-v2-bearer] is utilized by simply including the access 1519 token string in the request: 1521 GET /resource/1 HTTP/1.1 1522 Host: example.com 1523 Authorization: BEARER h480djs93hd8 1525 while the "mac" token type defined in [I-D.hammer-oauth-v2-mac-token] 1526 is utilized by issuing a token secret together with the access token 1527 which is used to sign certain components of the HTTP requests: 1529 GET /resource/1 HTTP/1.1 1530 Host: example.com 1531 Authorization: MAC token="h480djs93hd8", 1532 timestamp="137131200", 1533 nonce="dj83hs9s", 1534 signature="kDZvddkndxvhGRXZhvuDjEWhGeE=" 1536 Each access token type definition specifies the additional attributes 1537 (if any) sent to the client together with the "access_token" response 1538 parameter. It also defines the HTTP authentication method used to 1539 include the access token when making a protected resource request. 1541 8. Extensibility 1543 8.1. Defining Access Token Types 1545 Access token types can be defined in one of two ways: registered in 1546 the access token type registry (following the procedures in 1547 Section 10.1), or use a unique absolute URI as its name. 1549 Types utilizing a URI name SHOULD be limited to vendor-specific 1550 implementations that are not commonly applicable, and are specific to 1551 the implementation details of the resource server where they are 1552 used. 1554 All other types MUST be registered. Type names MUST conform to the 1555 type-name ABNF. If the type definition includes a new HTTP 1556 authentication scheme, the type name SHOULD be identical to the HTTP 1557 authentication scheme name (as defined by [RFC2617]). 1559 type-name = 1*name-char 1560 name-char = "-" / "." / "_" / DIGIT / ALPHA 1562 8.2. Defining New Endpoint Parameters 1564 New request or response parameters for use with the authorization 1565 endpoint or the token endpoint are defined and registered in the 1566 parameters registry following the procedure in Section 10.2. 1568 Parameter names MUST conform to the param-name ABNF, MUST NOT use the 1569 "x_" parameter name prefix, and parameter values syntax MUST be well- 1570 defined (e.g., using ABNF, or a reference to the syntax of an 1571 existing parameter). 1573 param-name = 1*name-char 1574 name-char = "-" / "." / "_" / DIGIT / ALPHA 1576 Vendor-specific parameter extensions that are not commonly 1577 applicable, and are specific to the implementation details of the 1578 authorization server where they are used SHOULD utilize the "x_" 1579 parameter name prefix if they are not registered. 1581 8.3. Defining New Authorization Grant Types 1583 New authorization grant types can be defined by assigning them a 1584 unique absolute URI for use with the "grant_type" parameter. If the 1585 extension grant type requires additional token endpoint parameters, 1586 they MUST be registered in the OAuth parameters registry as described 1587 by Section 10.2. 1589 9. Security Considerations 1591 [[ TBD ]] 1593 10. IANA Considerations 1595 10.1. The OAuth Access Token Type Registry 1597 This specification establishes the OAuth access token type registry. 1599 Access token types are registered on the advice of one or more 1600 Designated Experts (appointed by the IESG or their delegate), with a 1601 Specification Required (using terminology from [RFC5226]). However, 1602 to allow for the allocation of values prior to publication, the 1603 Designated Expert(s) may approve registration once they are satisfied 1604 that such a specification will be published. 1606 Registration requests should be sent to the [TBD]@ietf.org mailing 1607 list for review and comment, with an appropriate subject (e.g., 1608 "Request for access toke type: example"). [[ Note to RFC-EDITOR: The 1609 name of the mailing list should be determined in consultation with 1610 the IESG and IANA. Suggested name: oauth-ext-review. ]] 1612 Before a period of 14 days has passed, the Designated Expert(s) will 1613 either approve or deny the registration request, communicating this 1614 decision both to the review list and to IANA. Denials should include 1615 an explanation and, if applicable, suggestions as to how to make the 1616 request successful. Registration requests that are undetermined for 1617 a period longer than 21 days can be brought to the IESG's attention 1618 (using the iesg@iesg.org mailing list) for resolution. 1620 10.1.1. Registration Template 1622 Type name: 1623 The name requested (e.g., "example"). 1624 Additional Token Endpoint Response Parameters: 1625 Additional response parameters returned together with the 1626 "access_token" parameter. New parameters MUST be separately 1627 registered in the OAuth parameters registry as described by 1628 Section 10.2. 1630 HTTP Authentication Scheme(s): 1631 The HTTP authentication scheme name(s), if any, used to 1632 authenticate protected resources requests using access token of 1633 this type. 1634 Change controller: 1635 For standards-track RFCs, state "IETF". For others, give the name 1636 of the responsible party. Other details (e.g., postal address, 1637 e-mail address, home page URI) may also be included. 1638 Specification document(s): 1639 Reference to document that specifies the parameter, preferably 1640 including a URI that can be used to retrieve a copy of the 1641 document. An indication of the relevant sections may also be 1642 included, but is not required. 1644 10.2. The OAuth Parameters Registry 1646 This specification establishes the OAuth parameters registry. 1648 Additional parameters for inclusion in the authorization endpoint 1649 request, the authorization endpoint response, the token endpoint 1650 request, or the token endpoint response, are registered on the advice 1651 of one or more Designated Experts (appointed by the IESG or their 1652 delegate), with a Specification Required (using terminology from 1653 [RFC5226]). However, to allow for the allocation of values prior to 1654 publication, the Designated Expert(s) may approve registration once 1655 they are satisfied that such a specification will be published. 1657 Registration requests should be sent to the [TBD]@ietf.org mailing 1658 list for review and comment, with an appropriate subject (e.g., 1659 "Request for parameter: example"). [[ Note to RFC-EDITOR: The name of 1660 the mailing list should be determined in consultation with the IESG 1661 and IANA. Suggested name: oauth-ext-review. ]] 1663 Before a period of 14 days has passed, the Designated Expert(s) will 1664 either approve or deny the registration request, communicating this 1665 decision both to the review list and to IANA. Denials should include 1666 an explanation and, if applicable, suggestions as to how to make the 1667 request successful. Registration requests that are undetermined for 1668 a period longer than 21 days can be brought to the IESG's attention 1669 (using the iesg@iesg.org mailing list) for resolution. 1671 10.2.1. Registration Template 1673 Parameter name: 1674 The name requested (e.g., "example"). 1676 Parameter usage location: 1677 The location(s) where parameter can be used. The possible 1678 locations are: authorization request, authorization response, 1679 token request, or token response. 1680 Change controller: 1681 For standards-track RFCs, state "IETF". For others, give the name 1682 of the responsible party. Other details (e.g., postal address, 1683 e-mail address, home page URI) may also be included. 1684 Specification document(s): 1685 Reference to document that specifies the parameter, preferably 1686 including a URI that can be used to retrieve a copy of the 1687 document. An indication of the relevant sections may also be 1688 included, but is not required. 1690 10.2.2. Initial Registry Contents 1692 The OAuth Parameters Registry's initial contents are: 1694 o Parameter name: client_id 1695 o Parameter usage location: authorization request, token request 1696 o Change controller: IETF 1697 o Specification document(s): [[ this document ]] 1699 o Parameter name: client_secret 1700 o Parameter usage location: token request 1701 o Change controller: IETF 1702 o Specification document(s): [[ this document ]] 1704 o Parameter name: response_type 1705 o Parameter usage location: authorization request 1706 o Change controller: IETF 1707 o Specification document(s): [[ this document ]] 1709 o Parameter name: redirect_uri 1710 o Parameter usage location: authorization request, token request 1711 o Change controller: IETF 1712 o Specification document(s): [[ this document ]] 1714 o Parameter name: scope 1715 o Parameter usage location: authorization request, authorization 1716 response, token request, token response 1717 o Change controller: IETF 1718 o Specification document(s): [[ this document ]] 1720 o Parameter name: state 1721 o Parameter usage location: authorization request, authorization 1722 response 1724 o Change controller: IETF 1725 o Specification document(s): [[ this document ]] 1727 o Parameter name: code 1728 o Parameter usage location: authorization response, token request 1729 o Change controller: IETF 1730 o Specification document(s): [[ this document ]] 1732 o Parameter name: error_description 1733 o Parameter usage location: authorization response, token response 1734 o Change controller: IETF 1735 o Specification document(s): [[ this document ]] 1737 o Parameter name: error_uri 1738 o Parameter usage location: authorization response, token response 1739 o Change controller: IETF 1740 o Specification document(s): [[ this document ]] 1742 o Parameter name: grant_type 1743 o Parameter usage location: token request 1744 o Change controller: IETF 1745 o Specification document(s): [[ this document ]] 1747 o Parameter name: access_token 1748 o Parameter usage location: authorization response, token response 1749 o Change controller: IETF 1750 o Specification document(s): [[ this document ]] 1752 o Parameter name: token_type 1753 o Parameter usage location: authorization response, token response 1754 o Change controller: IETF 1755 o Specification document(s): [[ this document ]] 1757 o Parameter name: expires_in 1758 o Parameter usage location: authorization response, token response 1759 o Change controller: IETF 1760 o Specification document(s): [[ this document ]] 1762 o Parameter name: username 1763 o Parameter usage location: token request 1764 o Change controller: IETF 1765 o Specification document(s): [[ this document ]] 1767 o Parameter name: password 1768 o Parameter usage location: token request 1769 o Change controller: IETF 1770 o Specification document(s): [[ this document ]] 1772 o Parameter name: refresh_token 1773 o Parameter usage location: token request, token response 1774 o Change controller: IETF 1775 o Specification document(s): [[ this document ]] 1777 Appendix A. Contributors 1779 The following people contributed to preliminary versions of this 1780 document: Blaine Cook (BT), Brian Eaton (Google), Yaron Goland 1781 (Microsoft), Brent Goldman (Facebook), Raffi Krikorian (Twitter), 1782 Luke Shepard (Facebook), and Allen Tom (Yahoo!). The content and 1783 concepts within are a product of the OAuth community, WRAP community, 1784 and the OAuth Working Group. 1786 The OAuth Working Group has dozens of very active contributors who 1787 proposed ideas and wording for this document, including: 1789 Michael Adams, Andrew Arnott, Dirk Balfanz, Brian Campbell, Leah 1790 Culver, Bill de hOra, Brian Ellin, Igor Faynberg, George Fletcher, 1791 Tim Freeman, Evan Gilbert, Kristoffer Gronowski, Justin Hart, Phil 1792 Hunt, Michael B. Jones, John Kemp, Mark Kent, Chasen Le Hara, Rasmus 1793 Lerdorf, Torsten Lodderstedt, Alastair Mair, Eve Maler, James Manger, 1794 Laurence Miao, Chuck Mortimore, Justin Richer, Peter Saint-Andre, Nat 1795 Sakimura, Rob Sayre, Marius Scurtescu, Naitik Shah, Justin Smith, 1796 Jeremy Suriel, Christian Stuebner, Paul Tarjan, Franklin Tse, Nick 1797 Walker, Skylar Woodward. 1799 Appendix B. Acknowledgements 1801 [[ Add OAuth 1.0a authors + WG contributors ]] 1803 Appendix C. Document History 1805 [[ to be removed by RFC editor before publication as an RFC ]] 1807 -13 1809 o Small editorial changes. 1810 o Split introduction 'Roles' into 'Roles' and 'Protocol Flow'. 1811 o Changes section name 'Requesting an Access Token' to 'Obtaining 1812 Authorization'. 1814 o Added explicit authorization request and access token response 1815 sub-sections for each grant type. 1816 o Added document overview in the introduction. 1817 o Reduced the use of 'x_' prefix to SHOULD. 1818 o Removed unused references and updated others. 1819 o Dropped 'invalid_client' error from authorization endpoint 1820 responses. 1822 11. References 1824 11.1. Normative References 1826 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1827 Requirement Levels", BCP 14, RFC 2119, March 1997. 1829 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 1830 Leach, P., Luotonen, A., and L. Stewart, "HTTP 1831 Authentication: Basic and Digest Access Authentication", 1832 RFC 2617, June 1999. 1834 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1835 Resource Identifier (URI): Generic Syntax", STD 66, 1836 RFC 3986, January 2005. 1838 [RFC4627] Crockford, D., "The application/json Media Type for 1839 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1841 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1842 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 1843 May 2008. 1845 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 1846 Specifications: ABNF", STD 68, RFC 5234, January 2008. 1848 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1849 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1851 [W3C.REC-html401-19991224] 1852 Hors, A., Raggett, D., and I. Jacobs, "HTML 4.01 1853 Specification", World Wide Web Consortium 1854 Recommendation REC-html401-19991224, December 1999, 1855 . 1857 11.2. Informative References 1859 [I-D.hammer-oauth-v2-mac-token] 1860 Hammer-Lahav, E., "HTTP Authentication: MAC 1861 Authentication", draft-hammer-oauth-v2-mac-token-02 (work 1862 in progress), January 2011. 1864 [I-D.ietf-oauth-saml2-bearer] 1865 Campbell, B. and C. Mortimore, "SAML 2.0 Bearer Assertion 1866 Grant Type Profile for OAuth 2.0", 1867 draft-ietf-oauth-saml2-bearer-03 (work in progress), 1868 February 2011. 1870 [I-D.ietf-oauth-v2-bearer] 1871 Jones, M., Hardt, D., and D. Recordon, "The OAuth 2.0 1872 Protocol: Bearer Tokens", draft-ietf-oauth-v2-bearer-02 1873 (work in progress), January 2011. 1875 [OASIS.saml-core-2.0-os] 1876 Cantor, S., Kemp, J., Philpott, R., and E. Maler, 1877 "Assertions and Protocol for the OASIS Security Assertion 1878 Markup Language (SAML) V2.0", OASIS Standard saml-core- 1879 2.0-os, March 2005. 1881 Authors' Addresses 1883 Eran Hammer-Lahav (editor) 1884 Yahoo! 1886 Email: eran@hueniverse.com 1887 URI: http://hueniverse.com 1889 David Recordon 1890 Facebook 1892 Email: dr@fb.com 1893 URI: http://www.davidrecordon.com/ 1895 Dick Hardt 1896 Microsoft 1898 Email: dick.hardt@gmail.com 1899 URI: http://dickhardt.org/