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:
- Register your consumer application with the OAuth compliant service to receive your Consumer Credentials (This is only done once)
- You initiate the OAuth Token exchange process for a user by requesting a RequestToken from the Service
- You store the RequestToken in your database or in the users session object
- You redirect your user to the service providers authorize_url with the RequestToken’s key appended
- Your user is asked by the service provider to authorize your RequestToken
- Your user clicks yes and is redirected to your CallBack URL
- Your callback action exchanges the RequestToken for an AccessToken
- Now you can access your users data by performing http requests signed by your consumer credentials and the AccessToken.
- ????
- 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 :
@[email protected]_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.
If your company needs help getting your OAuth Strategy right or implementing OAuth in your application I’m available for consulting work [email protected].
