Google Accounts Authentication and Authorization

OAuth 1.0 for Web 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 a web application's requests for access to a user's data. If instead your application is installed on a computer or a mobile device, you should read the documentation on OAuth for Installed Apps.

If you want to allow users to sign in to your application using OpenID, you can find more information about implementing the Hybrid Protocol (OAuth+OpenID) in the OpenID documentation.

Prerequisites

This document is written for web application developers using the Google Data APIs to access a user's data. It assumes that you have read the documentation for the API you are using and are aware of any service-specific authorization issues. The document also assumes that you are familiar with the principles behind OAuth. For more background information, see the Beginner's Guide to OAuth

Contents

  1. The OAuth authorization process
  2. Getting ready for OAuth
    1. Deciding whether or not to register your web application
    2. Determining the scope of the data to which you require access
    3. Setting up a mechanism to manage OAuth tokens
    4. Setting up a mechanism to request access to a Google service
    5. Implementing OpenID (optional)
  3. Working with OAuth tokens
    1. Setting a callback URL
    2. Identifying your application to users
    3. Working with Google Apps domains
  4. OAuth for Google Apps domains
  5. Migrating from AuthSub to OAuth

The OAuth authorization process

The OAuth authorization process involves a series of interactions between your web 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.

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.

Deciding whether to register your web application

To provide your users with additional assurances of the security of their data, you can choose to register your web application with Google and sign your requests with the registered security certificate. Some Google Data API feeds are available to registered applications only. See the documentation for the Google Data API you're interested in to determine if that API only works with registered applications.

Your application must sign each OAuth request it makes. If you choose to use a RSA-SHA1 signature to sign your requests, you must upload a security certificate as part of the registration process.

Alternatively, you can use a HMAC-SHA1 signature to sign your requests. No certificate is required for HMAC-SHA1 signatures. Instead, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.

For more information on the registration process, see Registration for Web Applications.

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 you require access to more than one Google service, you can obtain multiple access tokens, but no more than ten access tokens per user and application can be outstanding at any time.

If your application supports multiple user accounts, you must keep track of which account each token is associated with. Each OAuth token is specific to the user who authorized access. Your application must be able to associate a token with the correct user. One way to manage this is to issue a cookie to the user before making the token request. After the user grants access to the requested data, Google sends an authorized request token and redirects the user to your application. You can then use your application's cookie to associate the token with the correct user.

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.

Implementing OpenID (optional)

If you're implementing OpenID for user authentication, consider using the hybrid protocol to combine the two processes. With OpenID+OAuth, the tasks of getting a request token and authorizing it are handled as part of the OpenID request with OAuth extensions. As with OAuthGetRequestToken, these extensions are used to identify the Google services to be accessed. A successful response to the OpenID request contains an authorized request token. Once this token is received, use OAuthGetAccessToken to exchange it for an access token.

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.

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

For detailed documentation, see the OAuth API Reference.

Setting a callback URL

You can specify a value for oauth_callback in an OAuthGetRequestToken request, to determine where Google redirects the user after they authorize your access request. The callback URL can include query parameters. The redirect will include the same query parameters, as well as the authorized request token, which your application must be able to parse.

For example, when supporting multiple languages, you can include a query parameter that identifies the version of the application that a 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.

If the oauth_callback parameter is not included, Google will direct the user to a web page that displays a verification number (see example), after authorizing your access request. The user must manually return to your application and enter the verification number before you can obtain an authorized request token.

Identifying your application to users

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

If your application is not registered, 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".

Do not set this parameter if your application is registered. By default, Google shows the display name specified during registration. If you set a display name in your OAuthGetRequestToken request, Google will use this instead of your registered display name, and will include a message that the identity of your application cannot be verified.

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

Working with Google Apps domains

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

OAuth for Google Apps domains

Using 2-legged OAuth allows for domain-wide delegation of authority. A domain administrator can authorize access requests for all users. An application that has the OAuth consumer key and secret (roughly equivalent to a role account username and password) is allowed to act as any user in the domain when accessing Google Data APIs.

The domain administrator can revoke the key, change the secret, and control which APIs accept domain-wide delegation.

