Return to Google homepage

GData Developer's Guide

Related Links

 Google Data APIs (Beta) Developer's Guide

Using the Account Authentication Proxy with the GData Client Libraries

This document describes how to use the Google data API ("GData") client libraries to connect to Google's account authentication proxy for web-based applications (known as the "AuthSub interface").

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

This document focuses on examples specific to the Java client library, but the basic approach in the other client libraries is similar.

Contents

Audience

This document is intended for programmers who want their web-based applications to access Google services on behalf of users, using the GData 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 the AuthSub interface, outside of the GData context, see Account Authentication Proxy for Web-Based Applications.

This document also assumes that you're familiar with using the GData Java client library.

Using AuthSub and GData without the client libraries

If you want your web application client to interact with a GData service using AuthSub as an authentication system, then everything you really need to know is in the AuthSub documentation. You don't need to use the GData 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.

But as usual, the GData client libraries simplify the process, handling various details for you; this document explains how.

Working with AuthSub and GData: client library examples

This section shows an example of using GData 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 whether to register your web application

As discussed in the AuthSub documentation, AuthSub can be used in two different modes. You can choose to register your web application with Google, or not register it.

Registering offers applications the following benefits:

Though unregistered mode is simpler to set up than registered mode, Google encourages you to use registered mode where possible.

If you decide to register, you'll need a key; see Generating keys and certificates for use with registered mode (below) for an example of how to acquire one.

This example works regardless of whether you register or not; we'll explain the differences as they come up.

Decide what type of token to use

You can choose to use single-use tokens or session tokens; in this example, for the sake of demonstration, we'll use a session token. As discussed in the AuthSub documentation, if you decide to use session tokens in a real web app, you'll need to manage token storage; this document doesn't cover that.

Determine the scope required

Each Google service defines the scope of capabilities that a token gives your application. Refer to the documentation for the Google service you want to access to get the appropriate scope.

In this example, we're interacting with Google Calendar's feeds, so the scope is "http://www.google.com/calendar/feeds".

If you can't find a scope in the service's documentation, you can usually guess what it should be: it's usually the root URL of the service's feeds, or of the part of the service that's made available through AuthSub.

Request a one-time-use authentication token

To acquire an AuthSub token for a given user and a given service, your application must redirect the user to the AuthSubRequest URL, which prompts them to log into their Google account. (For more information on the AuthSubRequest URL, see the AuthSub documentation.)

To construct the AuthSubRequest URL for your application, make a Java client library call as follows:

String requestUrl =
  AuthSubUtil.getRequestUrl("http://www.example.com/RetrieveToken",
                            "http://www.google.com/calendar/feeds/",
                            false,
                            true);

The getRequestUrl method takes several parameters (corresponding to the query parameters used by the AuthSubRequest handler): the "next" URL (which is the URL that Google will redirect to after the user logs into their account and grants access); the scope (as determined in the previous section); and two Booleans, one to indicate whether the token will be used in registered mode or not, and one to indicate whether the token will later be exchanged for a session token or not. The above example shows a call in unregistered mode (the first Boolean is false), for a token that will be exchanged for a session token later (the second Boolean is true); adjust the Booleans appropriately for your application.

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 your Google account; then attach the request URL to the link. For example, you could display the following string on a page:

String suggestAuthorization = "<p>MyApp needs access to your
  Google Calendar account to read your Calendar feed. To authorize
  MyApp to access your account, <a href=\"" + requestUrl + "\">log in
  to your account</a>.</p>";

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.

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

The user's browser is redirected to that URL. The servlet handling that URL should then examine the query parameters in the requested URL to retrieve the token set by Google. For example, the servlet can retrieve the token from the URL by using the convenience function getTokenFromReply from the Java client library:

String onetimeUseToken = AuthSubUtil.getTokenFromReply(httpServletRequest.getQueryString());

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 with getTokenFromReply is always a one-time use token. You can exchange this token for a session token using the AuthSubSessionToken URL, as described in the AuthSub documentation. Your application can make this exchange using the Java client library as follows:

String sessionToken = AuthSubUtil.exchangeForSessionToken(onetimeUseToken,
                                                          null);

You pass your one-time use token to the exchangeForSessionToken method, along with either null (for unregistered mode) or a private key (for registered mode), and the AuthSub interface returns a session token.

If you've registered your application and you're using registered mode, then instead of null in that method call, you have to provide your private key. To do this, you first generate a set of keys and a certificate by following the instructions in the Generating keys and certificates for use with registered mode section, below; then you read in the private key from the generated keystore (.jks) file using the getPrivateKeyFromKeystore method:

java.security.PrivateKey privateKey =
  AuthSubUtil.getPrivateKeyFromKeystore("AuthSubExample.jks", "changeme",
                                        "AuthSubExample", "changeme");

Then you can use the following code to acquire a session token:

String sessionToken = AuthSubUtil.exchangeForSessionToken(onetimeUseToken,
                                                          privateKey);

Note that you don't need to provide the other parameters required by the AuthSubSessionToken handler (see the AuthSub documentation); the client library generates the other parameters and sends them along for you.

Also note that your private key itself is not sent over the network; you pass the private key to exchangeForSessionToken, but what the client library sends to the Google service is the signature made by the private key, not the private 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. To tell the Java client library to automatically send the Authorization header (containing the session token) with each request, you call the GoogleService object's setAuthSubToken method:

googleService.setAuthSubToken(sessionToken, null);

Again, if you're using registered mode, then you provide your private key instead of null.

After you've called setAuthSubToken, you can use the standard GData client library calls to interact with the service, without having to think about the token. For details, see the client library documentation and the GData documentation for the service you're interacting with.

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

Map<String, String> info = AuthSubUtil.getTokenInfo(sessionToken, null);  

Revoke the session token

AuthSub session tokens don't expire; your client can store the session token for as long as needed.

Therefore, when your client is done using the session token, it can revoke the token using the AuthSubRevokeToken handler, as described in the AuthSub documentation.

For example, if you want to manage tokens in a traditional session-like way, then your client can get a token at the beginning of a user's session and revoke it at the end of the user's session.

To revoke a token using the Java client library, call revokeToken. Include your private key for registered mode, or null otherwise. For example:

AuthSubUtil.revokeToken(sessionToken, null);

Generating keys and certificates for use with registered mode

Applications that register with Google to use AuthSub are provided with a higher level of security. To use registered mode, however, you must first generate a set of keys and a corresponding certificate.

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 GData; you can use the same utilities to generate keys for any use of AuthSub.

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

For more information about keys and certificates, see the AuthSub documentation.

Generating keys using OpenSSL

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

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

The -sha1 parameter specifies that the key will be used to generate SHA1 signatures. The -subj parameter specifies the identity of the application that the certificate represents. The -nodes parameter specifies that the private keys will not be protected with a password. Consider protecting it with a password for additional security.

The -keyout parameter specifies the file that will contain the keys. This file contains sensitive information and should be protected and not shared with anyone. The -out parameter specifies the file that will contain the certificate in PEM format (which can be sent to Google while registering).

Generating keys using the Java keytool utility

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

# Generate the RSA keys and certificate
keytool -genkey -v -alias AuthSubExample -keystore ./AuthSubExample.jks\
  -keyalg RSA -sigalg SHA1withRSA
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

Note that "changeme" is not a good password; this is just an example.

To write the certificate to a file that can be sent to Google during registration, use the following command:

# Output the public certificate to a file
keytool -export -rfc -keystore ./AuthSubExample.jks -storepass changeme \
  -alias AuthSubExample -file mycert.pem

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.

image art

cleardot

Last modified: