Google Accounts Authentication and Authorization

OAuth 1.0 for Installed Applications

Important: OAuth 1.0 has been officially deprecated as of April 20, 2012. It will continue to work as per our deprecation policy, but we encourage you to migrate to OAuth 2.0 as soon as possible.

This document describes how to get started using Google's implementation of the OAuth protocol to authorize an installed application's requests for access to a user's data. If you are writing a web application you should read the documentation on OAuth for Web Apps instead.

OAuth offers a more secure authorization process than alternative protocols, and its widespread support allows developers working with multiple services to create a single OAuth-based authorization solution for a variety of services.

Installed applications benefit from Google's OAuth support for unregistered applications, as well as additional options for returning verification information to the requesting application.

Prerequisites

This document is written for application developers using the Google Data APIs to access a user's data. The document assumes that you are familiar with the principles behind OAuth, and that you know how to make GET and POST requests over HTTPS.

For background information on OAuth, see the Beginner's Guide to OAuth.

For service-specific authorization issues, see the documentation for the API you are using.

Contents

  1. The OAuth authorization process
  2. Getting ready for OAuth
    1. Determining the scope of the data to which you require access
    2. Setting up a mechanism to manage OAuth tokens
    3. Setting up a mechanism to request access to a Google service
  3. Working with OAuth tokens
    1. Identifying your application to users
    2. Launching a web browser

The OAuth authorization process

The OAuth authorization process involves a series of interactions between your application, Google's authorization servers, and the end user.

At a basic level, the process is as follows:

  1. Your application requests access and gets an unauthorized request token from Google's authorization server.
  2. Google asks the user to grant you access to the required data.
  3. Your application gets an authorized request token from the authorization server.
  4. You exchange the authorized request token for an access token.
  5. You use the access token to request data from Google's service access servers.

When your application initially requests access to a user's data, Google issues an unauthorized request token to your application.

If the user is not already logged in, Google prompts the user to log in. Google then displays an authorization page that allows the user to see what Google service data your application is requesting access to.

If the user approves your application's access request, Google issues an authorized request token. Each request token is valid for only one hour. Only an authorized request token can be exchanged for an access token, and this exchange can be done only once per authorized request token.

OAuth supports installed applications using the unregistered mode. Because there are various methods for obtaining an authorized request token, your app can use OAuth to authorize an application even if the device it's installed on does not have a web browser.

By default, access tokens are long-lived. Each access token is specific to the user account specified in the original request for authorization, and grants access only to the services specified in that request. Your application should store the access token securely, because it's required for all access to a user's data.

Getting ready for OAuth

Before you can set up your application to use the Google Authorization service with OAuth, you must complete the following tasks.

Determining the scope of the data your application will access

Each Google service sets limits on the access it allows through the Google Data APIs. This access is expressed as a scope value. Some services provide a variety of scope values, to allow a user to choose which applications should have access to which data. For information about the available scope values for the Google service you want to access, see the documentation for that service.

In general, you should request a token for the narrowest scope that includes the data you need. For example, if your application requires access to the user's "All Calendars" feed, you should request a token for the scope http://www.google.com/calendar/feeds/default/allcalendars/full.

Setting up a mechanism to manage OAuth tokens

When you obtain an OAuth access token for a user's data, you must use that access token for all future interactions with the specified Google service on behalf of the user.

Your application should manage token storage securely, including tracking the Google service for which each token is valid.

If your application supports multiple user accounts, you must keep track of which account each token is associated with.

Setting up a mechanism to request access to a Google service

Each request to a Google service must be signed, and must include a valid OAuth access token. In general, each request is made in the form of a HTTP GET request, with the access token and signature included in the header. Requests that write new data should use HTTP POST.

For more information on the proper request format for each Google Data API, refer to the documentation for that API.

Working with OAuth tokens

To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:

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

All OAuth requests must be signed, whether or not your application is registered. For further information, see Signing OAuth Requests. Installed applications should follow the instructions for an unregistered application.

You can experiment with requesting and receiving authorization tokens in the OAuth Playground.

For detailed documentation, see the OAuth API Reference.

Identifying your application to users

Google normally displays the name of an application when requesting access consent from the user (see example).

Use the xoauth_displayname parameter in your OAuthGetRequestToken request to specify the name of your application. If that parameter is not specified, Google displays the domain name of the URL provided by the oauth_callback parameter. If no callback URL is provided, Google displays the string "anonymous".

Note: To set the xoauth_displayname parameter in the OAuth Playground, check the "Advanced" box before fetching the request token.

Launching a web browser

As part of the OAuth authorization process, your application must make a OAuthAuthorizeToken request. The user must then log in to a Google web page and authorize your application's access request.

  • AutoDetect mode should be used for most applications
  • Device mode should be used for applications which cannot launch a full web browser.
  • Development mode should be used during early development only.

AutoDetect mode

If possible, your application should launch a browser window and make an OAuthAuthorizeToken request to open the Google page. When Google returns the authorized token, your application should detect this and regain focus from the web browser.

This mode requires that you provide a callback URL to which the user is redirected after they authorize your access request. This URL must be provided as the oauth_callback parameter of the OAuthGetRequestToken request, and as the verifier parameter of the OAuthGetAccessToken request.

To improve the user experience, your application should attempt to automatically detect when the user is redirected to this URL, and immediately bring itself to the foreground and make a OAuthGetAccessToken request to complete the OAuth process.

For more information and best practices, see Auto-Detecting Approval.

If your application cannot automatically detect when the user is redirected to the callback URL, or cannot bring itself to the foreground, the callback URL should display a page that explains how to bring your application to the foreground and how to initiate the OAuthGetAccessToken request from within your application.

Device mode

If your application cannot launch a full web browser, it is also possible for rich-client devices to authorize without a web browser.

This mode allows a developer to set up a website where a user can authorize the request for access. After authorization, the user is given a code generated by Google, and redirected to the developer's site. This site should explain to the user how to input the code into their device to complete the authorization process.

Development mode

This mode is recommended for use during the early development of an application only.

As in the AutoDetect mode, your application must launch a browser, and the user must authorize your request. However, instead of creating a webpage for the callback URL, you can set the value of the oauth_callback parameter to "oob" (out of band).

In that case, after the user authorizes your request, Google directs the user to a Google Accounts page that displays a verification number (see example).

The user must return to your application and enter the verification number, before you can make a OAuthGetAccessToken request.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.