English | Site Directory

Google Data APIs

Google Data APIs Authentication Overview

In most contexts, your client application will act on behalf of a particular user of a Google service. The user provides their username and password, either to your client or to the Google service; the service returns an authentication token that your client can then send to the service along with every subsequent request on behalf of that user.

The Google Data APIs use support three different authentication systems, depending on what kind of client you're writing. If your client is a standalone single-user "installed" application (such as a desktop application), then you should use the "ClientLogin" system; if your client is a multi-user web application client, then you should choose between "AuthSub" and "OAuth".

This document is intended to be a brief overview of each authentication method. For detailed information on each method, see the full Google Account Authentication APIs documentation.

See also the Google Accounts API Group for discussion on using the Google Accounts APIs.

Authentication for Web Applications

AuthSub Overview

The AuthSub interface allows a web-based application to access a Google service on behalf of a user. To maintain a high level of security, the AuthSub interface enables the application to get an authentication token without ever handling the user's account login information.

Acquiring an AuthSub token

Here is the general process to acquire an AuthSub token for a given user. For further details, see the full AuthSub Authentication for Web Applications documentation.

  1. Your web app must redirect the user to the https://www.google.com/accounts/AuthSubRequest endpoint. The URL should include a query parameter called next, with a value set to the URL on your site where the user shuould return to after the authorization process.
  2. The AuthSub system may prompt the user to log into their Google Account. Once authenticated with Google, the user chooses to share their data.
  3. AuthSub redirects the user back to the URL you specified as the next parameter with a single-use authentication token appended to the URL as a query parameter named token.
  4. In most cases, your application will exchange the single-use token for a session token.
  5. The session token can be used in subsequent interactions with the service.

Note: The Google Data APIs Client Libraries provide methods to help you use AuthSub in your web applications. Specifically, there are methods for constructing the request URL, acquiring a single-use authentication token, exchanging the single-use token for a session token, and constructing and sending a correct Authorization header. If you are working with one of the libraries, see Using AuthSub with the Google Data APIs Client Libraries.

Using an AuthSub token

After you've acquired an authentication token, you use that token to create an Authorization header for each request: 

Authorization: AuthSub token="yourAuthToken"

Accessing an authenticated Google Data API feed

Begin by following the instructions in the Using AuthSub with the Google Data APIs Client Libraries documentation to acquire a session token, using the getRequestURL, getTokenFromReply, exchangeForSessionToken, and setAuthSubToken methods. Each Google Data API has documentation providing the appropriate scope to use.

After you have called the SpreadsheetService object's setAuthSubToken method, the client library sends the token with every request, so you don't need to do anything further with the token.

The following Java code, for example, shows how to set up the SpreadsheetService object after you have acquired a session token:

SpreadsheetService myService = new SpreadsheetService("exampleCo-exampleApp-1");
myService.setAuthSubToken(sessionToken);

Errors

If an AuthSub-authenticated Google Data request fails, you may receive any of a variety of HTTP error status codes in response. If there's a problem with the authentication token, you'll receive one of the following 401 errors:

  • 401 Token invalid
  • 401 Token disabled
  • 401 Token expired
  • 401 Token revoked

Error responses may also include a WWW-Authenticate header, such as the following:

WWW-Authenticate: AuthSub realm="https://www.google.com/accounts/AuthSubRequest"

That header provides information about how and where to authenticate correctly.

Need more details on AuthSub?

For information on AuthSub, including registering your application with Google and a detailed explanation of exchanging a one-time token for a session token, see these additional resources:

AuthSub Authentication for Web Applications (full documentation)
Using AuthSub with the Google Data APIs Client Libraries
Generating keys and certificates (secure AuthSub)
Signing Requests with AuthSub (secure AuthSub)
Registration for Web-Based Applications

OAuth Overview

All of the Google Data APIs support OAuth, an open standard for authorizing the use of data in web applications. In many ways, OAuth is similar to the "registered with enhanced security" option of AuthSub. All applications making OAuth requests must upload a security certificate and register with Google. See Registration for Web-Based Applications for more information.

Acquiring an OAuth Access token

Here is the general process to acquire an access token for a given user. For further details, see the full OAuth Authentication for Web Applications documentation.

  1. Your registered web application makes a signed request for a request token at Google's endpoint, https://www.google.com/accounts/OAuthGetRequestToken. Depending on the type of HTTP request being made, the required oauth_* query parameters can either be in the body of the request, as part of the Authorization header, or in the query part of the URL. In addition to the standard OAuth parameters, you must include a scope query parameter that is appropriate for the Google Data API(s) your application will interact with.
  2. Your web app sends the user to Google's authorization endpoint, https://www.google.com/accounts/OAuthAuthorizeToken, referencing the request token and including the oauth_callback parameter. Google may prompt the user to log into their Google Account. Once authenticated with Google, the user chooses to share their data.
  3. The request token is authorized and Google redirects the user back to the URL you specified in the oauth_callback query parameter.
  4. Your web app sends a signed request to Google's access token endpoint, https://www.google.com/accounts/OAuthGetAccessToken, to exchange the authorized request token for an access token.
  5. If the request is verified, Google responds with a valid access token.
  6. Your web app uses the access token to send signed requests to one or more of the Google Data APIs. The API(s) your application can interact with will depend on the value that was set in the initial scope query parameter.

