- Can I securely access the Google Data APIs to take advantage of our Google Apps services?
- Can I get a new account so that I don't have to put my username and password in the code?
- Why would I want to use OAuth?
- How do I use OAuth to access the Google Data APIs?
Can I securely access the Google Data APIs to take advantage of our Google Apps services?
Yes. As folks around the lab discover the capabilities presented by Google Apps and the APIs Google has made available through the Google Data APIs, we've received a growing number of queries about how best to use and authenticate to those APIs. The standard request is for a new, dedicated user account. Our standard response is to first take a look at OAuth and tell us if that won't work.
Can I get a new account so that I don't have to put my username and password in the code?
This is the most common question we've been getting. Our standard answer is, "No." It's not that we don't want to be cooperative. It's certainly not that we want to get in the way of things getting done. What we want is for everything to be done securely and, in many respects, more easily. Usernames and passwords, especially with the combined stores of LDAP and Google, can be difficult to manage. So-called "role" or "functional" accounts often become orphaned, and tracking down owners can be difficult. Worse, in the Google sense, they're full-fledged accounts that can be used even outside of Google. They present a security and identity management problem for the Identity Management team. And with Google's baked-in data sharing capabilities, there's little need to create yet another user account.
More importantly, they're really not the best or, longer term, easier solution. And that's the purpose of this document, to introduce you to a better, more broadly applicable approach using a relatively new authorization technology called OAuth.
Why would I want to use OAuth?
If you're writing applications that need to fetch user data from other applications, OAuth is quickly becoming the way to go. Use OAuth for your Google Data API work today, and you'll be better off when you need to start branching out beyond Google. Maybe you'll need to integrate Facebook or Twitter into your apps. Or any of the growing number of OAuth-enabled applications.
But there are Google-specific reasons that make is useful. First, the Google Data APIs provide scoped authorization to data. You can limit your applications solely to Google Docs or solely to Picasa, without concern that a lost or stolen credential will permit someone to steal all of your data. Second, Google and their Google Apps Marketplace customers rely on OAuth, so you know that Google will be investing considerable energy in support it. And if you application may be of use to other Google Apps users, you might be able to make use of the Marketplace. Finally, we still hold out hope that Google will eventually get OAuth positioned to permit us to eliminate passwords at Google entirely. You might as well be ready.
How do I use OAuth to access the Google Data APIs?
Register your "domain".
Go to Google's manage your domain section of Google Accounts. Give it the hostname of the host you plan to use to access the Google Data APIs. Follow the steps to verify it.
Take note of the OAuth Consumer Key and OAuth Consumer Secret.
Generate your tokens.
You can read Google's documentation to understand the complete 3-legged OAuth "dance". Also, these instructions are targeted at the developer with some scripts on a single machine; if you plan to have a multi-user application (web or otherwise), we recommend doing this step in a standalone application that generates and stores the users' tokens.
We have prepared a tool, encapsulated in the attached runnable Java jar file, called lbl-OAuthTokenGenerator.jar. To generate your token using this tool, you will need your OAuth Consumer Key and OAuth Consumer Secret (if using HMAC) or your the private key you used during the registration step (if using RSA). Below are two examples of using the tool to generate an OAuth access token scoped to the Google Docs List API.
OAuth tokens are bearer tokens. If you have the OAuth token and the signing information (either the token secret or the private key), you can access the data. One of the benefits of OAuth is that a user can quickly revoke access, which I've done with the access tokens granted above.
Use the token to access the API.
Next, you need to write code to access the data using OAuth. Google's best supported client libraries are Java and .NET, with Python usually just behind. The following Java code will simply list out the documents accessible to the user who authorized the token, along with a separate class to handle processing of the private key.
The following code, based on similar example code from Google's OAuth documentation, provide the readPrivateKey method needed to read a private key file.
That should give you a quick start. The OAuth space is hopping right now, with development of OAuth 2.0 coming along quickly. In addition, Google is in the process of updating their APIs and the client libraries, bringing along JSON support in addition to the current Atom format. For the most part, if you stick with the Google client libraries, your transition will likely be easier.