A simpler Ruby OAuth library
Ruby
Switch branches/tags
Nothing to show
Pull request Compare This branch is 2 commits ahead of zmalltalker:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
lib
test
.gitignore
History.txt
Manifest.txt
README.textile
README.txt
Rakefile
TODO
oauth-simple.gemspec

README.textile

A simple, yet powerful, Ruby OAuth library

This library provides OAuth functionality from Ruby. It is based on the Python OAuth library – but is intended to be more or less API compatible with the Ruby OAuth GEM

Differences from the oauth gem

I have made a few contributions to the Ruby OAuth gem, including support for Ruby 1.9. When working with the library, I found it a little too abstracted from the OAuth protocol, which is very simple. While the Ruby OAuth gem provides a very clean API I found it hard to extend the code, as most of the OAuth protocol details are scattered around the codebase. This said, the Ruby OAuth gem is a very nice piece of code, but the coding style is not quite to my liking.

The Python OAuth library, on the other hand, lives in a single file, defining a few classes:

  • a Request class
  • a Token class
  • a few Signature classes

… and that’s all OAuth really is. So I ported the Python code to Ruby, learning the OAuth spec in the process. Then I started (but didn’t finish yet) building wrappers around these basic concepts to provide the same API that the Ruby OAuth gem provides. If you’re anything like me, you’ll enjoy knowing what actually happens behind the scenes, when you need to use OAuth for not so common use cases.

Protocol specs

The OAuth protocol spec covers how you build the parameters needed to connect to an OAuth service:

  • Obtaining a Request Token
  • Generating a URL for authorization from a Request Token
  • Obtaining an Access Token after the user has authorized your access to his data

On a very high level, this happens as follows:

  • Your application, the Consumer, shares a key (public) and a secret (private) with an OAuth provider site
  • Using this key and secret, you send a HTTP request to the provider, asking for an access token. This is done by generating a timestamp and a nonce in your code (along with your key and any other parameters), signing this with the secret, and providing this either as a HTTP header, in the query string or in the postbody of the HTTP request. The OAuth provider will respond with a string containing a second key and secret that represent a Request Token
  • Using this token, you can build a URL you make sure your user visits in order to authorize your access to his data on the provider site
  • Once this is done, you send another signed HTTP request (like above), to obatain an Access Token (again taken from the response body from the provider)
  • This access token can be included in either a HTTP header, the query string or the postbody of subsequent requests to the provider, to access the user’s data.

That’s really how OAuth works. And, more importantly, that’s the way this library works too. The source code includes an examples directory with some samples of how to use the library.

Verifying that it works

There is a web browser interface for testing OAuth requests and signatures at Googlecode that generates signatures based on parameters you provide. Included in this library there is a small Sinatra application that provides the same, but based on the logic in the library itself. I built it mainly to ensure the library generates the correct signatures, but it’s also a fun way to learn how OAuth itself works. Just run the example/acceptance_tester.rb script and point your web browser to http://localhost:4567/ to get going.

Installing

There is a gem on Rubyforge, installed the usual way:

sudo gem install oauth-simple

Getting the source

If you feel so inclined, get the source from Github:

git clone git://github.com/zmalltalker/ruby-oauth-simple.git

Have a look at the tests and get hacking.

TODO

  • getting an Access Token from a Request Token
  • giving some love to the net_http client, maybe provide an extensible interface for other approaches (async HTTP, for instance)
  • complete the Ruby OAuth API for easy switching