Home > Security > Google OAuth Overview

Google OAuth Overview

If you’re like me, you were probably a bit overwhelmed the first time you started looking at the Google authentication and authorization APIs. Although everything is well documented, it took me a couple days to get the full picture, and actually start some work with it.  The goal of this article is to clarify some of the principles in a condensed form, and then start with some hands on examples in Java & PHP. oauth logo
  • We’ll start with an overview of how OAuth works, using the typical example of an application accessing user data from a Google service.
  • We’ll then focus on the oauth specific parameters that are associated with each request / response
  • In a follow-up post, we’ll be looking at hte OAuth playground, and implement a OAuth workflow using standard java and an Android app.

What’s important to realize is that OAuth provides you with a standard way of letting your application act on the users behalf when connecting to third party providers like Google, Yahoo, LinkedIn, Photobucket,….

It allows your application to integrate with these providers, without forcing the user to enter his credentials (username/password) in your application. The user is assured that your application will never have to read or store the user credentials, but thanks to OAuth, your application (after being granted permission by the user) will be able to interact with these providers on his/her behalf.

OAuth overview

According to OAuth (from http://oauth.net/core/1.0a/):

The OAuth protocol enables websites or applications (Consumers) to access Protected Resources from a web service (Service Provider) via an API, without requiring Users to disclose their Service Provider credentials to the Consumers. More generally, OAuth creates a freely-implementable and generic methodology for API authentication.

What we’re reading here is that we’re dealing with a standard way for an application to implement authorization towards user protected resources, without the need for that application to acquire the users passwords.

According to Google (from Google Latitude API : Developer’s Guide (v1): Using REST)

any application that requires access to a user’s data must be authorized by the user. Similarly, we make sure the user who is authorizing the access is who they say they are. For more information about authentication and authorization at Google

What we’re basically reading here is that if my application want to access your location through the Google APIs, 2 things must happen.

  • You need to allow my application to view your location (authorization) managed by and stored at Google.
  • You who are allowing me to view your data needs to be who you say you are (authentication)

We’re seeing 3 actors here :

  • You : the user
  • My application : the consumer
  • Google : the provider

When an application wants to access your data using OAuth, it needs to participate in the OAuth workflow (also known as the OAuth dance). In order to accomplish this flow,  a series of request / responses between the consumer (my application), and the provider (Google) need to be initiated. Each interaction (consumer sending a request and provider sending a response) involves sending / receiving a set of parameters.

We’ll cover the OAuth flow in detail here, including all the steps that both the consumer, provider and user needs to take. The detailed steps are outlined here, and are shown in the slides as well :

  1. The consumer registers his domain with the provider (prerequisite).
  2. The provider accepts the registration and provides a consumer key and a consumer secret.
  3. The consumer requests a request token (OAuthGetRequestToken).
  4. The service provider sends the request token.
  5. The consumer sends his request token for authorization (OAuthAuthorizeToken)
  6. If the user is not logged into the service provider, he does so now.
  7. User is authenticated by the provider. The consumer doesn’t capture the username/password
  8. The provider informs the user that the consumer wants to access his protected resource
  9. The users needs grants access to the consumer
  10. The provider then sends an authorized token to the consumer.
  11. The consumer sends his authorized token (OAuthGetAccessToken)
  12. The service provider knows that the user has granted access and sends an access token

This might seem overwhelming, but it all will become clear once we go through the individual steps. Always keep in mind what actor is performing the request, and what token is being exchanged.

All of these interactions are done through HTTP requests. The provider provides the endpoints for each interaction in the OAuth flow. The consumer takes note of each endpoints, and uses them in the interaction with the provider to finish the OAuth workflow.

Most google services define the following oAuth endpoints :

OAuth Endpoint URL
Request token endpoint https://www.google.com/accounts/OAuthGetRequestToken
Authorization endpoint https://www.google.com/accounts/OAuthAuthorizeToken
Access token endpoint https://www.google.com/accounts/OAuthGetAccessToken

The consumer will send a request to each of these endpoints. The provider then responds to these requests by sending an appropriate response so that the consumer can continue.

Each endpoint also defines a set of request parameters that need to be sent by the consumer, and a set of request parameters that will be returned by the provider.  We’ll cover these in the following section.

Note : In order to use Latitiude with OAuth, a different Authorization endpoint is used : https://www.google.com/latitude/apps/OAuthAuthorizeToken.
We’ll cover this in more detail later.

OAuth prerequisites

Before a consumer can start accessing data on behalf of a user, it first needs to register itself with the service provider (in this case Google). Usually, the service provider will provide some kind of registration form where you can register your application or domain. Google works with domains.  Registration for web based applications at Google is a simple process where you register your domain (site), and verify that you are the owner by any of the available verification methods (uploading an html file, adding a meta tag , ….). Once your domain has been registered, Google will provide you a consumer key and a consumer secret. The consumer key is used to identify yourself with the provider, and is sent in some of the OAuth requests. The consumer secret is used for signing requests that are sent to the provider as part of the OAuth workflow.

oauth part domain registration

oauth part domain registration

Google provides a page for managing your domains, where you can retrieve the consumer key and consumer secret for each registered domain.

Once you’ve registered a domain, you’ll get to see the following page :

google manage domains page

google manage domains page

Now that we have the pre-requisites out of the way, we can start with the first step in the OAuth workflow, and that is obtaining a request token.

OAuth Request Token

The request token is the first token to be exchanged in the OAuth workflow. When the consumer wants to retrieve user protected data, it first needs to get a hold of such a request token. This token is not user-bound, so it doesn’t require any interaction with the user. This is basically the initial handshake in the OAuth workflow. The application requests the request token using his consumer key. He signs his request with this consumer secret and sends if off to the service provider. The server provider hands out a request token to the consumer. Along with the request token (identified by the oauth_token parameter), the consumer also receives an oauth_token_secret. The secret is required to sign the next request that is to be sent to the provider. We’ll cover signing in a seperate section. Keep in mind that signing requests properly will be handled by the OAuthlibrary you’ll be using in your application.

oauth request token

oauth request token

After this initial request/response, the consumer has obtained a request token. Keep in mind that the user hasn’t been involved in the process yet. This is going to change in the following step. The consumer now needs to “upgrade” the request token into an authorized token. This involves user interaction, as in this step, the user needs to grant access to the consumer to access his protected data at Google.
To recap, he’re an overview of all the parameters that are sent by the consumer for the request token :

Parameter Name Description Sample Value
oauth_signature_method As we haven’t registered a domain with google, we’ll use HMAC-SHA1 . This is described in the Google OAuth API Reference. HMAC-SHA1
oauth_consumer_key Again, as we haven’t registered a domain with google, we need to pass “anonymous” here. In a live-scenario, where the application would have been registered by the service provider (google), a consumer key would have been provided by the service provider. anonymous
oauth_signature Our request signature. OAuth defines the way requests should be signed. It basically involves generating a base string, containing your request URL and all parameter name/value pairs in alphabetical order. All of this is concatenated into a single String, and the String is then signed using the consumer secret. The resulting signature is placed in the oauth_signature parameter. Signing a request is a fairly complex thing, as it involves putting the request parameters in the correct order, and signing the correct base string. This is described in detail in the OAuth specification, but keep in mind that OAuth library handle this for you. See the special section regarding signing below. 5O2E95BSnMGNzAzOEWXwXzkzamo%3D
oauth_timestamp Number of seconds after January 1, 1970 00:00:00 GMT.  Each token request (request token and access token requests) needs to include a timestamp. 1289139360
oauth_nonce Random 64-bit, unsigned number encoded as an ASCII string in decimal format 84acdf45870619360b94eeadfda9e6d5
oauth_version Optionally, a version outlining the OAuth spec. 1.0
oauth_callback A callback value can also be provided. This callback will be fired after the user has authorized the request. Keep in mind that during the authorization part, the user has been redirected to the provider pages (where he can login, and/or authorize the request). After granting the request, the user needs to be redirected back to the consumer. This is done using the callback. The consumer can interpret the callback and at that point knows he has an authorized token. We’ll refer to this callback in the next step. http%3A%2F%2Fgooglecodesamples.com%2F
oauth_playground%2Findex.php

The provider responds with the following values

Parameter Name Description Sample Value
oauth_token The actual request token that the provider sends to the consumer. In the next step, the consumer will upgrade this token to an authorized token. 4%2FkQMaP3-ltbDV2EDtMV5V-a9Ko3Sy
oauth_token_secret A value that the consumer will use to sign his request when obtaining an access token (final step in the OAuth workflow). The consumer needs to store the oauth_token and oauth_token secret untill the OAuth workflow has ended. It’s untill the final step in the OAuth workflow that the consumer will receive the access token. zf4NplkD61pt7PYpNtJnUIuw
callback_confirmed a value that indicates if the provider confirmed the callback value that was sent. true

OAuth Authorize Token

In the next step of the OAuth workflow, the consumer will send the request token he just obtained to the service provider for authorization. The user who is allowing the consumer to access his data needs to formally grant that access, or authorize the consumer access to his protected resources. The user (who is registered at the service provider)  first needs to login to his account  (if he’s already logged into the service provider, this step is skipped). The service provider then informs the user that the consumer is requesting access to his protected data (in this example, Google contacts). If the user grants access, the service provider will upgrade the request token to an authorized token. He’ll also send an oauth_verifier value to the consumer. The oauth_verifier is requiredin the following step, where the authorized token needs to be swapped in for an access token.

oauth authorize token

oauth authorize token

This is the most simple request that the consumer needs to send to the provider. As you can see, the authorization step involves less parameters then the previous request. We don’t need to sign our request, but just send our request token to the authorization URL :

Parameter Name Description Sample Value
oauth_token The request token we obtained in the previous step 4%2FksMaP3-ltEDV2EDtMV5V-a9Ko3Sy

As the provider takes over from here, the user will be guided to a login process (if not already logged in), and will finally get to authorize the request. Once the request has been authorized, the provider will redirect the 2 parameters below to the consumer using the callback url specified in the request token step. This allows the consumer to capture these values, and prepare for the final step, retrieving an access token.

Parameter Name Description Sample Value
oauth_token The authorized token. 4%2FksMaP3-ltEDV2EDtMV5V-a9Ko3Sy
oauth_verifier Value used by the consumer to attach to his request when retrieving an access token. Twx9xEA1oaddlCgVZqcDyp4E

OAuth Access Token

The only thing left to do now for the consumer is to exchange this authorized token for an access token. For that, the consumer sends the oauth_token and oauth_verifier parameters he has received during the previous step.

oauth access token

oauth access token

This request is similar to the first request (retrieve request token), only now we send the oauth_token and the oauth_verifier.

Parameter Name Description Sample Value
oauth_consumer_key Again, as we haven’t registered a domain with google, we need to pass “anonymous” here.In a live-scenario, where the application would have been registered by the service provider (google), a consumer key would have been provided by the service provider. anonymous
oauth_signature_method As we haven’t registered a domain with google, we’ll use HMAC-SHA1 . This is described (buried) somewhere in the OAuth API Reference. HMAC-SHA1
oauth_timestamp Number of seconds after January 1, 1970 00:00:00 GMT. (generated by the playground) 1289140888
oauth_nonce Random 64-bit, unsigned number encoded as an ASCII string in decimal format (generated by the playground) c03275566ac0075f10c2d887efe071b6
oauth_signature Our request signature. dys5kmcOaMEaY2%2F0gJGSg4yZPX0%3D
oauth_token Our authorized token received in the previous step. 4%2FksMaP3-ltEDV2EDtMV5V-a9Ko3Sy
oauth_verifier Our verifier token received in the previous step. Twx9xEA1oaddlCgVZqcDyp4E
oauth_version Optionally, a version outlining the OAuth spec can be provided 1.0

The provider responds with the following parameters :

Parameter Name Description Sample Value
oauth_token Our access token. This token will be used in all future calls when requesting user authorized data. All of these calls fall outside the OAuth workflow scope. 1%2FjHfvf29ESLSVZAS4N-0G-LPAQBKR2zmf2e8HLW51WTYU
oauth_token_secret Value to be used by the consumer to sign requests. zf4NeEkD543g2PYpNtJnABsw

With the access token, the consumer can now query the provider for the data, providing that these calls fall in the scope that was originally defined when the consumer retrieved the request token.

Conclusion

OAuth is a great way to integrate your applications with third party providers. By having an open standard for authorizing access to user protected resources, developers can leverage existing OAuth libraries for a multitude of languages, and integrate their applications quickly with providers supporting the OAuth standard.

The OAuth standard is widely supported by all major players (Google, Yahoo, LinkedIn , Phtotobucket, ….).

Although OAuth does have a somewhat steep lurning curve, it’s important to realize that a lot of the complexities involved in OAuth (sending the correct parameters, signing requests, ….) are handled by the OAuth library that you’ll use.

Despite of this, I think it’s important to have a good understanding on what is happening under the hood of these libraries in order gain a better understanding of the OAuth workflow, and to help you debug problems should the need arise.

My next posts will focus on some hands on OAuth using the OAuth playground, a java based library, and a sample Android app implementing the OAuth workflow.

References :

Bookmark and Share
  1. Bianca
    July 11th, 2011 at 17:35 | #1

    Is there any pre-requisite for developing for installed app on mobile? Do I need to go thru the domain registration step??

    Thanks,

  2. mistaguy
    July 13th, 2011 at 06:42 | #2

    Very Well Illustrated and Explained

    • admin
      July 16th, 2011 at 18:00 | #3

      Thx… I noticed many people seem to struggle with Oauth… once you get the hang of it it’s pretty straightfoward….

  1. November 8th, 2010 at 20:04 | #1
  2. November 8th, 2010 at 20:25 | #2
  3. November 10th, 2010 at 18:59 | #3
  4. April 12th, 2011 at 17:26 | #4