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 support multiple authentication methods, 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"; if your client is a multi-user web application client, then you should choose between "AuthSub" and "OAuth"; and if your application is a gadget (for use in iGoogle or other OpenSocial containers), then you should refer to the Authentication for Gadgets section.
Note: 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.
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.
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.
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.
|
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.next parameter with a single-use authentication token appended to the URL as a query parameter named token.After you've acquired an authentication token, you use that token to create an Authorization header for each request:
Authorization: AuthSub token="yourAuthToken"
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);
If an AuthSub-authenticated Data API 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 invalid401 Token disabled401 Token expired401 Token revokedError 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.
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:
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.
Note: The Google Data APIs Client Libraries provide methods to help you use OAuth in your web application. Specifically, there are methods for constructing the acquiring a request token, authorizing the request token, and exchanging the authorized request token for an access token. The libraries also handle the necessary signing algorithms when making requests to a Google Data service. If you are working with one of the libraries, see Using OAuth with the Google Data APIs Client Libraries.
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.
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.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.oauth_callback query parameter.https://www.google.com/accounts/OAuthGetAccessToken, to exchange the authorized request token for an access token.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.
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..."
To create an oauth_signature for the Authorization header, first construct the signature "base string".
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%3D1%252FasfdZ86oJxThxJfu3Jsyr%26oauth_version%3D1.0
The base string is hashed and the resulting bytes are signed using the algorithm you specified for oauth_signature_method. 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.
If an OAuth-authenticated Data API 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 scope400 Unsupported or missing parameter400 Unsupported signature method400 Error in the request format or content400 The requested URL returned errorFor detailed information on Google's implementation of OAuth, including how to register your application and construct the necessary OAuth parameters, see these additional resources:
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.
Note: The Google Data APIs Client Libraries provide methods to help you use ClientLogin
in your installed applications. Specifically, there are methods for acquiring an authentication token, handling CAPTCHA challenges, recalling
the auth token for later use, and sending the correct Authorization header with every request. If you are working with one of the libraries,
see Using ClientLogin with the Google Data APIs Client Libraries.
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.
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 is lowercased and doesn't contain quotes around the token value (as in the case of AuthSub).
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.
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 disabled403 Account deletedIf the problem is with the authentication token, you'll receive one of the following errors:
401 Token disabled401 Token expiredError 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.
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:
If you are building a gadget using the standard Gadgets API, you can leverage a feature of the gadget platform called the OAuth Proxy to access the Google Data APIs. OAuth (described above) is an authentication standard that allows a user to access their private data in a gadget hosting service such as iGoogle, MySpace, and Orkut, or share their data with another website or gadget. The OAuth Proxy is designed to make life easier for gadget developers by hiding much of OAuth's authentication details and doing the heavy lifting for you. The Proxy is based on an open-source project called Shindig, which is an implementation of the gadget specification.
Note: The OAuth Proxy is only supported for gadgets utililzing the gadgets.* API and running in OpenSocial containers. It is not supported for the legacy gadgets API. At this time, iGoogle in the US (www.google.com/ig) is the only container that supports this feature, though other sites are beginning to develop their own implementations.
Your gadget must obtain an OAuth token before it can access a user's data. Luckily, the OAuth Proxy manages the authentication flow for you. The first time a user installs your gadget, here's what it should do:
response.oauthApprovalUrl) for the OAuth approval page. Your gadget should provide a method to launch a new window with that URL.oauth_callback page you specify. For the best user experience, use http://oauth.gmodules.com/gadgets/oauthcallback.To access one or more of the Google Data APIs, you first need to tell your gadget to use OAuth as the authentication method. Add an <OAuth> element in the <ModulePrefs> section:
<ModulePrefs>
...
<OAuth>
<Service name="google">
<Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
<Request url="https://www.google.com/accounts/OAuthGetRequestToken?
scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
<Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
</Service>
</OAuth>
...
</ModulePrefs>
In this section, only change the following query parameters:
scopescope(s) used in this parameter. In this example, the gadget will access Blogger and Calendar data. A gadget can request data for a single scope or multiple scopes (as this example does).oauth_callbackhttp://oauth.gmodules.com/gadgets/oauthcallback. The last of those options provides the best user experience when users first install your gadget. That page provides a snippet of JavaScript that automatically closes the popup window.Once your gadget has authenticated the user, accessing a Google Data API is straightforward with the Google Data APIs Javascript client library. For information on how to use the library in the OAuth Proxy, see the Using the JavaScript Client Library.
For detailed information on creating Google Data API Gadgets, including details on the OAuth Proxy, an article on how to get started, and the gadgets.* spec, see these additional resources: