How to Use Three-Legged OAuth

You want to know how to implement three-legged OAuth protocol.

Figure 12.1 shows the role of the OAuth protocol. At the start of the protocol, the server uses a “consumer key” as an identifier for the client and a“ consumer secret” as a shared secret. Once a user authorizes the client to access her resources, the server uses an “access token” as an identifier uses the authorized client and uses a “token secret” as a shared secret.

Figure 12.1. Role of the three-legged OAuth flow

OAuth relies on three sets of tokens and secrets issued by the server to the client:

Using three-legged OAuth involves the following steps. The purpose of this flow is to obtain an access token and a secret. The server may grant the access token for a particular period of time and/or to limit access to certain user resources.

Note that since OAuth is a protocol layered on top of HTTP, servers need to document the following URIs to clients:

OAuth recommends using POST to obtain request and access tokens.

Consider the photo album web service introduced in the section called “How to Copy a Resource”. The client needs the user’s authorization for it to be able to make a copy of a user’s photo album resource. The client approaches the server to obtain an oauth_consumer_key and a secret through some out-of-band means. For example, the server may provide a web page for clients to register and obtain the consumer key and consumer secret. Assume that the server assigns a1191fd420e0164c2f9aeac32ed35d23 as the consumer key and, as the shared secret, fd9b9d0f769c3bcc548496e4b5077da79c02d7be.

For the client to initiate the three-legged protocol, the server documents the following URIs:

These requests involve the following parameters:

The first step for the client is to submit a request to obtain a request token and a secret from the server. The signature in this request is based on the consumer secret that the client obtained along with the consumer key. The signature includes oauth_consumer_key, oauth_signature_method, oauth_timestamp, oauth_nonce, and oauth_version and must be computed as follows:

Using this signature, the consumer sends a request to obtain a request token.

# Request to obtain a request token

POST /request_token HTTP/1.1 [1]

Host: www.example.org

Authorization: OAuth realm="http://www.example.com/photos",

 	oauth_consumer_key=a1191fd420e0164c2f9aeac32ed35d23,

 	oauth_nonce=109843dea839120a,

 	oauth_signature=d8e19bb988110380a72f6ca33b2ba5903272fe1,

 	oauth_signature_method=HMAC-SHA1,

 	oauth_timestamp=1258308730,

 	oauth_version=1.0 [2]

Content-Length: 0



# Response containing a request token and a secret

HTTP/1.1 200 OK

Content-Type: application/x-www-form-urlencoded



oauth_token=0e713d524f290676de8aff4073b1bb52e37f065c

 &oauth_token_secret=394bc633d4c93f79aa0539fd554937760f05987c [3]

	

The oauth_token in this response is a request token that the client must use in order to get the user’s permission. The client directs the user to visit a resource on the server to grant authorization.

# Request to obtain authorization

GET /oauth/authorize?oauth_token=0e713d524f290676de8aff4073b1bb52e37f065c HTTP/1.1

Host: www.example.org

The implementation of this resource is up to the server. At this point, the server will need to check whether the user is authenticated with the server. The server may allow the user to select the parts of data that the client can access and the nature of the access. For instance, the user may grant the client permission to edit an album or create a new album but not delete any album or photos. After this step, the server directs the user back to the client. If the client has a web-based user interface, the server may redirect the user to that interface via a callback URI. If not, the server will ask the user to manually enter a verification code in the client’s user interface. With either approach, the client obtains a verification code from the server.

The client uses the verification code to obtain an access token. The signature in this request is based on oauth_consumer_key, the request token, the verification code, oauth_signature_method, oauth_timestamp, oauth_nonce, and oauth_version.

# Request to obtain an access token

POST /access_token HTTP/1.1 [1]

Host: www.example.org

Authorization: OAuth oauth_consumer_key="a1191fd420e0164c2f9aeac32ed35d23",

 	oauth_token="ad0d1c7a765c9e6e8b14e639c763177312d18e7e",

 	oauth_verifier="988786765423",

 	oauth_signature_method="RSA-SHA1",

 	oauth_signature="698d58fd3316304181e11c6eb8127ffea7e2df46",

 	oauth_timestamp="1258328458",

 	oauth_nonce="109843dea839120a",

 	oauth_version="1.0" [2]

Content-Length: 0



HTTP/1.1 200 OK

Content-Type: application/x-www-form-urlencoded



oauth_token=8d743f1165c7030177040ec70f16df8bc6f415c7

 &oauth_token_secret=95aec3132c167ec2df818770dfbdbd0a8b2e105e [3]

	

This response contains an access token and a secret. The server must verify that the request token matches the consumer key before issuing an access token.

The client uses these to construct an Authorization header with its requests to access protected resources for that user. The signature in this request is based on the oauth_consumer_key, access token, oauth_signature_method, oauth_timestamp, oauth_nonce, and oauth_version along with any query parameters in the URI or the body of the request when the request media type is application/x-www-form-urlencoded.

# Request

POST /albums/2009/08/1011/duplicate;t=a5d0e32ddff373df1b3351e53fc6ffb1 HTTP/1.1 [1]

Host: www.example.org

Authorization: OAuth oauth_consumer_key="a1191fd420e0164c2f9aeac32ed35d23",

 	oauth_token="827fa00c6f15db4063378bb988e1563e0c318dbc",

 	oauth_signature_method="RSA-SHA1",

 	oauth_signature="f863cceebb4f1fe60739b125128e7355dcbf14ea",

 	oauth_timestamp="1258328889",

 	oauth_nonce="3c93e7fdd1101e515997abf84116ef579dccce1a",

 	oauth_version="1.0" [2]

	

Although the flow appears complex, it is designed to let clients access the user’s data without asking for the user’s credentials such as a username and password. Moreover, the user can ask the server to revoke the permission to any client.

When considering OAuth, note that the protocol is not associated with any particular resource. For a more in-depth discussion on using this protocol, see the “Beginner’s Guide to OAuth” (http://hueniverse.com/oauth).