OAuth for Beginners

For those unfamiliar with OAuth, here's a very short run-down... I'm skipping over some of the details but I think this should give you a taste for what it's all about - for a more well rounded introduction, check out this article on the OAuth.Net website.

The participants

Consumer - "weitu.googlepages.com" - that application that wants to see protected information the provider has for a user.
Provider - "google.com" - the keeper of a users protected information.
User - a user who stores protected information with the provider (say contacts in gmail)

The goal

To allow the user to give a consumer access to their data on the provider without the user having to disclose their credentials (username & password) and to allow for fine-grained control over access granted to an individual consumer - i.e. putting power in the hands of the user to revoke access when they want to, and having it only affect one consumer.

A consumer needs to be known to a provider before they can request a token.

How it works

(For this example we'll use google, for more info on the google implementation see this  thread)

The provider publishes 3 Urls for their service and documents them on their site somewhere:

• Request Token Url - https://www.google.com/accounts/OAuthGetRequestToken
• User Authorize Url - https://www.google.com/accounts/accounts/OAuthAuthorizeToken
• Access Token Url - https://www.google.com/accounts/OAuthGetAccessToken

The consumer is known to google by it's consumer key (which in the case of a google api is normally a host address, like www.test.com) and this relationship is established in a proprietary manor (i.e. it's not covered by the OAuth spec).

Getting a Request Token

The start the ball rolling the consumer makes a request to the Request Token Url, they get back some form-encoded parameters in the body of the response which contains the token information.

As an example, here's an http request to get a new request token:

And here's the response:
Notice the oauth_signature and other oauth_ etc. parameters - as part of the OAuth core specification it requires that requests be "signed" so that a provider can ensure they haven't been tampered with - this is one of the aspects my library will take care of for you (signing and verifying requests).

User Authorization

At that point the consumer now needs to send the user off to the providers site - this involves using the second of the 3 urls, the User Authorize Url... we just append the scope (required by google, identifies the service you wish to access - not part of OAuth spec itself) and the request token (CMiJx-LdFxD56bOXAQ)

Note that the User Authorize Url isn't signed like the other requests... this is because this step may be manual i.e. a user typing or copying a link into their browser or some hand held device.

In this case, google takes us to a universal login page:

Once authenticated it then takes us to a page where we can authorize the consumer to have access:

By granting access at this point the consumer can then use the last of the 3 Urls, the Access Token Url, to exchange their request token for an access token. Upon granting access a few things should happen:

• An access token should be created.
• The access token should be related to the request token.
• The currently logged in user should be associated with the access token.

The last point is important - because you're passing tokens around, rather than account names, you need to have the provider implementation record the association between the access token and the user granting access - and it should be easy for your API implementation to fetch the associated user when a protected resource is accessed.

Exchanging Tokens

Once the user has authorized the consumers access request, the consumer can then exchange their request token for an access token - generally a request token can only be used once - so if the request failed for some reason they would need to start the authorization process again from scratch.

here's the http request for exchanging tokens:

And the corresponding response from the google server:
 

Accessing a Protected Resource

Now that the consumer has an access token they can then make requests for protected resources - they just need to use the access token, here's an example of doing just that:
Obviously once the request has been validated (i.e. valid signature, valid token, valid timestamp range, nonce is unique etc.) the provider implementation needs to fetch the user associated with the access token, so it can then return the correct data back to the consumer - normally you would want to automatically associate the token's user with the current request / controller / channel so that OAuth is basically transparent (i.e. it's just like getting a request from a user who's authenticated normally).

Risks & Issues

One obvious risk is that of phishing... if the consumer sends you to a site that looks like googles authentication page, but isn't google then you're in trouble.  Of course this kind of phishing is more a general problem, then something isolated to OAuth.

Another potential risk are that some signature methods are risky/flawed to the consumer due to implementation i.e. if you have a flickr uploader winforms application, and you
use RSA-SHA1, the uploader will need to ship with the x509 certificate (including the private key) in their application ... this basically invalidates the strength of that certificate, because anyone could extract and use the private key themselves (so it's as bad as a plain text signature) - on the flip side for a website RSA-SHA1 is very strong because the private key is kept private.

DevDefined.OAuth

I have a first release of my OAuth implementation up on google code, you can read a little more about it here and the code can be found here.  It's released under the MIT license, basically do what you like with it.

The library includes both consumer and a provider implementations - test coverage is pretty poor, as it was originally put together as part of my REST presentation to the local Ellerslie .Net user group a few weeks ago, but as I work through the code and rewrite various sections in my spare time it should become a little more
robust.

If you're serious about using this code then I would suggest reviewing the OAuth core spec
1.0 and the OAuth problem reporting extensions.

The OAuth wiki and google group are also great places to learn more about OAuth.

I have not added the MonoRail examples back to the code yet - but will shortly - and will probably provide a WCF implementation as well.

I've also posted a short intro to OAuth -  OAuth for beginners - for those who are interested.

Architecture Chat was today... discussions included:

• ADO.Net Data Services shortcomings (no COUNT for starters...
  ).
  
  
• Entity Framework usability & the extensibility model (or
  lack thereof) etc.
  
• Template Engines / Domain specific languages and debug
  integration.
  
• The EyeFI
  Explore SD Card that packs both Wireless and GPS + 2GB
  storage into a single package.
  
  
• Sql Server Compressed Tables & Indexes.
  
• Thoughts around having pile-like columns in a
  database, and avoiding column-level information redundancy
  (compressed column).
  
  
• StringBuilder performance.
  
• Practical uses for BigTable (and Amazon SimpleDB etc.).
  
  
• A lot of developers don't use or even know of the yield
  operator in C#.
  

Thanks all for coming and see you in a couple of weeks.

Thanks to everyone for turning up at my REST presentation yesterday, much appreciated!

At any rate - a quick note to say that I'll tidy up the slide deck a little and post most of the examples in the next couple of days.

The OAuth code I'll publish in a week or two as a seperate open-source project...  probably on googlecode or codeplex... and I'll break out the dependencies on the Castle stack so that it'll be usable for a general range of consumer / provider implementations (i.e. vanilla ASP.Net etc.)

Oh and appologies if I was a little vague - I was running on empty (have the flu quite bad and haven't really slept all week).

Morning All.

I'm presenting on "REST with .Net" tonight at the Ellerslie .Net User Group.

More details can be found on the Ellerslie user group site.

I'll be (attempting) to cover:

• REST concepts
• RESTful WCF (webHttpBinding etc.)
• ADO.Net Data Services
• OAuth including implementing a RESTful API in Monorail leveraging OAuth.

I have a touch of the flu - so we might not make it through everything before I loose my voice :) but we'll give it a go... and I'm hoping to keep the REST & WCF section short - seeing as we had  Ron Jacobs covering that last Friday at the Auckland connected systems user group.

And tomorrow we have the Architecture Chat at 11:30, the last chat was very quiet (just 3 of us, so I didn't bother writing it up) - hopefully this week will be a little more lively - if anyone has any topic suggestions then just send me an email or comment on this post...

See you all there!