Authentication for Installed Applications

Developers of installed applications have the option of using a programmatic login method to access Google services protected by user login. An installed application is installed on a device, such as a desktop computer or a cell phone, as opposed to a web application. Programmatic login is available when accessing services that support the Account Authentication service.

With programmatic login implemented, an application's user can log into their Google account from inside the application. The application then contacts Google with the login data and requests access to a specified Google service. Once access is authorized, the user can create, read, update, or delete service data as needed using the application interface.

Programmatic login and authentication is a big 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 supplies the application with 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 authentication process can incorporate additional security measures, such as the use of CAPTCHAs™.
Authentication measures can be more easily enhanced and extended as required.

This page discusses how to implement programmatic login using ClientLogin. See also the Google Accounts API Group for discussion on using the Accounts API.

The ClientLogin Interface
Using ClientLogin

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 log into Google accounts. It assumes you've read up on the service(s) being accessed and are aware of the access/authentication issues involved. You will need to know some service-specific details when incorporating ClientLogin. In addition, you will 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 provides tools to manipulate the data.

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

The ClientLogin Interface

Use this interface in your installed application to programmatically log into Google accounts. After collecting login information from a user, call ClientLogin to request access to the user's account. Once the login information has been successfully authenticated, Google will return 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.

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 when the server suspects an illegal intrusion, such as after too many incorrect login attempts. A CAPTCHA ensures that a real person is attempting login, and not a computer trying random strings (a "dictionary" attack).

ClientLogin can be used to authenticate both Google and hosted accounts. A hosted account is a user account that is part of the Google for Your Domain 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 will return 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 will fail.

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.

For the action URL parameter, use:
https://www.google.com/accounts/ClientLogin

Parameters

Parameter	Description
`accountType`	Type of account to be authenticated. Possible values are: GOOGLE (authenticate as a Google account only) HOSTED (authenticate as a hosted account only) HOSTED_OR_GOOGLE (authenticate first as a hosted account; if attempt fails, authenticate as a Google account) Use HOSTED_OR_GOOGLE if you're not sure which type of account needs authentication or want to avoid soliciting information from the user. If the user information matches both a hosted and a Google account, only the hosted account will be authenticated.
`Email`	User's full email address. It must include the domain (i.e. johndoe@gmail.com).
`Passwd`	User's password.
`service`	Name of the Google service for which authorization is requested. Each service that uses Google accounts is assigned a name value; for example, the name associated with Google Calendar is 'cl'. This parameter is required when accessing GData services; in this case, the generic service name "xapi" can be used. For specific service names, refer to the service documentation.
`source`	Short string identifying your application, for logging purposes. This string should take the form: "companyName-applicationName-versionID"
`logintoken`	(optional) Token representing the specific CAPTCHA challenge. Google supplies this token and the CAPTCHA image URL in a login failed response with the error code "CaptchaRequired".
`logincaptcha`	(optional) String entered by the user as an answer to a CAPTCHA challenge.

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

	Email=johndoe@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;=johndoe@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 will return either an HTTP 200, if login succeeded, or an HTTP 403, if login failed.

A success response contains the authentication 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 will contain 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 will also include 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

Error Code	Description
BadAuthentication	The login request used a username or password that is not recognized.
NotVerified	The account email address has not been verified. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application.
TermsNotAgreed	The user has not agreed to terms. The user will need to access their Google account directly to resolve the issue before logging in using a non-Google application.
CaptchaRequired	A CAPTCHA is required. (A response with this error code will also contain an image URL and a CAPTCHA token.)
Unknown	The error is unknown or unspecified; the request contained invalid input or was malformed.
AccountDeleted	The user account has been deleted.
AccountDisabled	The user account has been disabled.
ServiceDisabled	The user's access to the specified service has been disabled. (The user account may still be valid.)
ServiceUnavailable	The service is not available; try again later.

Using ClientLogin

Incorporating ClientLogin into your application will require these tasks:

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 URL links to the Google service to be used, in the event that the user needs to sign up for a new account or do other account maintenance.
Write code to generate a well-formed HTTPS POST ClientLogin request using the login data 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.
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 authentication token labeled "Auth". This token must be included in all subsequent requests to the Google service for this account. Authentication cookies 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 will need to handle all possible error message 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.
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 will validate the user's answer before authorizing access to the account.

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.

There is an alternative for developers who do not want to manage the processs 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 will trust the computer in use. The application can then resend the original login request to obtain the authentication token.

* CAPTCHA is a trademark of Carnegie Mellon University

Account Authentication

Authentication APIs

Resources