The specification on this page is provided under the following Patent License.
Google Code offered in: English - Español - 日本語 - 한국어 - Português - Pусский - 中文(简体) - 中文(繁體)
|
English
| Sign in
Google supports the OAuth protocol for authorizing web applications accessing their users' Google services. This page describes Google's implementation of OAuth with instructions on how to use it. For more information on the OAuth standard, see the OAuth.net documentation. Applications making OAuth requests to Google can be either registered or unregistered, but must sign all requests.
Google now supports a hybrid protocol, combining Federated Login with OAuth (OpenID+OAuth). Many third-party sites enable OpenID to let their users log in with their Google account information (freeing the third-party developer from having to manage login security). OpenID+OAuth combines the two authorization processes, minimizing the round-trip communication required for authorization—and, equally important, simplifying the process for users by giving them one confirmation page instead of two.
See also the Google Accounts API Group for discussion on using the Accounts API. For information on Google's other account authorization solutions, see the Getting Started guide.
This document is written for web application developers who want to access their users' Google services using the OAuth protocol. It assumes you've read up on the service(s) being accessed and are aware of any access authorization issues involved. You need to know some service-specific details when using Google's authorization proxy service. This document also assumes you have a basic familiarity with OAuth.
OAuth authorization for web applications involves a sequence of interactions between your web application, Google services, and the end user. This diagram illustrates the sequence:
With OAuth, there are two types of tokens used: request tokens and access tokens. Request tokens are used to verify Google registration and get end user authorization, after which they can be exchanged for an access token. Access tokens are used to request user data from the Google service(s) covered by the token.
The request token exists in one of two states: unauthorized and authorized. Initially, Google issues an unauthorized request token. Once the end user logs in and grants access to the third-party web application, the request token is authorized. Only authorized tokens can be exchanged for an access token. Request token are valid for one hour only, and can be exchanged only once.
Each OAuth access token is specific to one user account and covers the Google services specified in the original request for authorization. Access tokens are by default long-lived, and can be used any time the web application needs to access a covered service for that user's data.
The web application must have a mechanism to store access tokens for future use. For other token management options, see Working With OAuth Authorization.
If you're using OAuth, you can opt to register your web application with Google and provide enhanced security for your users by creating a security certificate. Although most Google services allow access to unregistered applications, some require more secure access. For more information on the registration process, see Registration for Web Applications.
This section covers topics relevant to using Google's Authorization service with OAuth.
These tasks must be done when setting up your web application to use the Google Authorization service with OAuth:
If you choose to register, use the automated registration page to register your web application with Google. At some point you will need to decide which signature method will be used to sign requests. If using the RSA-SHA1 signature method, you need to upload a security certificate as part of the registration process. For the HMAC-SHA1, no certificate is required; instead an OAuth "consumer secret" value is generated and displayed on your domain's registration page after you have registered.
An OAuth access token acquired from Google is intended to be used for all future interactions with the specified Google service for that user. Your web application will need to manage token storage, including tracking the user and Google service the token is valid for. Google Accounts is not set up to manage large numbers of tokens, and in fact does not allow more than ten valid tokens (per user, per web application) to be outstanding at any one time. This limitation allows a web application to get multiple tokens to cover different services, if necessary, but does not support getting a new token each time the web application needs to access a Google service. Tokens should be treated as securely as any other sensitive information stored on the server.
Each Google service determines how much and what type of access it will allow. This access is expressed as a scope value. A service's scope may be a simple URL identifying the entire service, or it may specify more restricted access. Some services severely limit access, such as allowing read-only access to limited information. To get the allowed scopes for the Google service you want to access, refer to the documentation for that service. You should request the broadest scoped token possible. For example, if attempting to access a Google Calendar feed, use the scope "http://www.google.com/calendar/feeds/", instead of "http://www.google.com/calendar/feeds/default/allcalendars/full". Using the latter limits access to the all calendars feed, whereas the first scope grants access to all of Calendar's feeds.
The mechanism must generate well-formed, signed token request calls and handle the responses for the following sequence:
Managing Tokens. Because OAuth tokens are specific to a user, your application must be able to associate a token with its user. The preferred option is to issue a cookie to the user before making the token request. Then, when Google redirects the user back to your site with an appended token, your application can read the cookie and associate the token with the correct user identification.
Using query parameters in a callback URL. If you specify an oauth_callback value on an OAuthGetRequestToken request, the mechanism should be equipped to parse
the redirect from Google, which contains the authorized request token, and take action with it. The callback URL can include query parameters. For
example, when supporting multiple languages, include a query parameter that identifies the version of the web application the 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.
Specifying an account domain. If your application is designed for users on a particular Google hosted domain, consider using the hd parameter when authorizing a token. For more information on the hd parameter, see Handling Users with Multiple Accounts.
Signing requests. With OAuth, all requests to Google must be signed. For information on signing requests with registered or unregistered applications, see Signing OAuth Requests.
Identifying your application to users. Google normally displays the name of an application when requesting access consent from the user (see example). With registered applications, this identifier is specified during registration. If your application is registered, do not set the OAuthGetRequestToken parameter xoauth_displayname; setting this parameter triggers Google to use this identifier rather than the one set during registration and to include a message that the application identity can't be verified. For unregistered applications, use the display name parameter to specify the name of your application. If no display name is set for an unregistered application, Google shows the domain name of the URL specified in the OAuthGetRequestToken oauth_callback parameter; if no callback URL is provided, Google uses the string "anonymous".
Displaying an authorization token. In some cases, an application will need to have the user manually convey the token verifier back to the web application. If the OAuthGetRequestToken parameter oauth_callback is left empty, Google will direct the user to a web page displaying a verification number (see example). The user must return to the application and enter the verification number.
Tip: Use the OAuth Playground to experiment with requesting and receiving authorization tokens. To set the xoauth_displayname parameter, check the "Advanced" box before fetching the request token.
If you're implementing Federated Login for user authentication, you may want to use 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.
Refer to documentation on the Google service for information on the proper request format. All requests to a Google service must include a valid OAuth access token and be signed. In general, a request to a Google service is in the form of an HTTP GET (or POST if writing new data), with access token and signature referenced in the request header.
Here are some tips for developers who are switching their authorization method from Google AuthSub to OAuth:
RSA-SHA1 signature method, you need to upload a security certificate as part of your domain's registration record.Differences between the two protocols are discussed in the Using OAuth with the Google Data APIs article.
Note: This feature is only available to Google Apps Premier and Education Edition domains.
While OAuth authorization is available to all developers wishing to access the Google Data APIs, Google Apps Premier and Education Edition administrators can enable a special kind of OAuth for their hosted domains, called 2-legged OAuth. Specifically, an access token is not required as per the normal authorization flow, also referred to as 3-legged OAuth. Applications using 2-legged OAuth must be registered with Google.
With Google Apps Premier and Education Edition, administrators can use two-legged OAuth for domain-wide delegation of authority. 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. Unlike three-legged OAuth, users do not need to give consent on an individual basis, as this decision is made on their behalf by the administrator. Administrators can revoke the key, change the secret, and control which APIs accept domain-wide delegation.
As an example, this feature can be used to do things like integrate with document management systems, enable third-party workflow applications, centralize backup of documents and contacts, and monitor document sharing inside and outside of the company.
Two key groups can use two-legged OAuth, and the access controls applied may be very different in each case.
Administrators can build scripts and custom applications that manage the user data for their domain through Google Data APIs. For example, an administrator can use the Google Documents Data List feed and two-legged OAuth to configure every user in their domain with a Google Docs folder named "Human Resources" that's 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 key and secret that's associated with your Google Apps domain, and granting global access control, see "Managing the OAuth key and secret".
Vendors may offer applications that use two-legged OAuth to integrate with Google Apps. If the vendor has registered their own consumer key and secret with Google, you can grant access to the vendor's client application to a limited set of Google resources on 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".
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.
This example uploads an empty document, 'Company Perks', to j.doe@example.com's Google Documents:
POST /feeds/documents/private/full?xoauth_requestor_id=j.doe%40example.com HTTP/1.1
Host: http://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>
Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity.
Here are a couple of points worth mentioning:
oauth_token query parameter should not be included with the request.xoauth_requestor_id is included as a query parameter.