I've been doing a fair amount of work with OAuth and OpenSocial for Freebase recently. Its been interesting to learn about the differences between 2-legged OAuth (aka Signed Fetch) and 3-legged or "normal mode" OAuth.
Essentially, normal 3-legged OAuth facilitates permissions delegation between an application which wants to do something on your behalf and a web service provider without any existing trust relationship. It is a way for a third party application to use your account at some other site on your behalf. In the case of Freebase, it allows third party applications to write to the system using your account - without having to give them your username and password.
2-legged OAuth is actually a lot simpler. Actually I don't really see why its called OAuth at all - its an unfortunately little-documented variation with completely different parameter names. That's probably why it is better known as "signed request" or "phone home" among Open Social developers. Indeed, the Open Social documentation for the gadgets.io.makeRequest() function is pretty clear that signed authorisation is NOT OAuth, but merely uses the signing method outlined in section 9 of the OAuth specification.
2-legged OAuth implies a pre-arranged trust relationship between actors (typically OpenSocial hosts (or "containers" ) and API providers). The OpenSocial container proxies the user's request, cryptographically signing it with HMAC-SHA1 or RSA-SHA1, depending on the specific container. The API provider who receives this request must already share a secret with the container (in the case of HMAC-SHA1) or have a copy of the container's public X509 cert (in the case of RSA-SHA1) in order to verify the signature - hence the pre-existing trust relationship. Because of this pre-existing trust relationship, the "prompt user to allow permissions" step can be skipped.
2-legged OAuth uses a quite different set of parameters compared with normal 3-legged OAuth. For example, there is no xoauth_requestor_id parameter nor is there an oauth_token parameter. Instead, you will want to use the various Open Social parameters - opensocial_viewer_id, opensocial_app_id and opensocial_owner_id. Furthermore, the values of oauth_consumer_key is the name of the signing site.
The best documentation I have found on accepting these 2-legged OAuth or "signed fetch" requests is over at the OpenSocial Wiki, specifically the pages titled introduction to signed requests and validating signed requests. Also the Open Social documentation
It is a bit tricky to support both 3-legged OAuth and 2-legged OAuth modes.
Niall O'Higgins is an author, event organizer and software consultant. He wrote the book MongoDB and Python, published by O'Reilly. Events he organizes include We Have Tablets, the #1 Bay Area Tablet Computing Meet-up and PyWebSF. He also offers consulting services for Mobile, Tablet and Cloud Computing.
