David Janes' Code Weblog

January 25, 2009

My issues with OAuth

authentication,ideas · David Janes · 2:44 pm ·

The other day I twittered Chris Messina about OAuth:

@factoryjoe #OAuth is an incomprehensible mess. Programming a Python client to connect to a service has never been so hard

This is the details of my experience, plus suggestions about how to fix the problems I’ve encountered.

The username/password gold standard

To interact with a service like Twitter’s API, you need three pieces of information: a username,  password and an API endpoint I want to use. Once I have this information I can use a standard library in almost any language to start using the Twitter API – I am up and running within 45 seconds. Now, don’t mistake that I think giving up your username and password to a third party service is a good idea: it’s horrible. However, the other part – to be up and running within a few minutes – is critical from a programming usability point of view. No bucks, no Buck Rogers; no API users, no API usage.

It took me a day and half (albeit of scattered hours) to get OAuth to work for me. To put this in perspective, I had Google’s authentication system – including recoding urllib2 to deal with PUT and 301/302 errors – usable in about 2 hours.

What I’ve discovered is that OAuth is as almost as easy to use as HTTP Basic Authentication (the username / password scheme above); the issue is the confusing way OAuth is currently presenting information to developers. I have documented my coding experiences here and the code is freely available for use and perusal here (though you’ll really be buying into a web resources model that might not be your thing if you do).

The informational issues I had – with suggested fixes – are documented below.

Critical OAuth information is poorly packaged

This is what you need to know to access an OAuth API:

  • A “consumer key”
  • A “consumer secret”
  • An “authorization URL”
  • A “token URL”
  • An “access token URL”

Not to mention a list of API URLs that are the API end points. Note that all of these items are defined by terminology unique to OAuth and thus unfamiliar to the new developer. Now, try going to Fire Eagle and getting all of that information, and when you’re finished that head on over to PostRank to do the same. If you’re clever, it’ll take you 5 minutes but more likely (especially if you’ve never seen OAuth before) it’ll take you about 10 minutes and you’re likely to have got something wrong. Did you catch that Fire Eagle has similar looking but not quite the same URLs? Does PostRank use “http://” or “https://” for “standard request paths“? Did you know that PostRank also has two entirely different hostnames for URLs in its APIs? If you didn’t, well, you’ll probably be revisiting your lists.

Here’s what I suggest: OAuth should recommend that every OAuth Service Provider return the following JSON dictionary (in a TEXTAREA or PRE) in the place where they’re currently returning the consumer key & secret:

{
    "api_uri": [
        "http://www.postrank.com/myfeeds/",
        "http://www.postrank.com/user/",
        "http://api.postrank.com/"
    ],
    "oauth_access_token_url": "http://www.postrank.com/oauth/access_token",
    "oauth_authorization_url": "http://www.postrank.com/oauth/authorize",
    "oauth_token_url": "http://www.postrank.com/oauth/request_token",
    "oauth_consumer_key": "XXXXXXXXXXXXXXXXXXXXXX",
    "oauth_consumer_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "oauth_signature_method": "HMAC-SHA1",
    "oauth_version": "1.0"
}

That’s it: one single piece of information that can be read without difficultly by every single language modern developers use and can be copied and pasted in a single operation by the developer.

I’d almost like to note that Fire Eagle has the most useful OAuth developer documentation I’ve seen and the OAuth team should consider adopting it wholesale as their own.

The OAuth website is confusing

The front page of the OAuth website is very promising. There’s a big round button like area that says “For Consumer developers…” and another that says “For Service Provider developers…”. From there things go rapidly downhill. Neither of these items are buttons. Instead, one clicks on the “Get Started…” link, from there you examine a list of other links and then start reading about how OAuth got it’s name after the sound Blaine Cook’s college roommate’s brother’s cat used to make horking up furballs or whatever. Honestly: no one cares at this stage. What I’d like to do is click on “Consumer developers” link and start seeing a concrete example of what I need to do interact with an OAuth enable service. All the other stuff is filler.

One further point: it’d be nice to see a proper logo.

The OAuth website needs a API playground

My final recommendation is that OAuth provide on their website a live sample API Service Provider than all the libraries interact with out of the box. It’s difficult enough to get an API working without wondering whether the problem is on my side or on their side.

6 comments

  1. Your critique is right on. OAuth has been the (very) part-time side-project of a number of people, and as such hasn’t received the love it needs (particularly when it comes to easing its use by developers). Join in–let’s make this better together!

    XRDS-Simple attempts to make some of this easier (much like your proposed JSON payload), but none of the libraries really support it. Fire Eagle’s descriptor is here:
    http://fireeagle.yahoo.net/fireeagle.xrds

    (but I have a suspicion that access and authorized urls are switched there)

  2. David, I agree, OAuth is a hard ticket to sell. Having written an implementation of it in Javascript for our Firefox extension, the logic behind it is a mess! The fact that we have so many ‘intro to OAuth’ videos, tutorials, and presentations just showcases the fact that it’s actually a really hard concept to wrap your head around. I’d love to see some work on ‘humanizing’ the entire concept.

    On the subject of multiple URLs for postrank: unfortunately that’s something we couldn’t get away from in our implementation, as some of the API’s live on the main web app, and a collection of other endpoints are standalone services. XRDS-Simple could be the answer for this, as Seth has already pointed out.

  3. David Janes · 2009-01-27 16:49

    Hi Seth, Ilya!

    I see XRDS is the way to go I see, and in fact makes more sense: then the API endpoints could evolve _after_ the fact (as what happened with AideRSS). I’d put a pointer in the JSON block to that instead. Note that the “reversal” you think you see is classic case of what happens (esp. according to Tantek Celik) when you hide data in a format rather than expose it visibly where it can examined by humans.

    There’s an inherent complexity to OAuth which some cleverness can be abstracted away. See my earlier post on the subject – I found that for the most part now I don’t even have to know that it’s there. But as you say Ilya – it has to be “humanized”, even if the target is _developers_.

  4. Jarrod · 2010-02-09 01:17

    I totally agree. The OAuth documentation is some of the most poorly written and confusing technical writing I have ever read. It reads as if a bunch of developers that just wanted to try their hand at RFC drafting came together and said “Let’s make this as confusing and as disconnected as possible!”

    It is terrible.

  5. […] OAuth community has faced similar issues. If a new developer just wants to start using the Twitter API, suddenly they have to understand […]

  6. OAuth is a nightmare! Having tried to figure it out for interactions with Flickr and more recently soundCloud I’m still confused as to how I’m meant to use it. The documentation is sparse at best and even the examples provided by the companies that implement it seem to be confused as to how it should work. In the end I gave up on Flickr and I’m still trying to implement soundcloud!

RSS feed for comments on this post.

Sorry, the comment form is closed at this time.

Powered by WordPress