2-legged OAuth can be used, for example, to integrate with a document management system, enable third-party workflow applications, centralize backup of documents and contacts, or monitor document sharing inside and outside of the company.

Administrators for Google Apps for Business and Education accountss can enable 2-legged OAuth for their domains. This differs from the normal authorization flow, also known as 3-legged OAuth, in that no access token is required. All applications using 2-legged OAuth must be registered with Google.

Note: This feature is only available to Google Apps for Business and Education accounts.

Three key groups can use 2-legged OAuth, and the access controls can be set individually for each group.

Google Apps domain administrators

Administrators can build scripts and custom applications to manage user data for their domain using Google Data APIs. For example, an administrator can use the Google Documents Data List feed and 2-legged OAuth to provide every user in their domain with a Google Docs folder named "Human Resources", populated with common employee forms. Some Google Apps applications, such as the Google Apps Connector for BlackBerry Enterprise Server, also require OAuth to be enabled.

To learn about managing the domain administrator's key and secret associated with your Google Apps domain, and granting global access control, see "Managing the OAuth key and secret".

Third-party software vendors

Vendors can offer applications that use 2-legged OAuth to integrate with Google Apps. If the vendor has registered their own consumer key and secret with Google, you can grant their application access to a limited set of resources within your domain using the Manage API client page.

To learn about setting up third-party or internal access to a specific set of Google Data APIs, see "Managing Client API access".

Marketplace applications

Applications built for the Google Apps Marketplace can access Google APIs using 2-legged OAuth. A Marketplace application includes the API scope required in its application manifest. When the application is installed in a domain, the domain administrator must explicitly approve access to the declared scope. This gives the application access to the required scope, for that domain, using the application's 2-legged OAuth consumer key and secret.

For an example of how to use 2-legged OAuth with the Google Data API client libraries, see the Google Data OAuth documentation.

Example: Accessing a Google Data API feed

When sending access requests to Google services with 2-legged OAuth, you do not need an OAuth access token to access a user's data. Instead, include the xoauth_requestor_id query parameter in the request URL and set its value to the email address of the user whose data you are trying to access. Next, send the signed OAuth request using the HMAC-SHA1 signature method (the consumer key and secret are provided in the administrative control panel) or upload a public certificate to use RSA-SHA1. For more information on signing requests, see the Signing OAuth Requests section of this document.

The example below is used to upload an empty document, titled 'Company Perks', to the Google Docs account for j.doe@example.com. This request will succeed only if 2-legged OAuth has been enabled for the domain.

POST /feeds/documents/private/full?xoauth_requestor_id=j.doe%40example.com HTTP/1.1
Host: docs.google.com
Content-Type: application/atom+xml
Authorization: OAuth
oauth_version="1.0",
oauth_nonce="1c4fbbe4387a685829d5938a3d97988c",
oauth_timestamp="1227303732",
oauth_consumer_key="example.com",
oauth_signature_method="HMAC-SHA1",
oauth_signature="lqz%2F%2BfwtusOas8szdYd0lAxC8%3D"

<atom:entry xmlns:atom="http://www.w3.org/2005/Atom">
  <atom:category scheme="http://schemas.google.com/g/2005#kind"
                 term="http://schemas.google.com/docs/2007#document" />
  <atom:title>Company Perks</atom:title>
</atom:entry>

The Authorization header should be contained on a single line. Newlines have been inserted here for clarity.

The xoauth_requestor_id must be included as a query parameter for requests using 2-legged OAuth. The oauth_token query parameter should not be used.

Migrating from AuthSub to OAuth

AuthSub is Google's proprietary authorization API. We recommend that you migrate to the open OAuth standard where possible. For more information about the differences between the two protocols, see Using OAuth with the Google Data APIs.

If you're already registered with Google to use AuthSub, you do not need to re-register to use OAuth. However, you must specify which signature method you'll use to sign your requests. If you are using an RSA-SHA1 signature, you must also upload a security certificate as part of your domain's registration record.

If you've been using secure tokens under AuthSub, these tokens are equivalent to OAuth access tokens. These secure tokens can be used with OAuth requests.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.