warden_oauth_provider

h1. WardenOauthProvider

This gem allows you to start an oauth server and allow your customers to consume your application through oauth. It is based on Warden and can easily be added to the Warden authentication stack. It uses the "oauth gem":http://rubygems.org/gems/oauth to implement the oauth protocol for Warden.

h2. Installation

Add this gem to your Gemfile

gem 'warden_oauth_provider'

Run the generator to create a migration for the required database tables

$ rails generate warden_oauth_provider
$ rake db:migrate

Make sure you have installed the Warden gem for your authentication

Add the @:oauth_provider@ strategy to your Warden middleware and define the oauth paths

YourApp::Application.config.middleware.use Warden::Manager do |manager|
    manager.default_strategies :oauth_provider, :http_basic, :password
    manager.failure_app              = SessionsController
    manager.oauth_request_token_path = "/oauth/request_token"
    manager.oauth_access_token_path  = "/oauth/access_token"
  end

At this point your application responds on the @/oauth/request_token@ and @/oauth/access_token@ paths and provides request and access tokens based on the request. Before you can make any requests, you should create a client application.

h3. Creating client applications

Before a client can connect to the oauth provider, it should be registered as a client application in the database. This can be done through a Rails console or you can create a dedicated controller for this purpose:

WardenOauthProvider::ClientApplication.create!(:name => "My client application", :url => "http://myapplication.com", :callback_url => "http://myapplication.com/callback")

The @:callback_url@ is an optional argument, because the callback url can also be provided when requesting a request token. The @key@ and @secret@ attributes are automatically filled and are the consumer key and consumer secret that should be used to connect to the oauth server.

h3. Creating the authorize interface

During the oauth process, the end-user is redirected to your application to authorize the oauth request. You should write create controller, views and routes for this. You use the @WardenOauthProvider::TokenStrategy@ to verify and authorize the token:

def authorize
  @token = WardenOauthProvider::Token::Request.find_by_token(params[:oauth_token])
  if request.post? 
    if params[:authorize] == "1"  # Something based on your user interface
      if warden.authenticate?(:oauth_token, :scope => :oauth_token)
        redirect_to env['oauth.redirect_url']
      else
        # Render a template to display failure
        render :authorize_failure 
      end
    else
      # Render a template to display failure
      render :authorize_failure
    end
  end
end

h2. xauth

The oauth provider has support for xauth, which supports requests for access tokens without user interaction. More information can be found at "dev.twitter.com":https://dev.twitter.com/docs/oauth/xauth. In order to enable xauth, make sure you set the @xauth_enabled@ boolean for a trusted client application to @true@. Furthermore you should define how the strategy should authenticate a valid user of your system by defining a Proc for the @xauth_user@ Warden config option.

YourApp::Application.config.middleware.use Warden::Manager do |manager|
  manager.default_strategies :oauth_provider, :http_basic, :password
  manager.failure_app              = SessionsController
  manager.oauth_request_token_path = "/oauth/request_token"
  manager.oauth_access_token_path  = "/oauth/access_token"
  manager.xauth_user               = Proc.new do |env, username, password|
    User.authenticate(username, password)  # Return nil when authentication fails or a user when success
  end
end

h2. Reporting bugs

Please report bugs in this gem via Github Issues: https://github.com/bluetools/warden_oauth_provider/issues

h2. License

This code is free to use under the terms of the MIT license and stated in the LICENSE file.