OAuth 1.0 for Installed Applications

Important: OAuth 1.0 was officially deprecated on April 20, 2012, and is no longer supported.
We encourage you to migrate to OAuth 2.0 as soon as possible.

OAuth documentation

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.

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:

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.

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.

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

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.