My favorites | English | Sign in

Account Authentication APIs

OAuth Authentication for Web Applications


Google supports the OAuth protocol for authenticating 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. All applications making OAuth requests to Google must be registered and 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 authentication processes, minimizing the round-trip communication required for authentication—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.

Audience

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/authentication issues involved. You need to know some service-specific details when using Google's authentication proxy service. This document also assumes you have a basic familiarity with OAuth.

Contents

  1. The Authentication Process
    1. Tokens and Token Management
  2. OAuth Endpoints
    1. OAuthGetRequestToken
    2. OAuthAuthorizeToken
    3. OAuthGetAccessToken
  3. Working With OAuth
    1. Setting up OAuth Authentication
    2. Signing Requests
    3. Testing and Debugging OAuth requests
    4. Revoking an OAuth Access Token
    5. Migrating from AuthSub to OAuth
  4. OAuth for Google Apps Domain Administrators BETA
    1. Enabling 2-legged OAuth on your hosted domain

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 puts the scope in the body of the request.
  • Body of a POST request. The content type must be "Content-Type: application/x-www-form-urlencoded".
  • As URL query parameters in 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 OK message containing an OAuth 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 oauth_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 url-encoded 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.
hl (optional) An ISO 639 country code identifying what language the approval page should be translated in (for example, 'hl=en' for English). The default is the user's selected language. This is a Google-specific parameter.
btmpl (optional) Forces a mobile version of the approval page. The only accepted value is "mobile". This is a Google-specific parameter.

Sample Request

This example shows a request for authorization:

GET 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. The content type must be "Content-Type: 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"

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

Access Token Response

If the request for an access token is successful, Google responds with an HTTP 200 OK message containing an OAuth 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

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:

  • 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.

  • 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.

  • 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.

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

    The mechanism must generate well-formed, signed token request calls and handle the responses for the following sequence:

    1. Get a request token (OAuthGetRequestToken)
    2. Get the request token authorized (OAuthAuthorizeToken)
    3. Exchange the authorized request token for an access token (OAuthGetAccessToken)

    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.

    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. 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.

  • Implement federated login. (optional)

    If you're implementing federated login, you may want to use the hybrid protocol to combine the two authentication processes. With OpenID+OAuth, the tasks of getting a request token and authorizing it are handled using 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.

    Note: Federated login is not currently supported for Google Apps (hosted) accounts. Because token authorization is handled through OpenID, using the hd parameter is not an option.

  • 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 /accounts/OAuthGetRequestToken, /accounts/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. This 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 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.

Signature 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 /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"

Note: The Authorization should be contained on a single line. Newlines have been inserted for clarity only. The ordering of the oauth_* parameters does not matter in the Authorization header.

Testing and debugging OAuth requests

Google's OAuth Playground tool helps to debug problems, check your own implementation, and experiment with the Google Data APIs.

  • Illustrates the OAuth authentication flow:
    • Fetches a request token
    • Authorizes a request token
    • Upgrades the token to an access token.
  • Helps with debugging OAuth requests:
    • Displays the correct signature base string for each request.
    • Displays the correct Authorization header for each request.
    • Demonstrates how to use an oauth_token to interact with an authenticated Google Data feed.
    • Tests your own oauth_consumer_key (your registered domain), RSA private key, and HMAC consumer secret.
  • Lets you experiment with the Google Data APIs:
    • Uses GET, PUT/POST, or DELETE to manipulate data.
    • Allows you to view an authenticated feed directly in your browser.
    • Identifies what Data feeds are available to your oauth_token.

More debugging tips are available in Using OAuth with the Google Data APIs.

Revoking an OAuth Access Token

OAuth access tokens can be revoked either manually or programmatically.

Manually revoking a token (for Google account holders)

  1. Users can make changes to their Google Accounts settings at https://www.google.com/accounts/ . For Google Apps hosted domain accounts, go to https://www.google.com/a/yourdomain.com/ManageAccount.
  2. Click the link "Change authorized websites".
  3. In the list of authoized domains displayed, locate the domain to be revoked. Click the "Revoke Access" link next to the domain name.

Access to the user account for that domain will no longer be allowed. Users must explicity approve subsequent access requests, using the same process as they originally granted access.

Programmatically revoking a token (for third-party applications)

To programmatically revoke a token, send a request to AuthSub's AuthSubRevokeToken endpoint with the necessary signed OAuth request.

Migrating from AuthSub to OAuth

Here are some 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.

Differences between the two protocols are dicussed in the Using OAuth with the Google Data APIs article.

OAuth for Google Apps Domain Administrators BETA

While OAuth authentication 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.

2-legged OAuth allows domain administrators to create or customize third-party applications (controlled by their organization) to access their users' Google Data without their direct involvement or authorization. Specifically, an access token is not required as per the normal authorization flow, also referred to as 3-legged OAuth.

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.

Enabling 2-legged OAuth on a Hosted Domain

  1. Configure your hosted domain to accept 2-legged OAuth requests.

    Go to the Google Apps administrative control panel for your domain, click on the 'Advanced tools' tab, and go to the Manage OAuth Access section (see example). Check the box "Enable Two-legged Auth".

  2. Set up your data request mechanism to make 2-legged OAuth requests.

    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 adminstrative 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.

Note: This feature is only available to Google Apps Premier and Education Edition domain adminstrators.

Example: Accessing a Google Data API feed

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:

  • The oauth_token query parameter should not be included with the request.
  • The xoauth_requestor_id is included as a query parameter.
  • The request will only succeed if 2-legged OAuth has been enabled for the domain.