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.
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.
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:
- Your application requests access and gets an unauthorized request token from Google's authorization server.
- Google asks the user to grant you access to the required data.
- Your application gets an authorized request token from the authorization server.
- You exchange the authorized request token for an access token.
- 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
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.
To use OAuth, your application must generate well-formed, signed token request calls, and handle the responses, for the following sequence:
- Get an unauthorized request token (OAuthGetRequestToken)
- Authorize the request token (OAuthAuthorizeToken)
- 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).
xoauth_displayname parameter in
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
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.
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
parameter of the
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
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.
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.
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
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