For any of you that follow me on Twitter you probably know that I've been doing a lot with social data that comes from places like Twitter, Foursqaure, LinkedIn, and Facebook for my wow.ly project (and for those of you that don't, you do now).
Anyway, with the exception of Facebook, most of these services now support OAuth as a way of granting access to their services on behalf of their users (and facebook is rumored to be implementing OAuth soon).
If all these services agree to use the same process for 'vouching' for a user, it *should* make it much easier for developers to interact and bulid for all the various services...but, like any early stage thing, there's still a bit of confusion on just what OAuth is and especially how the various services interpet and implement the specification.
To make things a little bit worse, since many of these services are short-staffed and overloaded with requests, they don't spend a lot of time working on documentation for the developers and their API (they have more important things to worry about like their own actual users)...so often times, the best you get is "we implemented OAuth according to the specification" with a pointer to the official OAuth specification.
Seems like that would be good enough right? Well there's actually a lot of problems with that approach (all of which I won't get into right now) but probably the most frustrating thing from a developers stand point is that it doesn't do anything to help us understand which 'optional' features of the specification were or were not implemented...or, god forbid, if for some proprietary reasons you strayed slightly here or there from the specification (or maybe just interpreted the specification in a different way than I would).
Long story short is that it leaves a lot of research, hacking, and testing up to the developer to 'figure out'...but that's OK cause we developers love doing that stuff right?
Anyway, as I mentioned I've been doing a lot of the above mentioned research, hacking, and testing lately...and based on my own experiences and frustrations I thought maybe it would benefit a few others if I took a few minutes to explain some of the tips and tricks I've managed to figure out.
First, I think it's important to really understand the 'conversation' that's going on with OAuth...so I'm going to attempt to outline that for you in plain English (if I find time, I'll dig into actual 'technical' details with code examples in a future post).
OAuth - The conversation
OAuth is really a 'vouch for' system that involves three parties (in this example, 'my cool app', 'twitter', and 'random user who is really awesome cat')...but before the dance can start, two of the parties need to agree they can rely on each other for this 'vouch for' system...so when you first create 'my cool app', you'll have a quick conversation with 'twitter' that goes something like this:
My Cool App: Hey Twitter you seem to know everyone, can I ask you to vouch for people sometimes?
Twitter: Sure. Let's use this 'key' and this 'secret' when we're talking about people so I know it's for you.
Once you've done this initial conversation, you'll have a key and a secret as defined by the service you want to use to 'vouch for' people...so you'll be all set to have the real conversation involving users...each time it will go a little something like this:
My Cool App: Hey Twitter, it's 'my cool app' again, I'm thinking about sending over someone that says they know you is that ok?
Twitter: Sure. Send them over with this 'one time key' so I know they came from you.
My Cool App: Hey 'random visitor', you want Twitter to vouch for you?
Random Visitor: Yeah, Twitter loves me, let's do that.
My Cool App: OK, go to Twitter and make sure you use this 'one time key' so they know I sent you.
Random Visitor: Hey Twitter, 'my cool app' sent me with 'one time key'...can you tell them I'm really 'awesome cat'?
Twitter: Sure. You know 'my cool app' will have access to your Twitter account data right? Is that ok with you?
Awesome cat: Yes.
Twitter: Hey 'my cool app', 'awesome cat' says you sent him and he wants to give you access to his Twitter account. If you do want to access his Twitter account, just use this 'user key' and 'user secret' with future requests for them.
My Cool App: OK Great, I better store 'user key' and 'user secret' somewhere where I won't forget them then...thanks!
And that's it...at this point, you've now got Twitter telling you who this person is and granting you to act on their behalf within the Twitter system (if you want)!
Like I mentioned before though, each service does seem to implement the OAuth specification at least a little different...so let me quickly point out where the 'conversation' is different in foursquare (it's really just one small line):
...
Foursquare: Sure. Send them over with this 'one time key' so I know they came from you and when I send them back, I'll use this 'one time secret' so you know it's really me 'vouching for' them.
...
Notice the difference there in italics? In Twitter's case, they don't bother to worry about 'my cool app' knowing it's them actually doing the 'vouching for'...in Foursquare they do. (BTW this means technically foursquare is more in-line with the current official OAuth specification)
What this 'small' difference means on the technical side of things is that when you'll get two values back when you first contact foursquare to 'vouch for' someone...the first 'oauth_token' needs to be sent back to them so they know it's you...the second 'oauth_token_secret' is part of the key they'll use to check the signature you generate (which of course means, you'll also need to use it to generate the signature you send them when requesting your access_token).
That's it for now
So that's my basic understanding/explanation of the 'conversation of oauth' as they relate to Twitter and Foursquare (and the basics for other services as well)...not sure if it helps anyone else, but getting a clearer picture of this flow really helped me to debug and dechiper the specification and the various implementations of it so far.
If I have time in the near future (and no one beats me to it), I'll do a more 'technical' write up of this process with code examples for Twitter and Foursquare using nothing more than php5 and cURL...in the meantime if you're still struggling to get one or the other working and need some starter code to hack with, feel free to drop me an email, ping me on twitter, or post a comment below!
