Google provides two ways for authenticating third-party applications against Google services:

  • AuthSub
  • ClientLogin

AuthSub is aimed to third-party web applications that may need to access an user Google service, such as Google Calendar{#bv.7}, Picasa Web Albums{#nh_g}, or other Google services. AuthSub authenticates an user via a proxy web page. Only when the service is about to use, the user is redirected to a Google’s authentication page for typing their credentials. Once the user has successfully logged in, the browser is redirected back to our web application.

On the other hand, ClientLogin was thought as an authenticating mechanism for standalone desktop applications, where redirecting to a web page may not be possible or does not make much sense. Users must rely on third-party applications to handle their Google user-name and password safely.

Let’s leave AuthSub aside and take a look at ClientLogin and how it works. First of all, before interacting with a Google service it is necessary to be authenticated against that precise service. ClientLogin is the mechanism we are going to use to do it so. It needs at least four parameters:

  • Username, your Google’s account user-name (without @gmail.com)
  • Passwd, your Google’s account password.
  • service, the name of the Google service you want to use.
  • source, and identifier for an application, composed of the following values: “Plugin – Application name – Version“;

Let’s compose an HTTP frame for authenticating against Picasa Web Albums

curl https://www.google.com/accounts/ClientLogin 
-d Email=john.edwards 
-d Passwd=newfoundland 
-d source=Google-cURL-Example 
-d service=lh2

If the authenticating process is success, that means, we got a 2XX status code back, the result would look something like this:

SID=DQAAAHwAAAB5Of1UNiExDVXQXhdZYcEafL_VnoCS8JzvZfAKjdWm__v_Ns5ncw_pahEEsB7-r5nZmMsZyKHllSSxURV0k581VkzxHwxwvdy39nhRCTpBI1QhQOCSGvKH1tWufxZxqOxrUpS4x_hVLvfpbz7RjEO-8E7r37O6qOA3kfQK_pCVw
LSID=DQAAAH4AAAA1mBxyaM1-CjE8v3BiOEqXGVFBkQco_Z-c82rLBGNnxzy2bM9DI7riWv3-BTcqgoz7XCUum1i9yYCJSh4UHjI_v3_Kqy_N_Tx6j4ricwI5cCYcMRQ-2C8nTKLQ17NtJEwd_Zm382DgS9-ryYXjfK05Lslj7nbl6a0TS4GZgTFbg
Auth=DQAAAH4AAAA1mBxyaM1-CjE8v3BiOEqXGVFBkQco_Z-c82rLBGNnxzy2bM9DI7riWv3-BTcqgoy1o9YW9tnUd98s3ILVDfUAILHfuqZsYWUbkiSAml2wsXNZJ8RMu8X6Jjigm4bPQEIjiR3nzV7mguDFIoEGRoiWAzUocy7PZU-BSNoLwP4Sg

As an outcome, we got three cookies or tokens. Among these three, the cookie labeled Auth represents the authentication token we are interested in, and should be used here after in every further interaction with the service. SID and LSID cookies are not currently active and should not be used (which is partly true, more on this in a coming post).

Several things to highlight before continuing:

  • In general, while interacting with web services or composing hand-made HTTP frames is always a good idea to turn **WireShark{#z:ee} ** on for debugging.
  • Notice that every Google service has its own identifier. In the example above, “lh2″ identifier stands for Picasa Web Albums service. A more detailed list of Google services and its *code names *can be found on this post: “Google Account Services Names”{#m4c-}. Whenever we need to interact with a Google service is necessary to authenticate against that Google service. Right now, there is not such thing as single-sing-on mechanism for interacting with all Google services.
  • Parameters are case-sensitive, both Email and Password start by a capital letter, whereas source and service are lowercase.
  • About the* -d* modifier, indicates the name and value of an element in a HTML form. If you want to learn more about how to compose HTTP frames with cURL check the following article: “The Art of HTTP Scripting”{#lfip}.

Once we got a valid Auth token, we can start using the service. All Google services work in a similar way. In general, we can perform any CRUD{#r900} (Create-Read-Update-Delete) operation over them, in a Restful style, thanks to the most common HTTP methods: GET (for reading), POST (for creating), PUT (for updating) and DELETE (for erasing).

Let’s request a list of albums from my Picasa Web Albums account.



curl --silent -X GET http://picasaweb.google.com/data/feed/api/user/pinowsky?kind=album | tidy -xml -indent -quiet

Usually for reading operations there is no need to authenticate in before-hand neither providing any Auth token in the HTTP frame.

On the contrary, managing operations such as creating new data, deleting or updating, need an Auth token. Let's compose an HTTP frame using the Auth token retrieved in  the first step. This operation will create a new album, together with its description, in my Picasa account.

curl --silent -X POST --data "@album_entry.xml" --header "Content-Type: application/atom+xml" --header "Authorization: GoogleLogin auth=DQAAAIAAAACQCCOvLjNU4y6zYclO4t75sjAWtWxx3C6OdYbMz3WXjn6rux_Jb3O25xzy5RCktrwH4oB2rKe3SsPq81ee2Pnv2VkPO_XrKYeuIP4dIqyuCsrlg1c4bZ4f5zTXD6GcMSTYfpts8KwR4m4Bn1x5siTq7ERpgXxqrOvZameELOhFEw" "http://picasaweb.google.com/data/feed/api/user/pinowsky" | tidy -xml -indent -quiet

where album_entry.xml is a file containing an album description in GData{#dzw9} file format (as for the XML format of entries, GData is strongly based in Atom plus a customized set of tags added by Google). Check the Picasa Web Album Data API{#yt-8} documentation for further information. 

<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:media='http://search.yahoo.com/mrss/'
xmlns:gphoto='http://schemas.google.com/photos/2007'>
<title type='text'>A day at the opera</title>
<summary type='text'>Funny pictures taking on the Faemino and Cansado show last December.</summary>
<gphoto:location>Vigo</gphoto:location>
<gphoto:access>public</gphoto:access>
<gphoto:commentingEnabled>true</gphoto:commentingEnabled>
<gphoto:timestamp>1361289600000</gphoto:timestamp>
<media:group>
<media:keywords>theater, show, humour</media:keywords>
</media:group>
<category scheme='http://schemas.google.com/g/2005#kind'
term='http://schemas.google.com/photos/2007#album'></category>
</entry>

Lastly, let’s delete the album entry we just created.



curl -s -X DELETE --header "Authorization: GoogleLogin auth=DQAAAIAAAACQCCOvLjNU4y6zYclO4t75sjAWtWxx3C6OdYbMz3WXjn6rux_Jb3O25xzy5RCktrwH4oB2rKe3SsPq81ee2Pnv2VkPO_XrKYeuIP4dIqyuCsrlg1c4bZ4f5zTXD6GcMSTYfpts8KwR4m4Bn1x5siTq7ERpgXxqrOvZameELOhFEw" "http://picasaweb.google.com/data/entry/api/user/pinowsky/albumid/5234863202168634657"


where 5234863202168634657 stands for the albumid.

In a nutshell, Google provides a Data API for many of their services. It is possible to use most Google services in a programmatic way. Before using any service, it is necessary to authenticate against it. If we were success, this authentication process will provide an Auth token as a result. This token would be needed later on for interacting with the Google service we just authenticate against. It is important to notice, there are two valid methods for retrieving an Auth token: AuthSub and ClientLogin. As a rule of thumb, use AuthSub for web applications, and ClientLogin for standalone applications. Remember, whenever interacting with a service, especially when creating new data, modifying it, etc it is necessary to embed a valid Auth token as a header in the HTTP frame. The Auth token must be present for every interaction. Auth tokens cannot be shared among different services, every service requires its own valid Auth token.

The AuthSub authenticating process is fully described in the following link: “AuthSub Authentication fow Web Applications”{#x1mf} , whereas  more detailed information about ClientLogin can be found here: “Authentication for Installed Applications”{#y9zc}.