English | Site Directory

Account Authentication API

OAuth Authentication for Web Applications


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.

Audience

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.

Contents

  1. The Authentication Process
    1. Tokens and Token Management
  2. The OAuth Endpoints
    1. OAuthGetRequestToken
    2. OAuthAuthorizeToken
    3. OAuthGetAccessToken
    4. Revoking an OAuth Access Token
  3. Working With OAuth
    1. Setting Up OAuth Authentication
    2. Signing Requests
    3. Migrating from AuthSub to OAuth

The Authentication Process

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:

Authentication process

  1. The web application contacts the Google Authentication service, asking for a request token for one or more Google service.
  2. Google verifies that the web application is registered and responds with an unauthorized request token.
  3. The web application directs the end user to a Google authorization page, referencing the request token.
  4. On the Google authorization page, the user is prompted to log into their account (for verification) and then either grant or deny limited access to their Google service data by the web application.
  5. The user decides whether to grant or deny access to the web application. If the user denies access, they are directed to a Google page and not back to the web application.
  6. If the user grants access, the Authentication service redirects the user back to a page designated with the web application was registered with Google. The redirect includes the now authorized request token.
  7. The web application sends a request to the Google Authentication service to exchange the authorized request token for an access token.
  8. Google verifies the request and returns a valid access token.
  9. The web application sends a request to the Google service in question. The request is signed and includes the access token.
  10. If the Google service recognizes the token, it supplies the requested data.

Tokens and Token Management

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 OAuth Endpoints

The following methods make up Google's OAuth endpoints:

OAuthGetRequestToken

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:

ParameterDescription
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:

  • Authorization header of a GET or POST request. Use "Authorization: OAuth". All parameters listed above can go in the header, except for scope, which must go either in the body or in the URL as a query parameter. The example below uses this method.
  • Body of a POST request. Content-Type must be "application/x-www-form-urlencoded".
  • URL query part of a GET request.

For more details, see the OAuth specification, Section 5.2.

Sample Request

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

Request Token Response

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:

  • HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an unsupported signature method, or other error in the request format or content.

Sample Response

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

OAuthAuthorizeToken

Call the Google Authentication service at https://www.google.com/accounts/OAuthAuthorizeToken with the following query parameters:

Parameter Description
oauth_token (required) Request token obtained from Google.
oauth_callback (optional) URL the user should be redirected to after granting access to a Google service(s). It can include query parameters.
hd (optional) String value identifying a particular hosted domain account to be accessed (for example, 'mycollege.edu'). Use "default" to specify a regular Google account ('username@gmail.com'). This is a Google-specific parameter.

Sample Request

This example shows a request for authorization:.

https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&hd=mycollege.edu

Request Authentication Response

If Google accepts the request, the user is redirected to a Google login page, where:

  1. The user is asked to verify access to their Google account. Because it's possible for someone to have more than one Google-affiliated account (a regular Google account and one or more hosted accounts), in some cases the user also must specify which account to grant access to. There are two possible paths your users may experience:
    • If you've used the hd parameter to specify an account domain, the user is asked to log in to that account, if they aren't already logged in. (For more information on the hd parameter, see When to use the hd parameter.)
    • If you don't use the hd parameter, the user is put into a "universal login" path, which walks the user through selecting and logging into any type of Google account. Because the universal login process is still in beta, we recommend you use the hd parameter whenever possible. We're continuing to improve the user experience in this area.
  2. Once the user has selected an account and verified access, the Authentication service displays the Google Access Request page (see example). This page:
    • Informs the user that a third party wants access to their Google service.
    • Identifies both the third party and the Google service to be accessed.
    • Prompts the user to confirm that it's OK to give the third party access to their Google service.
  3. If the user denies access, they are redirected to a Google page (see example).
  4. If the user grants access, the referenced request token is immediately authorized. If a callback URL is provided, Google redirects the user to the URL specified in the web application registration. If no callback URL is provided, Google displays a simple message to the user: "The token has been authorized."

Sample Response

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

OAuthGetAccessToken

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:

  • Authorization header of a GET or POST request. Use "Authorization: OAuth".
  • Body of a POST request. Content-Type must be "application/x-www-form-urlencoded".
  • URL query part of a GET request.

For more details, see the OAuth specification, Section 5.2.

Sample Request

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"

Access Token Response

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:

  • HTTP 400 Bad Request: in the case of an unsupported or missing parameter, an unsupported signature method, or other error in the request format or content.

Sample Response

This example illustrates an OAuth access token returned in the response header.

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Revoking an OAuth Access Token

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

  1. Visit your Google Accounts settings page at https://www.google.com/accounts/
  2. Click "Change authorized websites"
  3. Revoke the token by clicking "Revoke Access" next to the appropriate domain

Programmatically revoking a token

To programmatically revoke a token, you can use AuthSub's AuthSubRevokeToken endpoint with the necessary signed OAuth request.

Working With OAuth

This section covers topics relevant to using Google's Authentication service with OAuth.

Setting Up OAuth Authentication

These tasks must be done when setting up your web application to use the Google Authentication service with OAuth:

  1. Register your web application.

    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.

  2. Set up a mechanism to manage OAuth tokens.

    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.

  3. Determine the scope required by the Google service to be accessed.

    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.

  4. Set up a mechanism to request and receive OAuth tokens.

    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.

  5. Set up a mechanism to request access to a Google service.

    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.

Signing OAuth Requests

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.

  1. Construct a signature "base string", which consists of a concatenation of three request elements:
    • The HTTP request method.
    • The base URL the request is being sent to. The URL should not include any query parameters. When signing calls to Google services, refer to the OAuth specification, Section 9.1.2, for relevant instructions.
    • A normalized string of the parameters in the request (excluding the oauth_signature parameter). This includes parameters sent in the request header or body, as well as query parameters added to the request URL. To normalize the string, sort the parameters using lexicographical byte value ordering. For more details on normalizing this string, see Section 9.1.1 of the OAuth specification.
  2. Generate an oauth_signature using the signature algorithm specified. If you're using RSA-SHA1, you need the private key corresponding to the certificate uploaded to Google during registration. For HMAC-SHA1, use the OAuth "consumer secret" value generated during registration; this value is displayed on your domain's registration page.

Example Request

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.

AuthSub to OAuth Migration

Tips for developers who are switching their authentication method from Google AuthSub to OAuth:

  • If you've already registered with Google, you do not need to re-register, but you do need to specify the signature method you'll be using to sign all requests. If you choose to use the RSA-SHA1 signature method, you need to 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.