warden_oauth¶ ↑

warden_oauth enhances the Warden authentication framework, offering a simple interface for creating oauth strategies.

Getting Started¶ ↑

To get started you just have to require the warden_oauth libraries, and setup the oauth services you would like to have on the Warden::Manager middleware declaration:

Warden::Manager do |config|
  config.failure_app = FailureApp
  config.oauth(:twitter) do |twitter|
    twitter.consumer_secret = <YOUR CONSUMER SECRET>
    twitter.consumer_key  = <YOUR CONSUMER KEY>
    twitter.options({ 
      :site => 'http://twitter.com',
      :oauth_callback => (BASE_URL.end_with?('/') ? BASE_URL[0..-2] : BASE_URL)  + '/users', 
      :oauth_callback_confirmed => 'true' 
    })
  end
  config.default_strategies(:twitter_oauth, :password, :other)
end

You then need to set the BASE_URL constant in your environment files so that the oauth_callback will work:

BASE_URL = "http://localhost"

Giving an Access Token fetcher¶ ↑

Users get identified on a system via an access_token and an access_secret, when a valid access_token is recevied, warden_oauth calls a fetcher declared on Warden::OAuth.access_token_user_finder(:<strategy_key>).

Warden::OAuth.access_token_user_finder(:twitter) do |access_token|
  User.find_by_access_token_and_access_secret(access_token.token, access_token.secret)
end

If a user is returned, then this is the user that is going to be authenticated in the session, otherwise the FailureApp will be called, you may check the env['warden.options'][:oauth][:access_token] to check the original access_token and <bold>create a new user</bold> from there if desired.

Strategy Class info¶ ↑

When you declare an oauth strategy on the Warden::Config initialization, (e.g. config.oauth(:service_name)) a Warden::OAuth::Strategy::ServiceName will be declared, at the same time this class will be registered as :service_name_oauth on the Warden::Strategies.

So when we have a declaration like the one we have in the Getting Started section, we will have an Strategy class called Warden::OAuth::Strategy::Twitter, and this will be registered as :twitter_oauth on the Warden::Strategies.

Running the Strategy¶ ↑

In order to get the strategy running in the app, you have to specify a parameter called warden_oauth_provider with the name of the oauth service you want to use. So for example, if you would like to boot the twitter oauth example given on the “Getting Started” section you just have to specify the parameter on a protected url.

In Rails:

link_to 'Twitter Authentication', url_for(login_path(:warden_oauth_provider => 'twitter'))

There can be 3 different outcomes from this strategy:

1. The OAuth credentials are invalid and the FailureApp is called.

2. The OAuth credentials are valid, but there is no user associated to them. In this case the FailureApp is called, but the env[:oauth] will be available.

3. The OAuth credentials are valid, and the user is authenticated successfuly.

Note:

In Rails, don’t set the :warden_oauth_provider parameter as part of the login route, if you do this, rails will catch the parameter, but not the warden rack middleware, ergo, it won’t work as expected.

Oauth 2.0¶ ↑

To use oauth 2.0 it is very similar to standard oauth. Here is my example for working with facebook

config.warden do |manager|
  manager.oauth2(:facebook) do |fb|
    fb.consumer_key  = FACEBOOK_CONSUMER_KEY
    fb.consumer_secret = FACEBOOK_CONSUMER_SECRET
    fb.client_id = FACEBOOK_CLIENT_ID
    fb.options({
      :authorize_url => 'https://www.facebook.com/dialog/oauth',
      :access_token_url => 'https://graph.facebook.com/oauth/access_token',
      :site => 'https://graph.facebook.com',
      :scope => 'email,offline_access',
      :redirect_uri => (BASE_URL.end_with?('/') ? BASE_URL[0..-2] : BASE_URL)  + '/users'
    })
  end
  manager.default_strategies(:scope => :user).unshift :facebook_oauth
end

Note: You still need to give an Access Token fetcher

Warden::OAuth2.access_token_user_finder(:facebook) do |access_token|
end

Note: Instead of oauth the keyword oauth2 is used in both examples above

Examples¶ ↑

If you want to know how to make a twitter authentication client, check examples/twitter/application.rb

Note on Patches/Pull Requests¶ ↑

For any error send an email to: romanandreg [at] gmail [dot] com

Copyright¶ ↑

Copyright © 2009 Roman Gonzalez. See LICENSE for details.