This document describes how to use the Google Data API ("GData") JavaScript client library to connect to Google's "AuthSub for JavaScript" authentication system.
Note: If you're already familiar with AuthSub, Google's account authentication service for web-based applications, you'll see that AuthSub for JavaScript is conceptually very similar. The underlying implementation is different, but the differences aren't important to you as a client application developer. In some of the documentation, in contexts where the distinction is irrelevant, we refer to AuthSub for JavaScript as "AuthSub" for short.
The AuthSub for JavaScript interface allows a web-based application to access a Google service on behalf of a user. To maintain a high level of security, the interface enables the application to get an authentication token without ever handling the user's account login information.
The JavaScript client library provides methods to help you use AuthSub for JavaScript in your web application. In particular, there are methods for acquiring and revoking authentication tokens.
See also the Google Accounts API Group for discussion on using all the Authentication service APIs.
This document is aimed at programmers who are developing web applications, such as JavaScript mashups, that access Google services using the Google Data APIs JavaScript client library.
This document assumes that you understand the general ideas behind the Google Data APIs protocol. It also assumes that you know how to program in JavaScript. It does not assume that you're familiar with the AuthSub interface.
AuthSub for JavaScript is currently supported in Firefox 1.5 and higher and Internet Explorer 6.0 and higher.
Here's a quick summary of how communication works between a web application, the Google Authentication service, and a Google Data service:
The AuthSub for JavaScript library is included in the main GData JavaScript client library, so you don't need to do anything special to acquire the AuthSub for JavaScript library.
The following steps walk through the process of getting an authentication token and using it to access a Google service.
|
google.accounts.user.login(scope). In most cases, this single step is all that's needed to acquire a token. This function automatically checks to see if a token is already stored in the browser; if one is found, it is returned. If no token is found, a request is sent to the authentication service.
function doLogin(){
scope = "http://www.google.com/calendar/feeds";
var token = google.accounts.user.login(scope);
}
google.accounts.user.login() immediately after loading, without waiting for user interaction, then the first thing the user sees on arrival at your page is a Google login page. If the user decides not to log in, then Google does not direct them back to your page; so from the user's point of view, they tried to visit your page but were sent away and never sent back. This scenario may be confusing and frustrating to users.logout(), which revokes the current authentication token, and then call login(scope) again to acquire a new, valid token.logout(). function doLogout(){
google.accounts.user.logout();
}
The following methods make up the AuthSub for JavaScript interface, providing functionality to acquire and manage authentication tokens. All methods are called on the google.accounts.user object, which is defined in the JavaScript client library.
The logout() and getInfo() methods both rely implicitly on the "current token," which is the token associated with the scope that you specified at the last call to login() or checkLogin(). If your client is using multiple scopes, it can switch to a new scope by calling checkLogin() .
logout() or getInfo() call to.Retrieves a valid authentication token. This method first checks whether or not a cookie for the specified scope is already stored in the browser. If one is found, the token value is returned. If no cookie is found, a request is sent to the authentication service, which shows the user a Google Accounts Request Access page. If the user successfully logs in and grants access, then cookies containing scope and token are stored in the client browser, and the token value is returned to the calling function.
| Parameter | Description |
|---|---|
scope |
(required) URL identifying the service to be accessed. The resulting token enables access to the specified service only. Depending on the service, some scopes are broad, while others are very restrictive. In some cases, the scope may specify read-only access. |
Sample code:
function doLogin(){
scope = "http://www.google.com/calendar/feeds";
var token = google.accounts.user.login(scope);
}
Returns:
A token, keyed to a specific combination of user, client application domain, and Google service scope, is returned as a string.
If no valid token exists in the client browser, then the user is redirected to a Google page and invited to log into their Google account and authorize access by the web application. In this scenario, there are four possible outcomes:
Revokes the current authentication token and deletes all authentication cookies for that token stored by the browser. The Google service refuses subsequent requests for access until your client acquires a new token.
If your client application uses multiple scopes, then it should call checkLogin() to set the appropriate scope before calling logout().
Sample code:
function doLogout() {
scope = "http://www.google.com/calendar/feeds";
if (google.accounts.user.checkLogin(scope)) {
google.accounts.user.logout();
}
}
Returns:
None.
Checks whether a cookie containing a token for the specified scope exists. Also, sets the current scope to the specified scope, so that subsequent calls to logout() and getInfo() use the new current scope.
| Parameter | Description |
|---|---|
scope |
(required) URL identifying the service to be accessed. |
Sample code:
function doCheck(){
scope = "http://www.google.com/calendar/feeds";
var token = google.accounts.user.checkLogin(scope);
}
Returns:
A token, if one exists. If no token exists for the specified scope, this method returns an empty string.
Gets detailed information related to the current token, including target (the domain that originally requested the token) and scope. This method is primarily intended for debugging purposes, because this information is not needed to verify authentication. Unlike other AuthSub for JavaScript methods, this method uses a callback function to asynchronously receive the requested data.
If your client application uses multiple scopes, then it should call checkLogin() to set the appropriate scope before calling getInfo().
| Parameter | Description |
|---|---|
callback |
(required) Callback function to return information. |
Sample code:
function handleInfo(data) {
var response = eval(data.currentTarget.responseText);
alert('Target: ' + response.Target + "\n" +
'Scope: ' + response.Scope + "\n" +
'Secure: ' + response.Secure);
}
function doGetInfo() {
scope = "http://www.google.com/calendar/feeds";
if (google.accounts.user.checkLogin(scope)) {
google.accounts.user.getInfo(handleInfo);
}
}
Returns:
Token details relating to the original token request, including:
This section describes the cookies and tokens used by AuthSub for JavaScript. In most contexts, you won't need to know this information; the JavaScript client library handles all the details behind the scenes.
There are two cookies stored when an AuthSub for JavaScript login request is successful, each named with the prefix "g314":
Each authentication token is specific to the following data:
The token data ensures that only the specified third-party application can request data and that the request is limited to data from the specified scope and user account.
Only one token for this combination of scope, user, and client can be valid at any one time. A web application must request a new token each time it needs access to a new Google service for a given user. The scope of access covered by the token depends on the Google service, which may choose to limit access to certain types of data or activity, such as read-only access.
The token returned by the AuthSub for JavaScript interface can be used as many times as is needed until it is revoked. It's up to your application to manage the life of the token, balancing security with convenience. Google recommends requesting a new token each time a new session is initiated.
Some Google services may allow access only by web applications that are registered and using secure tokens. AuthSub for JavaScript is not supported for such services. To use secure tokens, you'll need to use the standard AuthSub interface (and you thus can't use the JavaScript client library for this purpose), and your organization must register an SSL certificate with Google and sign all requests for those data feeds.