ClientLogin for Installed Applications

ClientLogin documentation

Important: If any of your customers are having trouble with ClientLogin, their account may not be compatible with it for a variety of possible reasons. For example, accounts that use 2-step verification, SAML, or Open ID are not compatible with ClientLogin. One workaround is to tell users to generate a single-use password, provided by access codes, which allows them to log in to their account in a web browser and generate a long password that they can type into the password field of any application using ClientLogin. A better solution is to convert your app to use OAuth 2.0, which is compatible with all existing Google accounts.

Installed applications that need to exchange information with Google services protected by a user's Google or Google Apps (hosted) account can use a programmatic method for getting authorized access. Before using, verify that the Google service to be accessed supports access with the ClientLogin API. Web applications should not use this authorization method; see "Getting Started" for a list of APIs for web applications.

With programmatic authorization implemented, your users can log into their Google account and grant access to their Google service data from inside your application. The application then contacts Google with the login data and requests access to a specified Google service. Once Google authorizes access, your application can access the Google service data, allowing the user to create, read, update, or delete service data as needed using your application interface.

Authorization with the ClientLogin API is a step up from the "low-tech" approach, which required applications to include the user's login name and password in every request to a Google service. With programmatic login, Google issues a token that can be referenced in all subsequent requests. This approach offers several advantages, including:

• Performance is improved because login data is validated only once per session instead of with each request.
• Security is tightened by minimizing the number of times login data is transmitted per session.
• The authorization process can incorporate additional security measures, such as the use of CAPTCHAs™.
• Authorization measures can be more easily enhanced and extended as required.

For more secure and streamlined authorization, as well as a better user interface, we recommend using Google's OAuth API for installed applications.

This page discusses how to implement programmatic authorization using ClientLogin. See also the Google Accounts API Group for discussion on using the Accounts API. For information on Google's other account authorization solutions, see the Getting Started guide.

Audience

This page is aimed at programmers who are developing client applications that access a Google service and who want to implement a programmatic way to get authorized access to Google account information. We assume you've read up on the service(s) being accessed and are aware of the access/authorization issues involved. You need to know some service-specific details when incorporating ClientLogin. In addition, you need to know how to make HTTPS POST requests and handle responses.

Example scenario

In this scenario, you're creating an installed application that communicates with Google's Calendar service. Users of Google Calendar manage their schedules, add, update, or delete events, and share calendar information with other users. For your application, you want to be able display Google Calendar data in your interface and provide tools to manipulate the data.

To accomplish this, you need to get access to a user's Calendar account. Before you can access the account, you need to request authorization from Google. Once you've been successfully authorized and received a token, you can access your user's Calendar data, referencing the token in each request.

The ClientLogin authorization process

Authorization with ClientLogin involves a sequence of interactions between three entities: the installed application, Google services, and the user. This diagram illustrates the sequence:

1. When the third-party application needs to access a user's Google service, it retrieves the user's login name and password.
2. The third-party application then makes a ClientLogin call to Google's Authorization service.
3. If the Google Authorization service decides additional vetting is necessary, it returns failure response with a CAPTCHA token and challenge, in the form of a URL for a CAPTCHA image.
4. If a CAPTCHA challenge is received, the third-party application displays the CAPTCHA image for the user and solicits an answer from the user.
5. If requested, the user submits an answer to the CAPTCHA challenge.
6. The third-party application makes a new ClientLogin call, this time including the CAPTCHA answer and token (received with the failure response).
7. On a successful login attempt (with or without CAPTCHA challenge), the Google Authorization service returns a token to the application.
8. The application contacts the Google service with a request for data access, referencing the token received from the Google Authorization service.
9. If the Google service recognizes the token, it supplies the requested data access.

Using ClientLogin

Use this interface in your installed application to programmatically access a user's Google account. After collecting login information from the user, call ClientLogin to request access to the user's account. 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. The token remains valid for a set length of time, which is defined by whichever Google service you're working with.

Incorporating ClientLogin into your application requires these tasks:

1. Create a UI element to capture login data from the user.

   The UI needs to solicit a user name (email address including domain) and password. The UI should also be capable of displaying a CAPTCHA image using the URL received from Google, if one is required, and soliciting a correct answer from the user. Ideally, your UI will include a link to Google Accounts login page ("https://www.google.com/accounts/Login") in the event that the user needs to sign up for a new account or do other account maintenance.

2. Write code to generate a well-formed HTTPS POST ClientLogin request and transmit it.

   This code needs to contain logic to handle a CAPTCHA challenge and include both the logintoken and logincaptcha parameters. The application should also be able to detect when the user omits required information--or repeats incorrect data after a login failure--and display an error without sending a superfluous request.

