OAuth Explained: A Short Case Study with Foursquare

Tweet

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.

For those of you interested in the finer workings, there are plenty of articles and specification documentation available that go into detail of how the protocol communicates

Free book: Jump Start HTML5 Basics

Grab a free copy of one our latest ebooks! Packed with hints and tips on HTML5's most powerful new features.

  • Dimas

    So lets say the consumer key and access key is captured by a 3rd-party (similar to capturing a username/password) would the 3rd-party have access to your twitter account?

    • Raj

      Yes, you’re correct. With the Access Token it is extremely important to not have it hardcoded or publicly available. For web applications these are often stored outside of any public serving web folders as a security precaution.

    • Mal Curtis

      I believe the request is signed with the public access key, so it’s safe.

      The great thing with oAuth is that if an application IS compromised, you only need to remove that application from your list of allowed apps (e.g. in your twitter settings area). This is different from the old way where you would have to change your password, which at the same time would break all the other applications that you’d told your username and password to.

  • Ardent

    I really like the functionality that things like oAuth give, but as a developer I find this whole area (facebook connect, oAuth, oAuth2, openID, etc) pretty painful.

    Putting aside the often confusing documenatation, the biggest problem is it is an area where things keep changing, where if you don’t keep on top of it you can find your “login with Twitter” no longer works.

    That has led me to use things like Gigya and RPX so the headache of keeping up with API changes is with them.

  • Vivek saurabh

    Hi,
    Great article
    Just wanted to know that, this oauth thing works for mobile applications also. If yes, does it follow the same procedure as you described above.

    • Raj Deut

      Yes Vivek, all OAuth transactions will work in a similar fashion. For Applications it is slightly different in that they are unlikely to accept a “callback url” and may instead ask the user to manually return to their application.

      Twitter have the best documentation around this as well as libraries for a variety of languages to help you implement OAuth in your application. I’d start here: http://dev.twitter.com/pages/oauth_libraries