[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[OAUTH-WG] First draft of OAuth 2.0

From: David Recordon <davidrecordon at facebook.com>
To: OAuth WG <oauth at ietf.org>
Date: Fri, 19 Mar 2010 18:28:45 -0700

As I mentioned a few weeks ago [1], I started working on editing the first draft of OAuth 2.0 over the past two weeks. While I realize that it's 6pm Friday (sorry about that), I hope to have a solid discussion about it at Monday's meeting. You can find the current draft of it – plus all of the document history – on my public GitHub account a thttp://github.com/daveman692/OAuth-2.0. Eran will be doing an initial editing pass before Monday and then spend more time with it next week.

I've attached both a HTML and TXT copy to this email and plan to officially submit it as an Internet Draft.

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
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.

Obviously I couldn't have made so much progress so quickly if it weren't for WRAP and I hope that 2.0 both addresses the WRAP use cases as well as those we all have been discussing here. I hope that I haven't missed anyone who contributed to prior work and am happy to add other authors if I have (and they wish to be added)!

Thanks,
--David

[1] http://www.ietf.org/mail-archive/web/oauth/current/msg01225.html

Title: OAuth 2.0 DRAFT

TOC

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 http://www.ietf.org/shadow.html.

This Internet-Draft will expire on September 2, 2010.

Copyright Notice

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

1. Introduction
    1.1. Acknowledgements
    1.2. Changes from WRAP
    1.3. Terminology
        1.3.1. Endpoints
    1.4. Notational Conventions
2. Getting an Access Token
    2.1. Web Server Flow
    2.2. Web Client Flow
    2.3. Device Flow
    2.4. Username and Password Flow
    2.5. Client Identifier and Secret Flow
3. Refreshing an Access Token
4. Accessing a Protected Resource
    4.1. Using TLS/SSL solely with an access token
        4.1.1. Client Calls Protected Resource Using HTTP Header
        4.1.2. Client Calls Protected Resource Using URL Query Parameter
        4.1.3. Client Calls Protected Resource Using Body Parameter
    4.2. Using Signatures
        4.2.1. Computing the signature
        4.2.2. Client Calls Protected Resource Using HTTP Headers
        4.2.3. Client Calls Protected Resource Using URL Query Parameters
        4.2.4. Client Calls Protected Resource Using Body Parameters
5. Security Considerations
6. References
    6.1. Normative References
    6.2. Informative References
§ Authors' Addresses

TOC

1. Introduction

This specification consists of two major parts: Getting an Access Token (Getting an Access Token) and Accessing a Protected Resource (Accessing a Protected Resource). 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 (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .) [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).

TOC

1.1. Acknowledgements

This (early) draft was written pretty quickly and is heavily based on The OAuth 1.0 Protocol (Hammer-Lahav, E., Ed., “The OAuth 1.0 Protocol,” .) [draft‑hammer‑oauth‑10], OAuth WRAP (Eaton, B., Goland, Y., Hardt, D., Ed., and A. Tom, “OAuth Web Resource Authorization Profiles,” .) [draft‑hardt‑oauth‑01] and further discussion on the IETF OAuth Working Group mailing list. 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.

TOC

1.2. Changes from WRAP

The following are highlighted changes from [draft‑hardt‑oauth‑01] (Eaton, B., Goland, Y., Hardt, D., Ed., and A. Tom, “OAuth Web Resource Authorization Profiles,” .):

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.
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
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
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.
Abstract the refresh token flow out of each profile into its own section. Support the ability to request access token secrets when refreshing.
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.

TOC

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] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .)) 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] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .)) 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.

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] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .)) 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.

TOC

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 (Getting an Access Token)) or by refreshing an access token (Section 3 (Refreshing an Access Token)).

API request

The protected resource endpoint used by the client to make OAuth-authenticated requests (Section 4 (Accessing a Protected Resource)).

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 (Getting an Access Token)).

The three URIs advertised by the server MAY include a query component as defined by [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” .) 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 servers should not make other assumptions about the possible range of their values.