Note: Unlike the "registered with enhanced security" option of AuthSub (secure AuthSub), all OAuth interactions with Google must be digitally signed. This even applies to redirecting the user to the OAuthAuthorizeToken authorization page.

Using an OAuth Access token

After you've acquired an OAuth access token, you will use that token to create an Authorization header for each request: 

Authorization: OAuth oauth_version="1.0", oauth_nonce="8df64ace8759d52ccc5d730bc0e8af79", oauth_timestamp="1217230730", oauth_consumer_key="example.com", oauth_token="1%2FasfdZ86oJxThxJfu3Jsyr", oauth_signature_method="RSA-SHA1", oauth_signature="IdUn42Qctcnc2kXR1zKjeZIOjQkJxkk%2BqXEr..."

Accessing an authenticated Google Data API feed

The signature format for OAuth is somewhat different than secure AuthSub. First, you must construct the signature "base string" which takes the form:

GET&http%3A%2F%2Fwww.blogger.com%2Ffeeds%2Fdefault%2Fblogs&oauth_consumer_key%3Dexample.com%26oauth_nonce%3D8df64ace8759d52ccc5d730bc0e8af79%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1217230730%26oauth_token%3D%2FasfdZ86oJxThxJfu3Jsyr%26oauth_version%3D1.0

To create the oauth_signature, the base string is hashed and the resulting bytes are signed using RSA and the private key paired with the certificate which you uploaded when registering your domain. The result is base64 encoded so that it can be placed in URLs, HTTP headers, etc.

For an explanation of the necessary query parameters and how to properly construct the base string, see the full OAuth Authentication for Web Applications documentation.

Errors

If an OAuth-authenticated Google Data request fails, you may receive an HTTP 400 error. In particular, if there's a problem with the oauth_signature or request, you'll receive one of the following 400 errors:

  • 400 Invalid scope
  • 400 Unsupported or missing parameter
  • 400 Unsupported signature method
  • 400 Error in the request format or content
  • 400 The requested URL returned error

Need more details on OAuth?

For detailed information on Google's implementation of OAuth, including how to register your application and construct the necessary OAuth parameters, see these additional resources:

OAuth Authentication for Web Applications (full documentation)
Registration for Web-Based Applications
Generating keys and certificates
OAuth specification

Back to top

Authentication for Installed Applications

ClientLogin Overview

ClientLogin allows your users to log into their Google account from inside your application. The application then contacts Google with the login data and requests access to a specified Google Data API. Once the login information has been successfully authenticated, Google returns a token, which your application will reference each time it requests access to the user's account, such as to get or post data. The token remains valid for a set length of time, defined by whichever Google service you're working with.

Acquiring a ClientLogin token

To authenticate a user using ClientLogin, your client first needs to ask the user for their username and password.

The client should then send a POST request to the following URL:

https://www.google.com/accounts/ClientLogin

Include the relevant parameters in the body of the POST request, as described in the Authentication for Installed Applications documentation, including the username and password. Also use the correct service name for the particular Google Data API you are accessing.

Note: The username should be a full email address (e.g. john.doe@gmail.com)

If the request succeeds, then the response contains an alphanumeric string labeled Auth. Its value is the ClientLogin token.

Using a ClientLogin token

After a successful authentication request, use the Auth value to create an Authorization header for each request to the Google Data API:

Authorization: GoogleLogin auth=yourAuthToken

The auth parameter should be lowercase and doesn't contain quotes around the token (as in the case of AuthSub).

Accessing an authenticated Google Data API feed

As an alternative to working with the raw HTTP and XML, you can interact with a Google service using a client library. If you're using the Java client library, for example, you create a Service object of the appropriate class (such as SpreadsheetService for Google Spreadsheets), then provide the user's credentials to the Service object:

SpreadsheetService myService = new SpreadsheetService("exampleCo-exampleApp-1");
myService.setUserCredentials("john.doe@gmail.com", "mypassword");

From then on, the client library automatically supplies the authentication token with every request your client sends.

Errors

If the authenticated Google Data API request fails, you may receive any of a variety of HTTP error status codes in response. In particular, if the problem is with the account itself (rather than the authentication token as such), you'll receive one of the following 403 errors:

  • 403 Account disabled
  • 403 Account deleted

If the problem is with the authentication token, you'll receive one of the following errors:

  • 401 Token disabled
  • 401 Token expired

Error responses may also include a WWW-Authenticate header, such as the following:

WWW-Authenticate: GoogleLogin realm="https://www.google.com/accounts/ClientLogin", service="cl"

That header provides information about how and where to authenticate correctly.

Need more details on ClientLogin?

For information on ClientLogin, including a list of the necessary authentication parameters, response and error codes, and how to deal with CAPTCHA challenges, see these additional resources:

Authentication for Installed Applications (full documentation)

Back to top