Google Account Authentication for Installed Application

We are considering using the unofficial Reader API to interface with Google, effectively using it as the database. In order to accomplish that, we'll need to use Account Authentication for Installed Applications:

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

It is unknown how long the token will be valid. The reader will store the email and password, which will be used for authentication as needed. Since we will be using our server for handling data between the reader and Google, the server will notify the reader to request a new token as needed.

There are four steps involved with using ClientLogin (directly from the Google page):

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


2. 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.
   
   
   The basic login request will take the form:
   
   Email=&Passwd=&service=cl&source=Asterbox-MIDPReader-0.0.1
   
   


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


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

The only time the reader will interact with Google is to authenticate and obtain the token, which is then passed to our server. Our server will act as the middle man between Google and the reader, storing user actions and resizing/converting images. The password will never be passed between the reader and our server, to reduce user security concerns.