TOC

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] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” .).

TOC

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 (Client Identifier and Secret Flow) 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.

TOC

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:

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:

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] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” .) 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 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] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) 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 (Accessing a Protected Resource)) 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] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) with a 401 status code (Unauthorized). The response contains the following OPTIONAL parameter:

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

TOC

2.2. Web Client Flow

The Web Client Flow is similar to the Web Server Flow (Web Server Flow), 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.

oauth_mode

The parameter value MUST be set to "flow_web_client" (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 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] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” .) 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.

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

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 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] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” .) 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.

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"

TOC

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 by [W3C.REC‑html40‑19980424] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) 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 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

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.

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

TOC

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.

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] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) 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.

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="example"

TOC

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.

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] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) 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.

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="example"

TOC

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 (Accessing a Protected Resource). 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 (Using Signatures)).

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).

For example, the client makes the following HTTPS request:

POST /refresh_token HTTP/1.1
Host: server.example.com
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] (Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” .) 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 (Using TLS/SSL solely with an access token)).

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

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="example"

TOC

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 (Using TLS/SSL solely with an access token)) and/or by signing their HTTP request with shared secrets (Section 4.2 (Using Signatures)). Protected resources MUST support clients making authenticated requests via TLS/SSL (Section 4.1 (Using TLS/SSL solely with an access token)) and MAY choose to also support signatures (Section 4.2 (Using Signatures)). 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.

TOC

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] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” .) 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.

TOC

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).

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] (Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” .) 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/"

TOC

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.

For example, the client makes the following HTTPS request:

    GET /user/daveman692.json?oauth_access_token=vF9dft4qmT HTTP/1.1
    Host: api.example.com

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="https://api.example.com/"

TOC

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.

For example, the client makes the following HTTPS request:

    POST /blog/entry HTTP/1.1
    Host: api.example.com
    oauth_access_token=vF9dft4qmT

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="https://api.example.com/"

TOC

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 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 (Hammer-Lahav, E., Ed., “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 (Refreshing an Access Token)).

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 (Refreshing an Access Token)).

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 (Computing the signature)).

The protocol parameters are added to the request using one of the three transmission methods: HTTP Headers (Client Calls Protected Resource Using HTTP Headers), HTTP query parameters (Client Calls Protected Resource Using URL Query Parameters), or HTTP body parameters (Client Calls Protected Resource Using Body Parameters).

Construction of the signature base string follows the process detailed in section 3.4.1 of [draft‑hammer‑oauth‑10] (Hammer-Lahav, E., Ed., “The OAuth 1.0 Protocol,” .).

For example the request:

    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

TOC

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 (Refreshing an Access Token)). 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.

TOC

4.2.1.1. HMAC-SHA1

The "HMAC-SHA1" signature method uses the HMAC-SHA1 signature algorithm as defined in [RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .):

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.

key

is set to the concatenated values of:

The client secret, after being encoded (TODO: ref)

An "&" character (ASCII code 38), which MUST be included even when either secret is empty.

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] (Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” .).

TOC

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 (Computing the signature).

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 (Computing the signature) 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

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="http://api.example.com/"

TOC

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 (Computing the signature). 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 (Computing the signature).

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

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="http://api.example.com/"

TOC

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 (Computing the signature).

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 (Computing the signature).

For example, the client makes the following HTTP request:

    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

For example:

    HTTP/1.1 401 Authorization Required
    WWW-Authenticate: OAuth realm="http://api.example.com/"

TOC

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.)

TOC

6. References

TOC

6.1. Normative References

