Google Code offered in: 中文 - English - Português - Pусский - Español - 日本語
Google supports the OAuth protocol for authentication of web applications. 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 documentation. All applications making OAuth requests to Google must be registered and must sign all requests.
See also the Google Accounts API Group for discussion on using the Accounts API.
This document is written for web application developers who want to communicate with 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/authentication issues involved. You need to know some service-specific details when using Google's authentication proxy service.
OAuth authentication 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 Authentication.
The following methods make up Google's OAuth endpoints:
Contact Google for a request token. Google verifies that the requesting web application has been registered with Google. The request token acquired with this request must be first authorized by the end user and then exchanged for an access token; a request token cannot be used to get access to a Google service.
Send a request to: https://www.google.com/accounts/OAuthGetRequestToken with the following query parameters:
| Parameter | Description |
|---|---|
oauth_consumer_key |
(required) Domain identifying the third-party web application. This is the domain used when registering the application with Google. |
oauth_signature_method |
(required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT". |
oauth_signature |
(required) String generated using the referenced signature method. See Signing Requests. |
oauth_timestamp |
(required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT. |
oauth_nonce |
(required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks. |
oauth_version |
(optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use. |
scope |
(required) URL identifying the service(s) to be accessed. The resulting token enables access to the specified service(s) only. Scopes are defined by each Google service; see the service's documentation for the correct value. To specify more than one scope, list each one separated with a space. This parameter is not defined in the OAuth standards; it is a Google-specific parameter. |
Depending on the type of request sent, these parameters can be placed in:
For more details, see the OAuth specification, Section 5.2.
This example asks for a request token to access a user's Calendar and Picasa accounts.
POST /accounts/OAuthGetRequestToken HTTP/1.1 Host: https://www.google.com Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_consumer_key="example.com", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d65724c61686176", oauth_version="1.0" scope=http://www.google.com/calendar/feeds http://picasaweb.google.com/data
If the request for a request token is successful, Google responds with an HTTP 200 message containing a request token and a token "secret".
A token request may be rejected by Google if the request is malformed or if Google has reason to believe the requestor is not acting in good faith. If the request is not successful, Google returns the following error:
This example illustrates an OAuth request token returned in the response header. At this point, the request token cannot be used to request data from the Google service; it must be authorized by the Google Authentication service.
oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20
Call the Google Authentication service at https://www.google.com/accounts/OAuthAuthorizeToken with the following query parameters:
This example shows a request for authorization:.
https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&hd=mycollege.edu
If Google accepts the request, the user is redirected to a Google login page, where:
This example illustrates the format of a Google redirect back to the web application with an authenticated request token. The token is a text string, up to 256 bytes.
http://www.yourwebapp.com/showcalendar.html?oauth_token=CKF50YzIHxCT85KMAg
Contact Google to exchange an authorized request token for an access token. The access token received in response to this request is used to request data from a Google service.
Send an HTTP request to: https://www.google.com/accounts/OAuthGetAccessToken with the following query parameters:
| Parameter | Description |
|---|---|
oauth_consumer_key |
(required) Domain identifying the third-party web application. This is the domain used when registering the application with Google. This value must be the same as the one provided in OAuthGetRequestToken. |
oauth_token |
(required) Authorized request token. |
oauth_signature_method |
(required) Signature algorithm. The legal values for this parameter "RSA-SHA1" or "HMAC-SHA1". Google does not support "PLAINTEXT". |
oauth_signature |
(required) String generated using the referenced signature method. See Signing Requests. |
oauth_timestamp |
(required) Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT. |
oauth_nonce |
(required) Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks. |
oauth_version |
(optional) The OAuth version used by the requesting web application. This value must be "1.0"; if not provided, Google assumes version 1.0 is in use. |
Depending on the type of request sent, these parameters can be placed in:
For more details, see the OAuth specification, Section 5.2.
This example asks for an access token.
POST /accounts/OAuthGetAccessToken HTTP/1.1 Host: https://www.google.com Content-Type: application/x-www-form-urlencoded Authorization: OAuth oauth_consumer_key="example.com", oauth_token="CKF50YzIHxCT85KMAg", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d65724c61686176", oauth_version="1.0"
If the request for an access token is successful, Google responds with an HTTP 200 message containing an access token and a token "secret".
A token request may be rejected by Google if the request is malformed or if Google has reason to believe the requestor is not acting in good faith. If the request is not successful, Google returns the following error:
This example illustrates an OAuth access token returned in the response header.
oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20
OAuth access tokens can be revoked either manually or programmatically in your client app. These are th same methods provided to AuthSub.
Manually revoking a token
Programmatically revoking a token
To programmatically revoke a token, you can use AuthSub's AuthSubRevokeToken endpoint with the necessary signed OAuth request.
This section covers topics relevant to using Google's Authentication service with OAuth.
These tasks must be done when setting up your web application to use the Google Authentication service with OAuth:
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 most tightly scoped token possible. For example, if attempting to access Google's Atom feed feature, use the scope "http://www.google.com/calendar/feeds/", not "http://www.google.com/calendar/". Google services are much more restrictive with large-scope requests.
The mechanism must generate well-formed, signed token request calls and handle the responses.
If you specify an oauth_callback value on an OAuthAuthorizeToken request, the mechanism should also be equipped to parse the redirect from Google, which contains the authorized request token, and take action with it. 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.
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 Lang parameter ensures that the user is redirected back to the correct version of the site.
In certain circumstances, using the hd parameter can help streamline your users' experience when they are asked to grant access on the Google Accounts site. In most cases, the process is a simple matter of logging into their account and choosing whether or not to grant access. For users who have more than one Google Account (a regular Google account and/or one or more hosted accounts), users may need to follow the extra "universal login" process to to identify which account they wish to have accessed. If your application is designed for one particular managed domain, you can eliminate these extra steps by using this parameter to identify the domain. You can also use the hd parameter if your application accesses services that are not available on hosted accounts--setting the value to 'default' will limit authentication to regular accounts only.
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.
All calls requesting or using an OAuth token must be signed. This includes calls to OAuthGetRequestToken, OAuthGetAccessToken, and all requests made to Google services. This section describes how to generate a signature for the requests. For more detailed information on this process, see the OAuth specification, Section 9.
Each request must specify the signature method in use (oauth_signature_method). Google currently supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.
Below is an example of using the Google Calendar API to retrieve a user's list of calendars at http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime. The example assumes you have
a valid OAuth access token.
Base string:
GET&http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2Fdefault%2Fallcalendars%2Ffull&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D4572616e48616d6d65724c61686176%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D137131200%26oauth_token%3D1%252Fab3cd9j4ks73hf7g%26oauth_version%3D1.0%26orderby%3Dstarttime
Notice the orderby=starttime query parameter is ordered along with the rest of the oauth_* parameters in the base string.
HTTP Request:
GET http://www.google.com/calendar/feeds/default/allcalendars/full?orderby=starttime HTTP/1.1 Host: http://www.google.com Content-Type: application/atom+xml Authorization: OAuth oauth_token="1%2Fab3cd9j4ks73hf7g", oauth_signature_method="RSA-SHA1", oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D", oauth_consumer_key="example.com", oauth_timestamp="137131200", oauth_nonce="4572616e48616d6d65724c61686176", oauth_version="1.0"
The ordering of the oauth_* parameters does not matter in the Authorization header. Notice also that this header does not include the orderby=starttime as the base string did.
Tips for developers who are switching their authentication method from Google AuthSub to OAuth: