OAuth Explained: A Short Case Study with Foursquare

As a developer today, be it for web, phone, desktop, or widget, you’ve almost certainly come across the need to link your work into an API of some kind. It might be a cURL request here, or some XML or JSON there; the common denominator is that the general approach to accessing restricted material has been to request it by providing a username and password along with each call to the API. What this means is that every interaction made to the particular API passes your details along with it. They’re generally encrypted in some way, but on the whole, this is lacklustre in terms of ideal security practices. Moreover, requiring the details to be recorded somewhere makes them potentially vulnerable.

OAuth is a relatively new open authentication protocol that allows secure API communication without the necessity of continually passing a username and password with each request. The idea for OAuth was conceived in 2006 by a group of individuals working on the Twitter implementation of OpenID. After reviewing both OpenID and other existing industry practices, such as Amazon Web Services API and Flickr API, it was decided that a proposal should be written for a new open protocol for application authentication. The movement quickly gathered momentum, with support heralded by Google, and in July 2007 an initial specification was drafted. We find ourselves using OAuth Core 1.0a today, with a new 2.0 spec being drafted.

How Does It Work?

Here’s a real-world example — one that you may have already come across and not even known it.

Let’s follow the OAuth path of how foursquare sends tweets on your behalf:

foursquare has initially registered themselves as an “application” with Twitter. In doing so, they’re provided with a token set called “consumer key” and its paired “consumer key secret.” These are used by foursquare in their application code and as a part of the OAuth model in generating requests.

From a user perspective, when you log in to foursquare and click the “please link my Twitter account” button, foursquare uses its consumer key to contact Twitter and generate a “request token.” You’re then provided with a special URL that whisks you off to Twitter’s website.

If you aren’t already logged into Twitter, you’ll be prompted to just like always, and then presented with a screen that asks if you’d like to provide said application with access to your account.

Clicking “Allow” tells Twitter that this app (foursquare) which has requested access using its particular consumer key should have access to your Twitter account. Twitter then redirects you back to your application (the foursquare website) with an attached coded verification string.

The foursquare application then reads the previously generated request token, and takes the returned verification to ask Twitter to generate a final token set called “access token” and “access token secret.”

Now when you perform an action on foursquare and it’s tweeted, foursquare calls the Twitter API by creating a request using its Twitter-provided consumer key and the newly stored access token for your account.

And amid all of this, your Twitter username and password are never seen, let alone stored, by foursquare.

By the way, the best graphical representation of this process I’ve found is documented here by Digg.

How Can I Implement It?

With all this talk of tokens and secrets flying back and forth, it’s likely you’ll find yourself with a blank look on your face. How the tokens are generated and in what order can seem extremely daunting. Fortunately, OAuth and others have built a wide array of tools, classes, and straight-up code that is readily available for a variety of languages. OAuth provide an excellent list of resources available through their website.

Who Currently Uses It?

Since its conception, OAuth has been widely adopted among major web services. The largest and indeed one of the protocol’s champions is Twitter, not only implementing OAuth as its primary (and soon to be only) API authentication method, but using it as the basis for its “Sign in with Twitter” service. Today, you’ll also find the protocol used by Yahoo, Vimeo, Digg, and many others.