[RFC2045]	Freed, N. and N. Borenstein, “Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies,” RFC 2045 (TXT).
[RFC2104]	Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” RFC 2104 (TXT).
[RFC2119]	Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119 (TXT, HTML).
[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 (TXT, HTML).
[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 (TXT, HTML).
[RFC3986]	Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986 (TXT, HTML).
[W3C.REC-html40-19980424]	Ragget, D., Ed., Le Hors, A., Ed., and I. Jacobs, Ed., “HTML 4.0 Specification,” W3C REC-html40-19980424.

TOC

6.2. Informative References

[draft-hammer-oauth-10]	Hammer-Lahav, E., Ed., “The OAuth 1.0 Protocol” (TXT, HTML).
[draft-hardt-oauth-01]	Eaton, B., Goland, Y., Hardt, D., Ed., and A. Tom, “OAuth Web Resource Authorization Profiles.”

TOC

Authors' Addresses

	David Recordon (editor)
	Facebook
Email:	davidrecordon at facebook.com

	Eran Hammer-Lahav (editor)
Email:	eran at hueniverse.com

	Allen Tom
	Yahoo!
Email:	atom at yahoo-inc.com

	Brent Goldman
	Facebook
Email:	brent at facebook.com

	Luke Shepard
	Facebook
Email:	lshepard at facebook.com

	Raffi Krikorian
	Twitter
Email:	raffi at twitter.com

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.

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

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

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

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:

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] <https://www.ietf.org/mailman/listinfo/oauth>

Authors' Addresses

David Recordon (editor)
Facebook

Email: davidrecordon at facebook.com

Eran Hammer-Lahav (editor)

Email: eran at hueniverse.com

Allen Tom
Yahoo!

Email: atom at yahoo-inc.com

Brent Goldman
Facebook

Email: brent at facebook.com

Recordon, et al. Expires September 2, 2010 [Page 31]

Internet-Draft OAuth 2.0 DRAFT Mar 2010

Luke Shepard
Facebook

Email: lshepard at facebook.com

Raffi Krikorian
Twitter

Email: raffi at twitter.com

Recordon, et al. Expires September 2, 2010 [Page 32]

Follow-Ups:
- Re: [OAUTH-WG] First draft of OAuth 2.0
  - From: Torsten Lodderstedt
- Re: [OAUTH-WG] First draft of OAuth 2.0
  - From: Chuck Mortimore
- [OAUTH-WG] OAuth 2.0: client_secret, state
  - From: Manger, James H
- Re: [OAUTH-WG] First draft of OAuth 2.0
  - From: Eve Maler

Prev by Date: Re: [OAUTH-WG] Understanding how OpenSocial uses OAuth 1.0a
Next by Date: Re: [OAUTH-WG] Defining a maximum token length?
Previous by thread: [OAUTH-WG] updated Anaheim agenda
Next by thread: Re: [OAUTH-WG] First draft of OAuth 2.0
Index(es):
- Date
- Thread

Note Well: Messages sent to this mailing list are the opinions of the senders and do not imply endorsement by the IETF.

[OAUTH-WG] First draft of OAuth 2.0

OAuth 2.0 DRAFTdraft-recordon-oauth2-01

Abstract

Status of this Memo

Copyright Notice

Table of Contents

1. Introduction

1.1. Acknowledgements

1.2. Changes from WRAP

1.3. Terminology

1.3.1. Endpoints

1.4. Notational Conventions

2. Getting an Access Token

2.1. Web Server Flow

2.2. Web Client Flow

2.3. Device Flow

2.4. Username and Password Flow

2.5. Client Identifier and Secret Flow

3. Refreshing an Access Token

4. Accessing a Protected Resource

4.1. Using TLS/SSL solely with an access token

4.1.1. Client Calls Protected Resource Using HTTP Header

4.1.2. Client Calls Protected Resource Using URL Query Parameter

4.1.3. Client Calls Protected Resource Using Body Parameter

4.2. Using Signatures

4.2.1. Computing the signature

4.2.1.1. HMAC-SHA1

4.2.2. Client Calls Protected Resource Using HTTP Headers

4.2.3. Client Calls Protected Resource Using URL Query Parameters

4.2.4. Client Calls Protected Resource Using Body Parameters

5. Security Considerations

6. References

6.1. Normative References

6.2. Informative References

Authors' Addresses

OAuth 2.0 DRAFT
draft-recordon-oauth2-01