OAuth for Installed Applications

Installed applications that need to access Google services protected by a user's Google or Google Apps (hosted) account can now use the OAuth protocol for authorization, using Google's newly released OAuth support for unregistered applications, and additional options for returning verification information back to the requesting application. OAuth offers a more secure authorization process than ClientLogin, and is a particularly valuable for developers working with multiple services supporting the OAuth protocol who can create a single OAuth-based authorization solution for all services.

This page discusses how to implement programmatic login using OAuth extensions for installed applications. See also the Google Accounts API Group for discussion on using the Accounts API. For information on Google's other account authorization solutions, see the Getting Started guide.

Audience

This page is aimed at programmers who are developing client applications that access a Google service and who want to implement a programmatic way to log into Google accounts. We assume you've read up on the service(s) being accessed and are aware of the access/authorization issues involved. You need to know some service-specific details when incorporating OAuth. In addition, you need to know how to make HTTPS POST requests and handle responses.

Example scenario

In this scenario, you're creating an installed application that communicates with several calendar services that provide access using the OAuth protocol, including Google's Calendar service. Users of Google Calendar manage their schedules, add, update, or delete events, and share calendar information with other users. For your application, you want to be able display Google Calendar data in your interface and provide tools to manipulate the data.

To accomplish this, you need to get access to a user's Calendar account. Before you can access the account, you need to request authorization from Google. Once you've been successfully authorized and received a token, you can access your user's Calendar data, referencing the token in each request.

Contents

1. The OAuth authorization process for installed apps
2. Working with OAuth
3. OAuth reference: endpoints
   1. OAuthGetRequestToken
   2. OAuthAuthorizeToken
   3. OAuthGetAccessToken

The OAuth authorization process for installed apps

OAuth authorization for installed applications involves a sequence of interactions between the third-party application, Google services, and the end user. This diagram illustrates the sequence:

1. The installed application contacts the Google Authorization service, asking for a request token for one or more Google service. The request is signed using the "anonymous" consumer key/secret.
2. Google verifies the request and responds with an unauthorized request token.
3. The installed application invokes a web browser.
4. In the browser, the installed application sends an OAuth request for token authorization, referencing the received request token.
5. Google displays an authorization page and prompts the user to log into their account (for verification) and then either grant or deny limited access to their Google service data by the third-party application.
6. The user decides whether to grant or deny access to the third-party application. If the user denies access, they are directed to a Google page and not back to the application.
7. If the user grants access, the Authorization service redirects the user back to a web page designated by the third-party application. The redirect includes the now authorized request token.
8. The installed application auto-detects that an authorized token has been received, retrieves the token, and reclaims focus from the browser.
9. The installed application sends a request to the Google Authorization service to exchange the authorized request token for an access token.
10. Google verifies the request and returns a valid access token.
11. The third-party application sends a request to the Google service in question. The request includes the access token.
12. If the Google service recognizes the token, it supplies the requested data.

Note: An alternative sequence does not require an installed application to invoke a browser, provide a callback URL, and auto-detect receipt of an authorized token. Instead, the sequence can require the user to initiate the token request and communicate an authorization verification number back to the installed application. This page includes information on how to implement this type of sequence.

Working with OAuth in installed apps

These tasks must be done when setting up your installed application to use the Google Authorization service with OAuth.

• Set up a mechanism to manage OAuth tokens.

  The OAuth access token acquired from Google will be used for all future interactions with the specified Google service for that user. Your application will need to manage token storage, including tracking the user and the Google service the token is valid for. Google Accounts is not set up to manage large numbers of tokens, and in fact does not allow more than ten valid tokens (per user, per third-party application) to be outstanding at any one time. This limitation allows an application to get multiple tokens to cover different services, if necessary, but does not support getting a new token each time the application needs to access a Google service. Tokens should be treated as securely as any other sensitive information.

• Determine the scope required by the Google service to be accessed.

  Each Google service determines how much and what type of access it will allow. This access is expressed as a scope value. A service's scope may be a simple URL identifying the entire service, or it may specify more limited access. Some services restrict access, such as allowing read-only access. To get the allowed scopes for the Google service you want to access, refer to the documentation for that service. You should request the most tightly scoped token possible. For example, if attempting to access Google Calendar's data feed, use the scope "http://www.google.com/calendar/feeds/", not "http://www.google.com/calendar/".

• Set up a mechanism to request and receive OAuth tokens.

  The mechanism must generate well-formed, signed token request calls and handle the responses for the following sequence:

  1. Get a request token (OAuthGetRequestToken)
  2. Get the request token authorized (OAuthAuthorizeToken)
  3. Exchange the authorized request token for an access token (OAuthGetAccessToken)

  Using query parameters in a callback URL.If you specify an oauth_callback value on an OAuthGetRequestToken request, the mechanism should be equipped to parse the redirect from Google, which contains the authorized request token, and take action with it. The callback URL can include query parameters. For example, when supporting multiple languages, include a query parameter that identifies the version of the application the user is viewing. An oauth_callback value of "http://www.yoursite.com/Retrievetoken?Lang=de would result in the redirect "http://www.yoursite.com/Retrievetoken?Lang=de&oauth_token=DQAADKEDE". Parsing the token and the language parameter ensures that the user is redirected back to the correct version of the site.

  Specifying an account domain.If your application is designed for users on a particular Google hosted domain, consider using the OAuthAuthorizeToken parameter hd when authorizing a request token. For more information on the hd parameter, see Handling Users with Multiple Accounts.

  Signing requests. With OAuth, all requests to Google must be signed. For an installed application, see Signing OAuth Requests, and follow the instructions for an unregistered application.
  

  Identifying your application to users. Google normally displays the name of an application when requesting access consent from the user (see example). With registered applications, this identifier is specified during registration. For unregistered applications, use the OAuthGetRequestToken parameter xoauth_displayname to specify the name of your application. If an unregistered application does not specify a display name, Google shows the domain name of the URL provided in oauth_callback; if no callback URL is provided, Google uses the string "anonymous".

  Invoking a web browser for user authorization and regaining focus when completed. Part of the OAuth authorization process requires that the user be directed to a Google web page, log in, and authorize access to the requesting application. Your application must in some way invoke a browser window and make the OAuthAuthorizeToken request, which opens the Google page. Then, when Google returns the authorized token, your application should be able to detect the returned token and regain focus from the web browser. Ideally, this transition takes place with minimal confusion for the user. For suggestions on how to accomplish this task, see Auto-Detecting Approval. If your application cannot handle a callback, use the alternative token display option described below.

  Displaying an authorization token. In some cases, an application will need to have the user manually convey the token verifier to the installed application. If the OAuthGetRequestToken parameter oauth_callback is left empty, Google will direct the user to a web page displaying a verification number (see example). The user must return to the installed application and enter the verification number.

  Tip: Use the OAuth Playground to experiment with requesting and receiving authorization tokens. To set the xoauth_displayname parameter, check the "Advanced" box before fetching the request token.

• Set up a mechanism to request access to a Google service.

  Refer to documentation on the Google service for information on the proper request format. All requests to a Google service must include a valid OAuth access token and be signed. In general, a request to a Google service is in the form of an HTTP GET (or POST if writing new data), with access token and signature referenced in the request header.