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.
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
- The OAuth authorization process
- Getting ready for OAuth
- Working with OAuth tokens
- OAuth for Google Apps domains
- 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:
- 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.
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
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
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
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
exchange it for an access token.
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.
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
For example, when supporting multiple languages, you can include a query
parameter that identifies the version of the application that a user is
oauth_callback value of
"http://www.yoursite.com/Retrievetoken?Lang=de would result in the redirect
Parsing the token and the language parameter ensures that the user is
redirected back to the correct version of the site.
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
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
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
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
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
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>
should be contained on a single line. Newlines have been inserted here for
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.