AuthSub in the Google Data Protocol Client Libraries

Warning: This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the Google Data APIs directory, many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see Google Accounts Authentication and Authorization.

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.

The Google Data API client libraries provide methods to help you use AuthSub in your web application. 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 signing the request.

Audience

This document is intended for programmers who want their web-based applications to access Google services on behalf of users,
using the Google Data APIs client libraries.

This document assumes that you are familiar with the AuthSub interface and the general process for incorporating
AuthSub into your web application. For a complete description of AuthSub's protocol, see
AuthSub Authentication for Web Applications.

Using AuthSub and Google Data APIs without the client libraries

If you want your web application client to interact with a Google Data service using AuthSub as an authentication system,
then everything you really need to know is in AuthSub Authentication for Web Applications.
You don't need to use the Google Data APIs client libraries if you don't want to.

Here's an outline of how your application might authenticate a user using AuthSub:

Your application constructs the appropriate AuthSub URL and then sends the user to that URL so they can log in; the AuthSub system sends the user back to the URL on your site that you specified, and returns a one-time-use token; your application optionally exchanges that token for a session token; then your application sends the token in the Authorization header with each request that the application sends to the service.

The Google Data APIs client libraries simplify this authorization process by handling various details for you. This document explains how.

Working with AuthSub and the Google Data APIs: client library examples

This section shows an example of using the Google Data APIs client library methods to follow the steps outlined in the "Working With AuthSub" section of the AuthSub documentation.

In this example, we're integrating the AuthSub interface into a web application that interacts with Google Calendar (although you don't need to know anything about Google Calendar to follow the example). The example assumes the web application is hosted at example.com.

Decide what type of token to use (session=0 or session=1)

You can choose to use single-use tokens (session=0) or session tokens (session=1).
This document will use session tokens, as they are more useful in applications that will make multiple API requests.
As discussed in the AuthSub documentation, if you decide to use session tokens in your web application, you'll need to manage
token storage yourself. This document does not cover token management. Also note that tokens requested with session=0
can't be later exchanged (upgraded) to a long-lived session token.

AuthSub can be used in three different modes, unregistered, registered,
and registered with enchanced security. The remainder of this document will refer to the last option as secure AuthSub.
Though unregistered/registered mode is simpler to set up than secure AuthSub, Google encourages you to use secure tokens
for their enchanced security.

Determine the scope of your data access

Each Google service defines a scope value which determines (and possibly narrows) a token's access to the user's data.
See the FAQ for the list of available scope values.

Since we decided to interact with the Google Calendar API, the scope should be
http://www.google.com/calendar/feeds/.

Note: Always set the scope value to the broadest URL possible unless you have need for a finer restriction.
For example, a narrower scope like scope=http://www.google.com/calendar/feeds/default/allcalendars/full will restrict the token's
access to just the allcalendars/full feed. Using scope=http://www.google.com/calendar/feeds/ will allow access to all of
Calendar's feeds: http://www.google.com/calendar/feeds/*.

Multi-scoped tokens

To create tokens that access multiple Google Data APIs, seperate each scope with a url-encoded space. The example below creates a token
which will have access to both a user's Google Contacts and Google Calendar data.

After constructing the "next" URL, your application can use it in a variety of ways to send the user to the
AuthSubRequest handler. The most common approach is to display a page that tells the user that they need to follow a link to
authorize your application to access their Google account; then attach the request URL to the link. For example, you could output the following
string in your web app:

The user follows the link to the AuthSub page at Google, and logs in. The AuthSub system then redirects the user back to your application, using the "next" URL you provided.

Extract the single-use token

When Google redirects back to your application, the token is appended to the "next" URL as a query parameter. In the case of the examples
above, after the user logs in, Google redirects to a URL like http://www.example.com/RetrieveToken?token=DQAADKEDE.
Your application should extract the token value from its URL query parameter.

If your application set an authentication cookie in the user's browser before sending them to the AuthSub system, then when Google redirects back to the "next" URL, your application can read the authentication cookie to recognize which user has arrived at that URL. You can use such a cookie to associate a user ID in your application with the AuthSub token retrieved from Google.

Request a session token

The token you retrieve from the URL is always a single-use token. The next step is to upgrade that token for a long-lived session token using the AuthSubSessionToken URL, as described
in the full AuthSub Authentication for Web Applications documentation. If you are using secure AuthSub, you'll need to set your RSA private key before
making the exchange. Here are some examples using each of the client libraries:

Note: The process is the same for secure AuthSub as long as you have used
gdata.auth.extract_auth_sub_token_from_url(url, rsa_key=rsa_key)
to extract the single-use token.

Note: When using secure AuthSub, your private key itself is not sent over the network. The client libraries send the unique signature generated by signing the request with your key, not the key itself.

Use the session token

You can use the session token to authenticate requests to the server by placing the token in the Authorization header,
as described in the AuthSub documentation.

After you've set your session token, you can use the standard Google Data APIs client library calls to interact with the service,
without having to think about the token. For details, see the client library documentation and the Google Data APIs developer guide for
the service and language you're interacting with.

Retrieving information about a session token

If you want to test that your client and the server agree on the token's parameters, you can pass the token to the
AuthSubTokenInfo handler, which returns a set of name-value pairs containing information about the token.

Generating a self-signing private key and public certificate for use with secure AuthSub

The private key is used to generate a signature, which must be included with each request. The public key embedded in the certificate is used by Google to verify the signature. The public key must be a 1024-bit RSA key encoded in an X.509 certificate in PEM format. The certificate should be sent to Google at time of registration.

The following sections provide examples of how to generate keys and certificates using two particular tools: the OpenSSL utility and Java's keytool utility.

These examples are not specific to the Google Data APIs; you can use the same utilities to generate keys for any purpose.

The examples assume that your company is named My_Company, and is located in Mountain View, California, US, with domain name example.com.

Generating keys using OpenSSL

To create a pair of RSA keys and the corresponding certificate, you could use the following command:

The -dname parameter specifies the identity of the application that the certificate represents. The -storepass parameter specifies the password to protect the keystore. The -keypass parameter specifies the password to protect the private key.

To write the certificate to a file that can be used in the ManageDomains tool, use the following command: