Stake Ventures

On the request of many people here is a quick guide to developing OAuth Consumer Application (Consumer==Client in OAuth Speak) in Ruby.

I will be using Agree2 as the sample application here, so feel free to go Register and load up a irb session to follow along. You could also do the same with Twitter’s OAuth or any other OAuth server.

The general process is:

1. Register your consumer application with the OAuth compliant service to receive your Consumer Credentials (This is only done once)
2. You initiate the OAuth Token exchange process for a user by requesting a RequestToken from the Service
3. You store the RequestToken in your database or in the users session object
4. You redirect your user to the service providers authorize_url with the RequestToken’s key appended
5. Your user is asked by the service provider to authorize your RequestToken
6. Your user clicks yes and is redirected to your CallBack URL
7. Your callback action exchanges the RequestToken for an AccessToken
8. Now you can access your users data by performing http requests signed by your consumer credentials and the AccessToken.
9. ????
10. PROFIT!!!

Get your Consumer Credentials

Once you are logged in to Agree2 click the Manage OAuth Applications link in the footer:

All OAuth capable applications require you to register your own application first to get your consumer credentials:

Click Register your application

Enter the name of your application, the url of your application, the callback url and an optional support url.

The callback url is the url that Agree2 redirects to after a user has authorized a token for you. For now just enter a url like http://myapp.com/oauth_client/callback. Click register and hey presto:

These are your applications Consumer Credentials.

Hooking up your code

As we are nice guys here at Agree2 also provides actual sample Ruby code on the credentials screen. I will go through this step by step.

First of all you need to install the oauth gem (make sure you have at least 0.2.2):

sudo gem install oauth

Your code needs to require the gem and the consumer part of the library:

gem 'oauth'
require 'oauth/consumer'

Instantiate your Consumer object with your credentials:

@consumer=OAuth::Consumer.new "AVff2raXvhMUxFnif06g", 
                              "u0zg77R1bQqbzutAusJYmTxqeUpWVt7U2TjWlzbVZkA", 
                              {:site=>"https://agree2.com"}

Now request a token from Agree2. This method actually performs a signed http request to https://agree2.com/oauth/request_token :

@request_token=@consumer.get_request_token

Now you need to redirect the user to the authorize_url

If you’re in irb just output the url:

@request_token.authorize_url

In a real rails application you would perform a redirect:

redirect_to @request_token.authorize_url

The user will be taken to this screen to authorize the token:

I think we need to work a bit on the user interface for this. But it does work. The user authorizes the token. and the user is redirected to the callback url you specified earlier.

In your callback action you now need to exchange the request token for an AccessToken:

@access_token=@request_token.get_access_token

Now you are ready to do whatever you wanted to do:

# Request all your users agreements
@response=@access_token.get "/agreements.xml"

The access token object has all the normal http request methods and returns a standard ruby http response.

Our next step is to integrate this with ActiveResource. This is being worked on now. Once this is done I will update this tutorial.

Create a simple NDA with zero legalese in no time at all and for free at our service Agree2.