| After having an overview of OAuth, we can now get a change to watch the OAuth dance unfold before us with a great site called the OAuth Playground where we can simulate all these OAuth requests. The site allows us to see the HTTP requests behind the OAuth workflow we discussed in the previous section. For the sake of this example, try to think of the OAuth playground as a rich application where you can view your Google contacts. (Obviously, OPlayground is a technical oriented site, allowing you to see the different request on the HTTP level, but the same principles apply. |  |
Choosing your scope
Defining scope for the oAuth authorization
Whenever a consumer wants to access data at Google, he needs to provide a scope.
This is a Google specific parameter (not part of the OAuth spec) that the consumer needs to send when he wants to obtain a request token. The scope will determine the type of requests that will be authorized on the access token has been retrieved.
In this case, I’ll be using the Contacts scope (defined by https://www.google.com/m8/feeds/). You can also choose multiple scopes if you require data from the different Google scopes.
Always look in the specific Google API documentation to see what scope you require. The Latitude API for example has 2 scopes that you can work with. (one for accessing the current location, and another for accessing location history).
When the scope is wrongly defined, you API calls can result in an Authorization error.
Provide the necessary OAuth parameters
| The second thing to do is to provide the required OAuth parameters for our OAuth workflow. As we don’t have a registered application, we’ll use HMAC-SHA1 as a signature method, and use the anonymous consumer key and consumer secret. The input field should look like this :If we had registered a domain at Google, we would have used the consumer key and consumer secret that was provided by Google, but for now we’ll just use anonymous.Note: Keep in mind that this kind of anonymous access doesn’t work for all Google APIs. The Latitidue API for example can only be accessed through a registered application, so using anonymous as a consumer key / consumer secret will result in authorization failures.
As you can see, 2 form fields are already provided by the playground. The oauth_timestamp and oauth_nonce are values used by the OAuth framework to avoid that the same request is fired over & over again. |
 oAuth params required for retrieving the request token |
Signing you request
Another very important parameter that is not mentioned in the table is the oauth_signature. This parameter value is generated automatically by the playground (and as such doesn’t appear on the form).
The oauth_signature is the result of signing your request. This parameter is passed on together with the parameters above in the HTTP authorization headers.
Note : Each time you send a request in the OAuth workflow (request,authorize or access token) the consumer needs to sign the HTTP request, and include that signature (as the oauth_signature parameter) to the request that you just signed.
The oauth_signature is derived from the Signature base string. The signature base string looks like this :
GET&https%3A%2%2Fwww.google.com%2Faccounts%2FOAuthGetRequestToken&oauth_callback%3Dhttp%253A%252F%252Fgooglecodesamples.com%252Foauth_playground%252Findex.php%26 oauth_consumer_key%3Danonymous%26oauth_nonce%3D91dc12eb6eaca91e9a98cd1f0d5724a8%26oauth_signature_method%3DHMACSHA1%26oauth_timestamp%3D1287431663%26 oauth_version%3D1.0%26scope%3Dhttps%253A%252F%252Fwww.google.com%252Fm8%252Ffeeds%252F
Alongside the original request URL (in this case OAuthRequestToken), it also includes all parameters that are sent with the request.
Enough with the theory, we’ll now initiate our first request, the OAuthRequestToken request, by submitting the form.
Request a token
| Requesting a token is done by clicking on the Request Token button. What will happen now is that a request will be fired to Google, and a request token will be returned. |
 oauth playground - request token |
As you can see from this initial request, we’ve passed all our parameters, including the signature derived from our base string (oauth_signature=”IKoPssKd2YXO73frNHg%2BtrTYq8Y%3D”).
GET /accounts/OAuthGetRequestToken?scope=https%3A%2F%2Fwww.google.com%2Fm8%2Ffeeds%2F HTTP/1.1 Host: www.google.com Accept: */* Authorization: OAuth oauth_version="1.0", oauth_nonce="84acdf45870619360b94eeadfda9e6d5", oauth_timestamp="1289139360", oauth_consumer_key="anonymous", oauth_callback="http%3A%2F%2Fgooglecodesamples.com%2Foauth_playground%2Findex.php", oauth_signature_method="HMAC-SHA1", oauth_signature="5O2E95BSnMGNzAzOEWXwXzkzamo%3D"
The actual base string that was used to generate the oauth_signature was this :
GET&https%3A%2F%2Fwww.google.com%2Faccounts%2FOAuthGetRequestToken&oauth_callback%3Dhttp%253A%252F%252Fgooglecodesamples.com%252Foauth_playground%252Findex.php%26oauth_consumer_key%3Danonymous%26oauth_nonce%3D84acdf45870619360b94eeadfda9e6d5%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1289139360%26oauth_version%3D1.0%26scope%3Dhttps%253A%252F%252Fwww.google.com%252Fm8%252Ffeeds%252F
As you can see, it contains all the authorization headers that were sent with the original request.
The server responds to our request and sends us an oauth_token and oauth_token_secret.
HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 Date: Sun, 07 Nov 2010 14:16:00 GMT Expires: Sun, 07 Nov 2010 14:16:00 GMT Cache-Control: private, max-age=0 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Content-Length: 118 Server: GSE oauth_token=4%2FkQMaP3-ltbDV2EDtMV5V-a9Ko3Sy&oauth_token_secret=zf4NplkD61pt7PYpNtJnUIuw&oauth_callback_confirmed=true
| Now that we have received the request token, and the request token secret, you’ll notice that the OAuth playground has updated the oauth_token value, and marked it as a request token. We can now continue the OAuth workflow, and authorize this request token. |
 oauth playground request token received |
Authorize the request token
Next step is to authorize the request. This is done by sending a new request to Google containing the Request Token we just obtained. This request doesn’t need to be signed, and the only parameter that we need to send is the request token we just retrieved (via the oauth_token).
https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=4%2FkQMaP3-ltbDV2EDtMV5V-a9Ko3Sy&hd=default
Sending this request to Google will show the following page where Google will request you to authorize the consumer (in this case googlesamples.com) to access you contacts (the scope we identified when sending the request to obtain the Request Token. Notice how our oauth_token is added to the OAuthAuthorizeToken URL. Here, the user has the ability to grant access to the consumer to access the user data on his behalf.
Note : Because we were already logged in, Google doesn’t show the login page again. If we weren’t logged into Google at the time this request was sent, Google would have shown us the login page, followed by the page above.If you decide to grant access, you’ll be redirected to the google oauth playground application at the following URL.
http://googlecodesamples.com/oauth_playground/index.php?oauth_verifier=Twx9xEA1oaddlCgVZqcDyp4E&oauth_token=4%2FkQMaP3-ltbDV2EDtMV5V-a9Ko3Sy
The fact that you get redirected to this URL is a result of the oauth_callback parameter that was specified when the original request token was requested. Recall that when we requested the token, the following authorization headers were sent :
oauth_callback="http%3A%2F%2Fgooglecodesamples.com%2Foauth_playground%2Findex.php"
| The callback value that was provided in the first step is now being used to redirect the user back to the consumer. This callback value allows the playground to capture the authorized token by just picking it up from the request.
As you can see the playground has detected the token as an authorized token. Now that we have received an authorized token, we can exchange it for an access token. |
 oauth playground authorized request |
Upgrading to an access token
Retrieving an access is done through the playground by clicking on the access token button.
When clicking on the access token button, the following request will be sent. Notice how it contains all the oauth parameters we discussed in the previous section, in addition to the oauth_token and oauth_verifier we just received.
GET /accounts/OAuthGetAccessToken HTTP/1.1 Host: www.google.com Accept: */* Authorization: OAuth oauth_version="1.0", oauth_nonce="c03275566ac0075f10c2d887efe071b6", oauth_timestamp="1289140888", oauth_consumer_key="anonymous", oauth_verifier="Twx9xEA1oaddlCgVZqcDyp4E", oauth_token="4%2FkQMaP3-ltbDV2EDtMV5V-a9Ko3Sy", oauth_signature_method="HMAC-SHA1", oauth_signature="dys5kmcOaMEaY2%2F0gJGSg4yZPX0%3D"
If the provider decides that this was a valid request, it will send the following response to the consumer, containing the oauth_token and oauth_token_secret. These values will then need to be stored by the consumer, as they will be required for making the actual API calls by the consumer on behalf of the user.
HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 Date: Sun, 07 Nov 2010 14:41:28 GMT Expires: Sun, 07 Nov 2010 14:41:28 GMT Cache-Control: private, max-age=0 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Content-Length: 103 Server: GSE oauth_token=1%2FjHevf25EFRTGS4N-0G-LPRiBKR6zDFRE451WTYU&oauth_token_secret=nel2UClZHG76BDERFSQA
If you decide to deny the authorization request, you won’t be able to retrieve the access token.
GET /accounts/OAuthGetAccessToken HTTP/1.1 Host: www.google.com Accept: */* Authorization: OAuth oauth_version="1.0", oauth_nonce="be1693e4d0974ccdfa3ae98ea9169341", oauth_timestamp="1287435215", oauth_consumer_key="googlecodesamples.com", oauth_verifier="GIFvdB4lrHKhpGW0FV6DQMWo", oauth_token="4%2FEEIIdQW8rwQMu9cpJFJcX5OUPNIm", oauth_signature_method="HMAC-SHA1", oauth_signature="Bm8fGXBHsZaHOuO5GT%2FHMZNRZUY%3D"
The signature will turn out to be invalid, and google will reject your request for an access token.
HTTP/1.1 400 Bad Request Content-Type: text/plain; charset=UTF-8 Date: Mon, 18 Oct 2010 20:53:35 GMT Expires: Mon, 18 Oct 2010 20:53:35 GMT Cache-Control: private, max-age=0 X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Content-Length: 374 Server: GSE signature_invalid base_string:GET&https%3A%2F%2Fwww.google.com%2Faccounts%2FOAuthGetAccessToken&oauth_consumer_key%3Dgooglecodesamples.com%26oauth_nonce%3Dbe1693e4d0974ccdfa3ae98ea9169341%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1287435215%26oauth_token%3D4%252FEEIIdQW8rwQMu9cpJFJcX5OUPNIm%26oauth_verifier%3DGIFvdB4lrHKhpGW0FV6DQMWo%26oauth_version%3D1.0
As a consequence of failing to obtain an access token, you won’t be able to make any API calls.
Making API calls with the access token
If you do have a valid access token, you can make API calls by sending your access token like this :
GET /m8/feeds/contacts/default/full HTTP/1.1 Host: www.google.com Accept: */* Authorization: OAuth oauth_version="1.0", oauth_nonce="28503b279e6587476f2462ccf1ddbfb9", oauth_timestamp="1289090198", oauth_consumer_key="anonymous", oauth_token="1%2FMcBedK1K557my_sC5XD0nN35iZtssXswhLISuqvWpN8", oauth_signature_method="HMAC-SHA1", oauth_signature="jbkNt%2FcPAPdcKmLQZF1Ze32XqO8%3D" Content-Type: application/atom+xml GData-Version: 2.0