3. Handle responses from Google.

   There are four possible responses to a login request:

   • success (an HTTP 200)
   • failure (an HTTP 403) with an explanatory error code
   • invalid request, generally resulting from a malformed request
   • failure with a CAPTCHA challenge

   A success response contains an authorization token labeled "Auth". This token must be included in all subsequent requests to the Google service for this account. Authorization tokens should be closely guarded and should not be given to any other application, as they represent access to the user's account. The time limit on the token varies depending on which service issued it.

   A failure response includes one or more error codes and a URL with the error message that can be displayed for the user. Please note that ClientLogin does not differentiate between a failure due to an incorrect password or one due to an unrecognized user name (for example, if the user has not yet signed up for an account). Your application needs to handle all possible error messages as appropriate.

   A failure response with a CAPTCHA challenge means that Google has decided, for whatever reason, that additional security measures should be taken. This response is accompanied by a CAPTCHA image URL and a token representing the specific CAPTCHA challenge.

4. Handle a CAPTCHA challenge from Google.

   To handle the challenge, the application must display the CAPTCHA image and solicit an answer from the user. To display the CAPTCHA image, use the value of CaptchaUrl returned with the failure response, prefixing it with the Google Accounts URL: "http://www.google.com/accounts/". Once the user provides an answer, the application should resend the login request, this time including the CAPTCHA token (logintoken) and the user's answer (logincaptcha). Google validates the user's answer before authorizing access to the account.

   There is an alternative for developers who do not want to manage the process's of getting and transmitting a user CAPTCHA response. In response to a CAPTCHA challenge, the application can direct the user to the Google hosted page: "https://www.google.com/accounts/DisplayUnlockCaptcha". Once the user has successfully responded to the challenge, the Google server trusts the computer in use. The application can then resend the original login request to obtain the authorization token.

Note: Google does not validate the login attempt prior to issuing a CAPTCHA challenge. This means a login attempt could fail even after a CAPTCHA challenge.

* CAPTCHA is a trademark of Carnegie Mellon University

The ClientLogin interface

ClientLogin uses standard security measures to protect user account information. To block bots and other entities from breaking user passwords, Google Accounts may add a visual CAPTCHA™ to the authentication process; this usually happens when the server suspects an illegal intrusion, such as after too many incorrect login attempts. A CAPTCHA ensures that a real person is trying to log in.

ClientLogin can be used to authorize access to both Google regular and hosted accounts. A hosted account is a user account that is part of the Google Apps service.

NOTE: ClientLogin does not support service sign ups or other account maintenance tasks. Users must have an existing account before using this feature. If a user tries to log in without an account, this interface returns a "login failed" response. In addition, if other account maintenance steps--such as email verification or acceptance of terms--are not completed, the login attempt fails.

ClientLogin

ClientLogin can be used with any application that can make an HTTPS POST request. The POST request should be structured as a form post with the default encoding application/x-www-form-urlencoded. Parameters should be included in the body of the post.

Action URL parameter: https://www.google.com/accounts/ClientLogin

Sample request

The first example illustrates a basic login request. The second example shows a request containing a response to a CAPTCHA challenge. Both examples are shown not URL-encoded for clarity.

POST /accounts/ClientLogin HTTP/1.0
Content-type: application/x-www-form-urlencoded

accountType=HOSTED_OR_GOOGLE&Email;=jondoe@gmail.com&Passwd;=north23AZ&service;=cl&
   source=Gulp-CalGulp-1.05

~~~~~~~~~~~~~~

POST /accounts/ClientLogin HTTP/1.0
Content-type: application/x-www-form-urlencoded

accountType=HOSTED_OR_GOOGLE&Email;=jondoe@gmail.com&Passwd;=north23AZ&service;=cl&
   source=Gulp-CalGulp-1.05&logintoken=DQAAAGgA...dkI1LK9&logincaptcha=brinmar

ClientLogin response

In response to a login request, Google returns either an HTTP 200, if login succeeded, or an HTTP 403, if login failed.

A success response contains the authorization token, labeled "Auth", in the body of the response. Your application must reference this token in each request to the Google service for this user. Additional cookies, labeled "SID" and "LSID", are not currently active and should not be used.

A failure response contains an error code and a URL to an error page that can be displayed to the user. If the error code is a CAPTCHA challenge, the response also includes a URL to a CAPTCHA image and a special token. Your application should be able to solicit an answer from the user and then retry the login request. To display the CAPTCHA image to the user, prefix the CaptchaUrl value with "http://www.google.com/accounts/", for example: " http://www.google.com/accounts/Captcha?ctoken=HiteT4b0Bk5Xg18_AcVoP6-yFkHPibe7O9EqxeiI7lUSN".

Sample responses

HTTP/1.0 200 OK
Server: GFE/1.3
Content-Type: text/plain

SID=DQAAAGgA...7Zg8CTN
LSID=DQAAAGsA...lk8BBbG
Auth=DQAAAGgA...dk3fA5N

 ~~~~~~~~~

HTTP/1.0 403 Access Forbidden
Server: GFE/1.3
Content-Type: text/plain

Url=http://www.google.com/login/captcha
Error=CaptchaRequired
CaptchaToken=DQAAAGgA...dkI1LK9
CaptchaUrl=Captcha?ctoken=HiteT4b0Bk5Xg18_AcVoP6-yFkHPibe7O9EqxeiI7lUSN

Error codes