Network Working Group D. Recordon, Ed. Internet-Draft Facebook Intended status: Informational E. Hammer-Lahav, Ed. Expires: September 2, 2010 A. Tom Yahoo! B. Goldman L. Shepard Facebook R. Krikorian Twitter Mar 2010 OAuth 2.0 DRAFT draft-recordon-oauth2-01 Abstract OAuth 2.0 provides a method for an application (client) to access the Protected Resource hosted on a server on behalf of a resource owner (such as a different client or an end-user). It provides a process for users to authorize third-party access to their protected resources via a variety of authorization flows. These flows generally do not include having to share their credentials (typically, a username and password pair). A server can additionally delegate authorization to one or more authorities (authorization server) which issue access tokens to clients. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at Recordon, et al. Expires September 2, 2010 [Page 1] Internet-Draft OAuth 2.0 DRAFT Mar 2010 http://www.ietf.org/shadow.html. This Internet-Draft will expire on September 2, 2010. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the BSD License. Recordon, et al. Expires September 2, 2010 [Page 2] Internet-Draft OAuth 2.0 DRAFT Mar 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . 4 1.2. Changes from WRAP . . . . . . . . . . . . . . . . . . . . 4 1.3. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 1.3.1. Endpoints . . . . . . . . . . . . . . . . . . . . . . 6 1.4. Notational Conventions . . . . . . . . . . . . . . . . . . 7 2. Getting an Access Token . . . . . . . . . . . . . . . . . . . 7 2.1. Web Server Flow . . . . . . . . . . . . . . . . . . . . . 7 2.2. Web Client Flow . . . . . . . . . . . . . . . . . . . . . 11 2.3. Device Flow . . . . . . . . . . . . . . . . . . . . . . . 14 2.4. Username and Password Flow . . . . . . . . . . . . . . . . 17 2.5. Client Identifier and Secret Flow . . . . . . . . . . . . 19 3. Refreshing an Access Token . . . . . . . . . . . . . . . . . . 21 4. Accessing a Protected Resource . . . . . . . . . . . . . . . . 23 4.1. Using TLS/SSL solely with an access token . . . . . . . . 23 4.1.1. Client Calls Protected Resource Using HTTP Header . . 23 4.1.2. Client Calls Protected Resource Using URL Query Parameter . . . . . . . . . . . . . . . . . . . . . . 24 4.1.3. Client Calls Protected Resource Using Body Parameter . . . . . . . . . . . . . . . . . . . . . . 25 4.2. Using Signatures . . . . . . . . . . . . . . . . . . . . . 25 4.2.1. Computing the signature . . . . . . . . . . . . . . . 27 4.2.2. Client Calls Protected Resource Using HTTP Headers . . 28 4.2.3. Client Calls Protected Resource Using URL Query Parameters . . . . . . . . . . . . . . . . . . . . . . 29 4.2.4. Client Calls Protected Resource Using Body Parameters . . . . . . . . . . . . . . . . . . . . . . 29 5. Security Considerations . . . . . . . . . . . . . . . . . . . 30 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.1. Normative References . . . . . . . . . . . . . . . . . . . 30 6.2. Informative References . . . . . . . . . . . . . . . . . . 31 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 Recordon, et al. Expires September 2, 2010 [Page 3] Internet-Draft OAuth 2.0 DRAFT Mar 2010 1. Introduction This specification consists of two major parts: Getting an Access Token (Section 2) and Accessing a Protected Resource (Section 4). The first part defines multiple authorization flows describing how a client may obtain an access token when acting autonomously or on behalf of an end-user. They involve resource owners authorizing client access to their resources, by authenticating directly with the server and provisioning tokens to the client for use with the authentication method. The second part defines a method for making authenticated HTTP requests using access tokens either protected via TLS/SSL or by using an access token combined with an access token secret. The access token both identifies the client making the request as well as the resource owner on whose behalf the request is being made. The use of OAuth with any other transport protocol than HTTP [RFC2616] is undefined. TODO: This section should provide a longer description of the protocol flows and the evolution from OAuth 1.0. Both OAuth 1.0 and WRAP contain fairly complete introductory sections. I think that the WRAP one is a bit too long and we should shoot for this section being a little over two pages (including terminology). 1.1. Acknowledgements This (early) draft was written pretty quickly and is heavily based on The OAuth 1.0 Protocol [draft-hammer-oauth-10], OAuth WRAP [draft-hardt-oauth-01] and further discussion on the IETF OAuth Working Group mailing list [1]. Those authors and editors include Allen Tom (Yahoo!), Brian Eaton (Google), Dick Hardt, Eran Hammer- Lahav (Yahoo!) and Yaron Goland (Microsoft). To provide feedback on this draft join the OAuth Working Group: http://www.ietf.org/dyn/wg/charter/oauth-charter.html. 1.2. Changes from WRAP The following are highlighted changes from [draft-hardt-oauth-01]: 1. A Web Client flow designed for use within JavaScript. It also supports the use cases of the rich app profile so that they're not two separate flows. 2. A new device flows which is based on the Netflix/Tivo flow (TV shows you a code that you type in on your computer). http://www.ietf.org/mail-archive/web/oauth/current/msg01346.html Recordon, et al. Expires September 2, 2010 [Page 4] Internet-Draft OAuth 2.0 DRAFT Mar 2010 3. Remove captchas from the username/password flow. They haven't been successfully implemented within this context and create complexity especially when we use other signals to detect compromised accounts. http://www.ietf.org/mail-archive/web/oauth/current/msg01293.html 4. Don't allow bearer tokens without either SSL and/or signatures. While some providers may offer this ability, they should be out of spec for doing so though technically it won't break the flows. 5. Abstract the refresh token flow out of each profile into its own section. Support the ability to request access token secrets when refreshing. 6. Support signatures for making API requests but not for getting access tokens. If you want to use signatures, you'll get an access token and then make a refresh call where you ask for a token secret. This causes the auth server to mark the token as no longer being valid as a bearer token via SSL. This performance tradeoff seems realistic given many use cases focus on high-volume API transactions and thus the one additional request at the onset should be noise. The signature mechanism is currently from OAuth 1.0. 1.3. Terminology access token An unique identifier issued by the authorization server and used by the client to make authenticated requests on behalf of the user whose authorization has been obtained by the client. When making protected resource requests, the access token is either a bearer token presented over SSL/TLS and/or accompanied by an additional secret when using a signature mechanism. access token secret A string issued by the authorization server and used by the client to establish ownership of the access token when using a signature mechanism to access a protected resource. authorization server A HTTP server (per [RFC2616]) that issues access tokens to clients after successful authorization. May be the same entity as the server hosting protected resources. client An HTTP client (per [RFC2616]) capable of making OAuth- authenticated requests for protected resources. client identifier An unique identifier issued by the authorization server and used used by the client to identify itself to the authorization server. Recordon, et al. Expires September 2, 2010 [Page 5] Internet-Draft OAuth 2.0 DRAFT Mar 2010 client secret A string issued by the authorization server and used by the client to establish ownership of the client identifier. protected resource An access-restricted resource which can be obtained from a HTTP server (per [RFC2616]) using an OAuth- authenticated request. May be the same entity as the authorization server. refresh token An unique long lived bearer token used by a client to acquire access tokens from an authorization server. resource owner An entity (generally an end-user) who can authenticate to the authorization server such that it issues the client an access token. 1.3.1. Endpoints The authorization server advertises (such as via documentation) the URIs of the following three endpoints: access token request The authorization server endpoint used by the client to obtain an access token via a HTTP "POST" request using one of the authorization flows (Section 2) or by refreshing an access token (Section 3). API request The protected resource endpoint used by the client to make OAuth-authenticated requests (Section 4). user authorization request The authorization server endpoint where the client sends the resource owners's user-agent via a HTTP "GET" request to make an authorization decision using one of the authorization flows (Section 2). The three URIs advertised by the server MAY include a query component as defined by [RFC3986] section 3, but if present, the query MUST NOT contain any parameters beginning with the "oauth_" prefix, to avoid conflicts with the protocol parameters added to the URIs when used. The methods in which the servers advertise and document its three endpoints are beyond the scope of this specification. Clients should avoid making assumptions about the size of tokens and other server- generated values, which are left undefined by this specification. However it is strongly RECOMMENDED that authorization servers make their identifiers, secrets, and tokens not over 255 characters in length in order to ease client implementations. In addition, protocol parameters MAY include values which require encoding when transmitted. All identifiers, secrets, tokens, and codes MUST use URL safe characters and not require further encoding. Clients and Recordon, et al. Expires September 2, 2010 [Page 6] Internet-Draft OAuth 2.0 DRAFT Mar 2010 servers should not make other assumptions about the possible range of their values. 1.4. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Getting an Access Token This specification defines five core authorization flows which are used by a client to request an access token from authorization servers. An authorization server MUST implement at least one of the following flows. Common scenarios involve the resource owner delegating to a client to act on their behalf, adding another party (the resource owner) to the protocol. In these flows, the client receives a refresh token when it acquires the first access token. When an access token expires, the client presents the refresh token to acquire a new access token. Refresh tokens are sensitive as they represent long-lived permissions to access a Protected Resource and are always transmitted using HTTPS. Unlike the others, Client Identifier and Secret flow (Section 2.5) is intended for a client acting on behalf of itself and not a separate resource owner. For example, when a client is accessing non-private data or modifying data about itself. 2.1. Web Server Flow This flow is suitable when the client is a web application calling the protected resource on behalf of a resource owner. It enables clients to act on behalf of resource owners without acquiring an end- user's credentials. Prior to making a request using this flow, the client MUST have obtained a client identifier and user authorization request endpoint URI from the authorization server. The authorization server MAY require the client to pre-register their callback URI. The client MUST first send the resource owners's user-agent to the authorization server's user authorization request endpoint. The client constructs the request URI by adding the following REQUIRED query parameters to the user authorization endpoint URI: Recordon, et al. Expires September 2, 2010 [Page 7] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_mode The parameter value MUST be set to "flow_web_server" (case sensitive). oauth_client_identifier The client identifier. oauth_callback_url An absolute URI to which the authorization server will redirect the resource owner back when the resource owner authorization step is completed. The client MAY also include the following OPTIONAL parameters: oauth_client_state An opaque value that clients can use to maintain state associated with this request. oauth_scope If the authorization server has defined a manner for the client to request certain capabilities of the access token, this parameter SHOULD be used to do so. The client directs the resource owner to the constructed URI using an HTTP redirection response, or by other means available to it via the resource owner's user-agent. The request MUST use the HTTP "GET" method. For example, the client directs the resource owner's user-agent to make the following HTTPS requests: GET /user_authorization?oauth_mode=flow_web_server&oauth_client_identifier=s6BhdRkqt3&oauth_callback_url=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 Host: server.example.com The way in which the server handles the user authorization request (such as via cookies), including whether it uses a secure channel such as TLS/SSL is beyond the scope of this specification. However, the server MUST first verify the identity of the resource owner. If the resource owner approves the authorization request, the authorization server MUST generate a verification code and associate it with the client identifier and callback URI. After receiving an authorization decision from the resource owner, the server redirects the resource owner to the callback URI if one was provided in the "oauth_callback" parameter or pre-registered by other means. The authorization server constructs the request URI by adding one of the two following REQUIRED parameters to the callback URI query component depending on if the resource owner approved (oauth_verification_code) or declined (oauth_error_reason) the authorization request: Recordon, et al. Expires September 2, 2010 [Page 8] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_verification_code The verification code. oauth_error_reason The parameter value MUST be set to "user_denied" (case sensitive). The authorization server MAY also include the following parameters: oauth_client_state REQUIRED if the client sent the parameter in its request. If the callback URI already includes a query component as defined by [RFC3986] section 3, the server MUST append the OAuth parameters to the end of the existing query. The callback URI's query component MUST NOT contain any parameters beginning with the "oauth_" prefix. For example, the server redirects the resource owner's user-agent: HTTP/1.1 302 Found Location: https://client.example.com/cb?oauth_verification_code=i1WsRn1uB1 Continuing the example, this results in the resource owner's user- agent making the following HTTPS "GET" request: GET /cb?oauth_verification_code=i1WsRn1uB1 HTTP/1.1 Host: client.example.com GET /cb?oauth_error_reason=user_denied HTTP/1.1 Host: client.example.com If the client receives a verification code, it constructs an HTTP "POST" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "flow_web_app" (case sensitive). oauth_client_identifier The client identifier. oauth_client_secret The client secret. oauth_verification_code The verification code. oauth_callback_url The callback URI from the user authorization request. Since the request results in the transmission of plain text credentials in the HTTP request and response, the authorization Recordon, et al. Expires September 2, 2010 [Page 9] Internet-Draft OAuth 2.0 DRAFT Mar 2010 server MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: POST /access_token HTTP/1.1 Host: server.example.com oauth_client_identifier=s6BhdRkqt3&oauth_client_secret=gX1fBat3bV&oauth_verification_code=i1WsRn1uB1&oauth_callback_url=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb If the request is authorized, the access token is included in the HTTP response body using the "application/x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 200 status code (OK). The response contains the following REQUIRED parameter: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_refresh_token The refresh token. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=SlAV32hkKG&oauth_refresh_token=8xLOxBtZp8 The server must retain the scope, duration, and other attributes approved by the resource owner, and enforce these restrictions when receiving a client request made with the tokens issued. Once the client receives and stores the token credentials, it can proceed to access protected resources on behalf of the resource owner by making authenticated requests (Section 4) using the access token received. If the authorization server is unable to issue an access token to the client, the HTTP response body uses the "application/ x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 401 status code (Unauthorized). The response contains the following OPTIONAL parameter: Recordon, et al. Expires September 2, 2010 [Page 10] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_error_reason Value must be one of "callback_url_mismatch" or "expired_verification_code" (case sensitive). For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" oauth_error_reason=expired_verification_code 2.2. Web Client Flow The Web Client Flow is similar to the Web Server Flow (Section 2.1), but it has different security characteristics. Client-side applications are those that live entirely in JavaScript, on the desktop, a mobile device, or in other environments where the code does not have easy access to a server. These applications have the ability to display a web page to the user, but cannot receive the response on a server. Because the entirety of the client is downloaded to the resource owner's user-agent, it is not possible to completely protect the client secret. This flow allows for authorization while taking those security considerations into account. Because there is no client secret to ensure authenticity, both the client and authorization server should take some extra precautions when using this flow. Specifically, as the access token flows directly to the user-agent, it should only be used when it is acceptable for the end-user to have direct access to the access token. Additionally, care should be taken to choose a good callback URL, as described below. Prior to making a request using this flow, the client MUST have obtained a client identifier and user authorization request endpoint URI from the authorization server. The authorization server SHOULD require the client to pre-register their callback URI. The client MUST first send the resource owners's user-agent to the authorization server's user authorization request endpoint. The client constructs the request URI by adding the following REQUIRED query parameters to the user authorization endpoint URI: oauth_mode The parameter value MUST be set to "flow_web_client" (case sensitive). Recordon, et al. Expires September 2, 2010 [Page 11] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_client_identifier The client identifier. oauth_callback_url An absolute URI to which the authorization server will redirect the resource owner back when the authorization step is completed. The client MUST make use of at least one of either a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections) for the callback URI or including a fragment identifier ("#") as defined by [RFC3986] section 3.5 in the URI to prevent transmission of plain text credentials. The client MAY also include the following OPTIONAL parameters: oauth_client_state An opaque value that clients can use to maintain state associated with this request. oauth_scope If the authorization server has defined a manner for the client to request certain capabilities of the access token, this parameter SHOULD be used to do so. The client directs the resource owner to the constructed URI using an HTTP redirection response, or by other means available to it via the resource owner's user-agent. The request MUST use the HTTP "GET" method. For example, the client directs the resource owner's user-agent to make one of the following HTTPS requests: GET /user_authorization?oauth_mode=flow_web_client&oauth_client_identifier=s6BhdRkqt3&oauth_callback_url=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1 Host: server.example.com GET /user_authorization?oauth_mode=flow_web_client&oauth_client_identifier=s6BhdRkqt3&oauth_callback_url=http%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb# HTTP/1.1 Host: server.example.com The way in which the server handles the user authorization request (such as via cookies), including whether it uses a secure channel such as TLS/SSL is beyond the scope of this specification. However, the server MUST first verify the identity of the resource owner. If the Client has previously registered a callback URI with the authorization server, it SHOULD verify that the callback URI provided in the "oauth_callback" parameter is valid given the pre-registered URI. After receiving an authorization decision from the resource owner, the server redirects the resource owner to the callback URI. The authorization server constructs the request URI by adding the Recordon, et al. Expires September 2, 2010 [Page 12] Internet-Draft OAuth 2.0 DRAFT Mar 2010 following REQUIRED parameter to the callback URI query component: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_refresh_token The refresh token. If the callback URI already includes a query component as defined by [RFC3986] section 3, the server MUST append the OAuth parameters to the end of the existing query. If the callback URI includes a fragment (#), then the OAuth parameters MUST be appended to the end of the query, after the fragment. The callback URI's query component MUST NOT contain any parameters beginning with the "oauth_" prefix. For example, the server redirects the resource owner's user-agent: HTTP/1.1 302 Found Location: https://client.example.com/cb?oauth_access_token=FJQbwq9OD8&oauth_expires=10800 HTTP/1.1 302 Found Location: http://client.example.com/cb#?oauth_access_token=FJQbwq9OD8&oauth_expires=10800 Continuing the example, this results in the resource owner's user- agent to make the following HTTPS/HTTP "GET" request: GET /cb?oauth_access_token=FJQbwq9OD8&oauth_expires=10800 HTTP/1.1 Host: client.example.com GET /cb#?oauth_access_token=FJQbwq9OD8&oauth_expires=10800 HTTP/1.1 Host: client.example.com The server must retain the scope, duration, and other attributes approved by the resource owner, and enforce these restrictions when receiving a client request made with the tokens issued. Once the client receives and stores the token credentials, it can proceed to access protected resources on behalf of the resource owner by making authenticated requests (Section 4) using the access token received. If the request fails verification, the authorization server SHOULD respond with the appropriate HTTP response status code. The authorization server MAY include further details about why the Recordon, et al. Expires September 2, 2010 [Page 13] Internet-Draft OAuth 2.0 DRAFT Mar 2010 request was rejected in the response body. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" 2.3. Device Flow The Device Flow is suitable when the client is a device which does not have an easy data-entry method (e.g. game consoles or entertainment centers), but where the end-user has access to a separate computer with simple data-entry methods (e.g. their home computer, a laptop or a smartphone). Prior to making a request using this flow, the client MUST have obtained a client identifier and access token request endpoint URI from the authorization server. The client constructs an HTTP "GET" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "flow_device" (case sensitive). oauth_client_identifier The client identifier. The client MAY also include the following OPTIONAL parameters as well as any additional parameters as defined by the authorization server: oauth_scope If the authorization server has defined a manner for the client to request certain capabilities of the access token, this parameter SHOULD be used to do so. Since the request results in the transmission of temporary plain text credentials in the HTTP response, the authorization server MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: GET /access_token?oauth_client_identifier=s6BhdRkqt3&oauth_mode=flow_device HTTP/1.1 Host: server.example.com Upon receiving an authorization request by the client, the authorization server generates a device verification code and a user verification code. These are included in the HTTP response body using the "application/x-www-form-urlencoded" content type as defined Recordon, et al. Expires September 2, 2010 [Page 14] Internet-Draft OAuth 2.0 DRAFT Mar 2010 by [W3C.REC-html40-19980424] with a 200 status code (OK). The response contains the following REQUIRED parameters: oauth_device_code The device verification code. oauth_user_code The user verification code. oauth_verification_url The user verification URL on the authorization server. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the two verification codes in seconds. oauth_verification_rate_limit The minimum amount of time in seconds that the client SHOULD wait between polling requests to the device authorization URL. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_device_code=74tq5miHKB&oauth_user_code=94248&oauth_verification_url=http%3A%2F%2Fwww%2Eexample%2Ecom%2Fdevice&oauth_verification_rate_limit=3 The client MUST display the user verification URL and the user verification code to the end-user, instruct them to visit the user verification URL in a web browser, and to enter the user verification token upon doing so (a user authorization request). The way in which the authorization server handles the user authorization request, including whether it uses a secure channel such as TLS/SSL is beyond the scope of this specification. However, the server MUST first verify the identity of the resource owner. After doing so, the server MUST prompt the end-user to enter the user verification code. The authorization server MUST verify that the user verification code is valid and MAY verify that the client is authorized to use this flow. If the request is authorized, the authorization server directs the end-user to go back to the client device and follow its instructions. The client MAY have an interface element (such as a button) that the end-user interacts with to communicate that they have finished the authorization process. The client MAY initiate the following request at an arbitrary but reasonable interval in order to create a more responsive user experience though MUST NOT exceed the verification Recordon, et al. Expires September 2, 2010 [Page 15] Internet-Draft OAuth 2.0 DRAFT Mar 2010 rate limit if one is specified. The Client MAY both poll and have an interface element, but MUST NOT have neither. The client constructs an HTTP "GET" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "flow_device" (case sensitive). oauth_client_identifier The client identifier. oauth_device_verification_code The device verification code. Since the request results in the transmission of plain text credentials in the HTTP response, the authorization server MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: GET /access_token?oauth_client_identifier=s6BhdRkqt3&oauth_device_verification_code=J2vC42OifV HTTP/1.1 Host: server.example.com If the request is authorized, the access token is included in the HTTP response body using the "application/x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 200 status code (OK). The response contains the following REQUIRED parameter: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_refresh_token The refresh token. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=FJQbwq9OD8&oauth_expires=600 The server must retain the scope, duration, and other attributes approved by the resource owner, and enforce these restrictions when receiving a client request made with the tokens issued. Recordon, et al. Expires September 2, 2010 [Page 16] Internet-Draft OAuth 2.0 DRAFT Mar 2010 Once the client receives and stores the token credentials, it can proceed to access protected resources on behalf of the resource owner by making authenticated requests (Section 4) using the access token received. If the authorization server is unable to issue an access token to the client, the HTTP response body uses the "application/ x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 401 status code (Unauthorized). The response contains the following REQUIRED parameter: oauth_error_reason Value must be one of "authorization_declined", "authorization_pending", "slow_down", or "verification_code_expired" (case sensitive). For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" oauth_error_reason=authorization_pending 2.4. Username and Password Flow This flow is used when the authorization server generally trusts the client to temporarily collect the end-user's username and password and it is impossible to use one of the other authorization flows. This flow enables a client to act on behalf of the resource owner without having to permanently store their username and password. Prior to making a request using this flow, the client MUST have obtained a client identifier, client secret, and access token request endpoint URI from the authorization server. How the client prompts the resource owner for their username and password is beyond the scope of this specification. The client MUST discard the resource owner's username and password once an access token has been obtained. The client constructs an HTTP "POST" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "flow_username_password" (case sensitive). oauth_client_identifier The client identifier. Recordon, et al. Expires September 2, 2010 [Page 17] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_username The resource owner's username. oauth_password The resource owner's password. The client MAY also include the following OPTIONAL parameters as well as any additional parameters as defined by the authorization server: oauth_scope If the authorization server has defined a manner for the client to request certain capabilities of the access token, this parameter SHOULD be used to do so. Since the request results in the transmission of plain text credentials in both the HTTP request and response, the authorization server MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: POST /access_token HTTP/1.1 Host: server.example.com oauth_client_identifier=s6BhdRkqt3&oauth_client_secret=8eSEIpnqmM&oauth_username=daveman692&oauth_password=1password The authorization server MUST verify that the resource owner's credentials are accurate and MAY verify that the client is authorized to use this flow. If the request is authorized, the access token is included in the HTTP response body using the "application/ x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 200 status code (OK). The response contains the following REQUIRED parameter: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_refresh_token The refresh token. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=FJQbwq9OD8&oauth_refresh_token=gO3CHNqpH8 The server must retain the scope, duration, and other attributes approved by the resource owner, and enforce these restrictions when Recordon, et al. Expires September 2, 2010 [Page 18] Internet-Draft OAuth 2.0 DRAFT Mar 2010 receiving a client request made with the tokens issued. Once the client receives and stores the token credentials, it can proceed to access protected resources on behalf of the resource owner by making authenticated requests (Section 4) using the access token received. If the request fails verification, the authorization server SHOULD respond with the appropriate HTTP response status code. The authorization server MAY include further details about why the request was rejected in the response body. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" 2.5. Client Identifier and Secret Flow This flow is suitable when the client is also the resource owner and thus not accessing protected resources within the context of a given end-user. For example, when a client is accessing non-private data or modifying data about itself. This flow SHOULD NOT be used when the client is acting on behalf of an end-user. Prior to making a request using this flow, the client MUST have obtained a client identifier, client secret, and access token request endpoint URI from the authorization server. The client constructs an HTTP "POST" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "flow_client" (case sensitive). oauth_client_identifier The client identifier. oauth_client_secret The client secret. The client MAY also include the following OPTIONAL parameters: oauth_scope If the authorization server has defined a manner for the client to request certain capabilities of the access token, this parameter SHOULD be used to do so. Since the request results in the transmission of plain text credentials in both the HTTP request and response, the authorization server MUST require the use of a transport-layer mechanism such as Recordon, et al. Expires September 2, 2010 [Page 19] Internet-Draft OAuth 2.0 DRAFT Mar 2010 TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: POST /access_token HTTP/1.1 Host: server.example.com oauth_client_identifier=s6BhdRkqt3&oauth_client_secret=8eSEIpnqmM The authorization server MUST verify that the resource owner has authorized the provisioning of an access token to the client. If the request is authorized, the access token is included in the HTTP response body using the "application/x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 200 status code (OK). The response contains the following REQUIRED parameter: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_refresh_token The refresh token. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=FJQbwq9OD8&oauth_refresh_token=gO3CHNqpH8 The server must retain the scope, duration, and other attributes approved by the resource owner, and enforce these restrictions when receiving a client request made with the tokens issued. Once the client receives and stores the token credentials, it can proceed to access protected resources on behalf of the resource owner by making authenticated requests (Section 4) using the access token received. If the request fails verification, the authorization server SHOULD respond with the appropriate HTTP response status code. The authorization server MAY include further details about why the request was rejected in the response body. For example: Recordon, et al. Expires September 2, 2010 [Page 20] Internet-Draft OAuth 2.0 DRAFT Mar 2010 HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" 3. Refreshing an Access Token Authorization servers MAY issue access tokens that expire and thus require clients to refresh them. A client determines that an access token needs refreshing either by using the access token's expiration information or upon receiving the HTTP 401 Unauthorized response when accessing protected resources per Section 4. A client will also refresh a token if it wishes to obtain a corresponding access token secret for use when accessing protected resources via signatures (Section 4.2). Prior to making a request using this flow, the client MUST have obtained a client identifier, client secret, and access token request endpoint URI from the authorization server. The client constructs an HTTP "POST" request to the access token request endpoint and includes the following REQUIRED parameters: oauth_mode The parameter value MUST be set to "refresh_token" (case sensitive). oauth_client_identifier The client identifier. oauth_client_secret The client secret. oauth_refresh_token The refresh token associated with the access token to be refreshed. If the client wishes to obtain an access token for use when accessing protected resources via signatures, the following parameters MUST also be added to the request: oauth_want_secret The parameter value MUST be set to "true" (case sensitive). Since the request results in the transmission of plain text credentials in both the HTTP request and response, the authorization server MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: POST /refresh_token HTTP/1.1 Host: server.example.com Recordon, et al. Expires September 2, 2010 [Page 21] Internet-Draft OAuth 2.0 DRAFT Mar 2010 oauth_client_identifier=s6BhdRkqt3&oauth_client_secret=8eSEIpnqmM&oauth_refresh_token=n4E9O119d The authorization server MUST verify that the resource owner has still authorized the provisioning of an access token to the client and that the refresh token is valid. If the request is authorized, the access token is included in the HTTP response body using the "application/x-www-form-urlencoded" content type as defined by [W3C.REC-html40-19980424] with a 200 status code (OK). If an access token secret is included in the response, the protected resource MUST NOT allow the use of the corresponding access token without its secret (Section 4.1). The response contains the following REQUIRED parameters: oauth_access_token The access token. The authorization server MAY also include the following parameters: oauth_expires The lifetime of the access token in seconds. oauth_access_token_secret A corresponding access token secret if the client requested one. oauth_signature_methods A comma-separated list of signature methods supported by the protected resource. REQUIRED if an access token secret is being returned. Possible values include "HMAC-SHA1" and "HMAC-SHA256" (case-sensitive) as well as any other values defined by extensions to this protocol. For example: HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=8F44J2HGMl HTTP/1.1 200 OK Content-Type: application/x-www-form-urlencoded oauth_access_token=8F44J2HGMl&oauth_access_token_secret=h3B2Tw1CHw&oauth_signature_methods=HMAC-SHA1,HMAC-SHA256 If the request fails verification, the authorization server SHOULD respond with the appropriate HTTP response status code. The authorization server MAY include further details about why the request was rejected in the response body. Recordon, et al. Expires September 2, 2010 [Page 22] Internet-Draft OAuth 2.0 DRAFT Mar 2010 For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="example" 4. Accessing a Protected Resource OAuth 2.0 supports the ability for clients to make protected resource requests by using TLS/SSL (Section 4.1) and/or by signing their HTTP request with shared secrets (Section 4.2). Protected resources MUST support clients making authenticated requests via TLS/SSL (Section 4.1) and MAY choose to also support signatures (Section 4.2). It is RECOMMENDED that clients make authenticated requests via TLS/SSL. If a client includes more than one access token within the request, the protected resource MUST respond with a HTTP 400 "Bad Request" error code. 4.1. Using TLS/SSL solely with an access token When using TLS/SSL, clients MUST present an access token to authenticate to a protected resource. Use of the HTTP "Authorization" header field as defined by [RFC2617] is RECOMMENDED, since HTTP implementations are aware that this header has special security properties and may require special treatment in caches and logs. Protected resources SHOULD take precautions to ensure that access tokens are not inadvertently logged or captured. It is RECOMMENDED that clients verify the authenticity of the certificate provided when establishing a TLS/SSL connection to the protected resource. 4.1.1. Client Calls Protected Resource Using HTTP Header The protected resource SHOULD allow clients to make authenticated requests by including the access token in the HTTP "Authorization" header. Prior to making a request, the client MUST have obtained a valid access token and the API request endpoint URI. The client constructs a HTTP request to the API request endpoint URI and includes the HTTP "Authorization" header field with the auth- scheme name set to "OAuth" (case-insensitive). Since the request results in the transmission of plain text credentials in the HTTP request, the protected resource MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). Recordon, et al. Expires September 2, 2010 [Page 23] Internet-Draft OAuth 2.0 DRAFT Mar 2010 For example, the client makes the following HTTPS request: GET /user/daveman692.json HTTP/1.1 Host: api.example.com Authorization: OAuth oauth_access_token="vF9dft4qmT" Note that per [RFC2617] section 1.2 the following request is also valid: GET /user/daveman692.json HTTP/1.1 Host: api.example.com Authorization: OAuth oauth_access_token = vF9dft4qmT If the request fails verification, the protected resource SHOULD respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body or headers. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="https://api.example.com/" 4.1.2. Client Calls Protected Resource Using URL Query Parameter The protected resource MAY allow clients to make authenticated requests by including the access token as a URL query parameter. Prior to making a request, the client MUST have obtained a valid access token and the API request endpoint URI. While the following examples use the HTTP "GET" method, there's nothing limiting a client to use query parameters with other HTTP methods. The client constructs the request URI by adding the following REQUIRED query parameter to the API request endpoint: oauth_access_token The access token. Since the request results in the transmission of plain text credentials in the HTTP request, the protected resource MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: GET /user/daveman692.json?oauth_access_token=vF9dft4qmT HTTP/1.1 Host: api.example.com If the request fails verification, the protected resource SHOULD Recordon, et al. Expires September 2, 2010 [Page 24] Internet-Draft OAuth 2.0 DRAFT Mar 2010 respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="https://api.example.com/" 4.1.3. Client Calls Protected Resource Using Body Parameter The protected resource MAY allow clients to make authenticated requests by including the access token as a parameter in the body of a HTTP request. Prior to making a request, the client MUST have obtained a valid access token and the API request endpoint URI. The client constructs an HTTP "POST", "PUT", or "DELETE" request to the API request endpoint and includes the following REQUIRED parameter: oauth_access_token The access token. Since the request results in the transmission of plain text credentials in the HTTP request, the protected resource MUST require the use of a transport-layer mechanism such as TLS or SSL (or a secure channel with equivalent protections). For example, the client makes the following HTTPS request: POST /blog/entry HTTP/1.1 Host: api.example.com oauth_access_token=vF9dft4qmT If the request fails verification, the protected resource SHOULD respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="https://api.example.com/" 4.2. Using Signatures When using signatures, clients MAY use TLS/SSL as the transport to authenticate to a protected resource. Use of the "Authorization" header field is RECOMMENDED, as HTTP implementations are aware that Recordon, et al. Expires September 2, 2010 [Page 25] Internet-Draft OAuth 2.0 DRAFT Mar 2010 this header has special security properties and may require special treatment in caches and logs. Editor's note: This draft bases it's signature mechanism off of the OAuth 1.0 Protocol [draft-hammer-oauth-10] and it's possible that parts of the mechanism will change in future drafts. The following parameters are obtained (or computed) by clients in order to make protected resource requests: oauth_access_token The access token obtained through a refresh token call with the "oauth_want_secret" parameter included (Section 3). oauth_signature_method The signature method used by the client to sign the request. The method MUST be one of those listed in the "oauth_signature_methods" parameter returned with the access token secret (Section 3). oauth_timestamp Unless otherwise specified by the server's documentation, the timestamp is expressed in the number of seconds since January 1, 1970 00:00:00 GMT. It MUST be a positive integer. oauth_nonce A nonce is a random string, uniquely generated by the client to allow the server to verify that a request has never been made before and helps prevent replay attacks when requests are made over a non-secure channel. The nonce value MUST be unique across all requests with the same timestamp and token combinations. oauth_signature The computed signature value ensuring the integrity of this request (Section 4.2.1). The protocol parameters are added to the request using one of the three transmission methods: HTTP Headers (Section 4.2.2), HTTP query parameters (Section 4.2.3), or HTTP body parameters (Section 4.2.4). Construction of the signature base string follows the process detailed in section 3.4.1 of [draft-hammer-oauth-10]. For example the request: Recordon, et al. Expires September 2, 2010 [Page 26] Internet-Draft OAuth 2.0 DRAFT Mar 2010 GET /user/daveman692.json?b5=%3D%25%3D&a3=a&c%40=&a2=r%20b HTTP/1.1 Host: api.example.com Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_access_token="vF9dft4qmT", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1268998408", oauth_nonce="7d8f3e4a", c2&a3=2+q Is represented by the following signature base string: GET&http%3A%2F%2Fapi.example.com%2Fuser%2Fdaveman692.json& a2%3Dr%2520b%26a3%3D2%252Bq%26a3%3Da%26b5%3D%253D%2525%253D%26c% 2540%3D%26c2%3D%26oauth_nonce%3D7d8f3e4a%26oauth_signature_method% 3DHMAC- SHA1%26oauth_timestamp%3D1268998408%26oauth_access_token% 3DvF9dft4qmT%26oauth_version%3D2.0 4.2.1. Computing the signature The authorization server declares which signature methods it accepts via the "oauth_signature_methods" returned as part of obtaining an access token secret (Section 3). The client declares which signature method is used for this request via the "oauth_signature_method" parameter. It then generates a signature, and includes it in the "oauth_signature" parameter. The server verifies the signature as specified for each method. There is no mandate for a particular signature method as each implementation can have its own unique requirements. Authorization servers are free to implement and document their own custom methods. 4.2.1.1. HMAC-SHA1 The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104]: digest = HMAC-SHA1 (key, text) The HMAC-SHA1 function variables are used in following way: text is set to the value of the signature base string. Recordon, et al. Expires September 2, 2010 [Page 27] Internet-Draft OAuth 2.0 DRAFT Mar 2010 key is set to the concatenated values of: 1. The client secret, after being encoded (TODO: ref) 2. An "&" character (ASCII code 38), which MUST be included even when either secret is empty. 3. The access token secret, after being encoded (TODO: ref). digest is used to set the value of the "oauth_signature" protocol parameter, after the result octet string is base64-encoded per section 6.8 of [RFC2045]. 4.2.2. Client Calls Protected Resource Using HTTP Headers The protected resource MAY allow clients to make authenticated requests by including the access token in the HTTP "Authorization" header. Prior to making a request, the client MUST have obtained a valid access token, a valid access token secret, and the API request endpoint URI. It MUST have also constructed the signature base string and computed the signature (Section 4.2.1). The client constructs a HTTP request to the API request endpoint URI and includes the HTTP "Authorization" header field with the auth- scheme name set to "OAuth" (case-insensitive). The protocol parameters and the signature computed in Section 4.2.1 are included in the Authorization header. For example, a valid request follows the form of: GET /user/daveman692.json?b5=%3D%25%3D&a3=a&c%40=&a2=r%20b HTTP/1.1 Host: api.example.com Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_access_token="vF9dft4qmT", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1268998408", oauth_nonce="7d8f3e4a", oauth_signature="hfVFpKvoKp5S6YaNIJ6ljuNYR6s%3D" c2&a3=2+q If the request fails verification, the protected resource SHOULD respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body or headers. For example: Recordon, et al. Expires September 2, 2010 [Page 28] Internet-Draft OAuth 2.0 DRAFT Mar 2010 HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="http://api.example.com/" 4.2.3. Client Calls Protected Resource Using URL Query Parameters The protected resource MAY allow clients to make authenticated requests by including the access token as a URL query parameter. Prior to making a request, the client MUST have obtained a valid access token, a valid access token secret, and the API request endpoint URI. It MUST have also constructed the signature base string and computed the signature (Section 4.2.1). While the following examples use the HTTP "GET" method, there's nothing limiting a client to use query parameters with other HTTP methods. The client constructs the request URI by adding the protocol parameters and the signature computed in Section 4.2.1. For example, the client makes the following HTTP request: GET /user/daveman692.json?oauth_access_token=vF9dft4qmT&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1268998408&oauth_nonce=7d8f3e4a&oauth_signature=hfVFpKvoKp5S6YaNIJ6ljuNYR6s%3D Host: api.example.com If the request fails verification, the protected resource SHOULD respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body or headers. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="http://api.example.com/" 4.2.4. Client Calls Protected Resource Using Body Parameters The protected resource MAY allow clients to make authenticated requests by including the access token as a parameter in the body of a HTTP "POST" request. Prior to making a request, the client MUST have obtained a valid access token, a valid access token secret, and the API request endpoint URI. It MUST have also constructed the signature base string and computed the signature (Section 4.2.1). The client constructs a HTTP "POST" request to the API request endpoint and includes the protocol parameters and the signature computed in Section 4.2.1. For example, the client makes the following HTTP request: Recordon, et al. Expires September 2, 2010 [Page 29] Internet-Draft OAuth 2.0 DRAFT Mar 2010 GET /user/daveman692.json Host: api.example.com oauth_access_token=vF9dft4qmT&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1268998408&oauth_nonce=7d8f3e4a&oauth_signature=hfVFpKvoKp5S6YaNIJ6ljuNYR6s%3D If the request fails verification, the protected resource SHOULD respond with the appropriate HTTP response status code. The protected resource MAY include further details about why the request was rejected in the response body or headers. For example: HTTP/1.1 401 Authorization Required WWW-Authenticate: OAuth realm="http://api.example.com/" 5. Security Considerations TODO: David is the wrong person to write this section. Should definitely cover why device profiles don't have client secrets (hard to trust them to keep secrets and will probably use custom ways to auth based on the device and if it has TPM.) 6. References 6.1. Normative References [RFC2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045. [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- Hashing for Message Authentication", RFC 2104. [RFC2119] Bradner, B., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, Recordon, et al. Expires September 2, 2010 [Page 30] Internet-Draft OAuth 2.0 DRAFT Mar 2010 RFC 3986. [W3C.REC-html40-19980424] Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., "HTML 4.0 Specification", W3C REC-html40-19980424. 6.2. Informative References [draft-hammer-oauth-10] Hammer-Lahav, E., Ed., "The OAuth 1.0 Protocol". [draft-hardt-oauth-01] Eaton, B., Goland, Y., Hardt, D., Ed., and A. Tom, "OAuth Web Resource Authorization Profiles". URIs [1] Authors' Addresses David Recordon (editor) Facebook Email: davidrecordon@facebook.com Eran Hammer-Lahav (editor) Email: eran@hueniverse.com Allen Tom Yahoo! Email: atom@yahoo-inc.com Brent Goldman Facebook Email: brent@facebook.com Recordon, et al. Expires September 2, 2010 [Page 31] Internet-Draft OAuth 2.0 DRAFT Mar 2010 Luke Shepard Facebook Email: lshepard@facebook.com Raffi Krikorian Twitter Email: raffi@twitter.com Recordon, et al. Expires September 2, 2010 [Page 32]