vidibus-oauth2_server 0.0.2 → 0.0.3

data/README.rdoc

@@ -1,8 +1,8 @@
-= vidibus-oauth2_server
+= Vidibus::Oauth2Server
 
-Allows OAuth2 authentication based on http://tools.ietf.org/html/draft-ietf-oauth2-v2-00.
+Allows OAuth2 authentication for Rails applications based on http://tools.ietf.org/html/draft-ietf-oauth2-v2-00.
 
-This gem is part of the open source SOA framework Vidibus: http://vidibus.org.
+This gem is part of the open source SOA framework {Vidibus}[http://vidibus.org].
 
 It is far from being complete and stable! But this will change soon.
 
@@ -15,44 +15,53 @@ Add the dependency to the Gemfile of your application:
 
 Then call bundle install on your console.
 
+To get your own OAuth2 server working, some small adjustments will have to be made to your Rails application:
 
-=== Routes
-
-Two routes will be added to your application. If you use a catch-all route, you will have to define these routes manually:
 
-  get "oauth/authorize" => "oauth2#authorize"
-  post "oauth/access_token" => "oauth2#access_token"
+=== Client model
 
+Each remote application that requests authentication has to be authorized to do this. Usually, such an application will have to provide an API key that will be validated against a local repository. For OAuth2 this API key is called "client_id".
 
-=== ApplicationController
+Additionally, each client application has to provide a password to make a valid Oauth2 request, the "client_secret".
 
-In ApplicationController of your OAuth server application you have to define two methods in order to perform OAuth authentication.
+This gem will validate an incoming OAuth2 request against client_id and client_secret parameters. Thus your client model has to provide both attributes, although they don't have to be named like this.
 
-The first method performs a sign in of the current user. If you use Devise for authentication, this method already exists and works. This is an example that works with Authlogic:
+You'll also have to provide a #domain method on your OAuth client model that returns the domain name of the client, e.g. vidibus.org. This method is used to validate the redirect_url parameter.
 
-  # Calls authentication method.
-  def authenticate_user!
-    logged_in? or login_required
-  end
+Before issuing a token, the Oauth2Controller will ensure that the given client_secret is valid. In order to perform this validation, a method #valid_oauth2_secret? must be given on your client model.
 
-The second method returns a client object with given id. This is an example for usage with vidibus-service gem:
+If you use the {Vidibus::Service}[https://github.com/vidibus/vidibus-service] gem, you'll get this method on the service model:
 
-  # Returns Service with given id.
-  # This method is called from Vidibus' OauthServer gem.
-  # The given client_id comprises the requesting service's
-  # uuid and realm, concatenated by -
-  def oauth2_client(client_id)
-    Service(*client_id.split("-"))
+  # Returns true if given client_secret matches signature.
+  def valid_oauth2_secret?(client_secret)
+    client_secret == Vidibus::Secure.sign("#{Service.this.url}#{uuid}", secret)
   end
 
 
 === User model
 
-Your user model has to provide an unique UUID. If you use Mongoid, add the following:
+Your user model has to provide an unique UUID in compact format. If you use Mongoid, you may include the UUID generator provided by the {Vidibus::Uuid}[https://github.com/vidibus/vidibus-uuid] gem:
 
-  field :uuid
+  class User
+    include Mongoid::Document
+    include Vidibus::Uuid::Mongoid
+    ...
+  end
 
-If you have an ActiveRecord model, add a migration like this:
+If you have an ActiveRecord model, implement something like this:
+
+  require "uuid"
+  class User < ActiveRecord::Base
+    before_create :generate_uuid
+    ...
+    protected
+
+    def generate_uuid
+      self.uuid ||= UUID.new.generate(:compact)
+    end
+  end
+
+And don't forget the migration:
 
   require "uuid"
   class AddUuidToUsers < ActiveRecord::Migration
@@ -71,9 +80,44 @@ If you have an ActiveRecord model, add a migration like this:
   end
 
 
-=== User controller
+=== Routes
+
+Two routes will be added to your Rails application. If you use a catch-all route, you will have to define these routes manually:
 
-This gem will an action to obtain data of the currently logged in user. The following route will be added:
+  get "oauth/authorize" => "oauth2#authorize"
+  post "oauth/access_token" => "oauth2#access_token"
+
+
+=== ApplicationController
+
+In the ApplicationController of your OAuth server application you'll have to define two methods in order to perform OAuth authentication.
+
+The first method performs the sign-in of the current user. If you use Devise for authentication with a "User" model, that method already exists and works. This is an example that works with Authlogic:
+
+  # Calls authentication method.
+  def authenticate_user!
+    logged_in? or login_required
+  end
+
+The second method returns a service client with given id. This is an example taken from the {Vidibus::Service}[https://github.com/vidibus/vidibus-service] gem:
+
+  # Returns service matching given client_id.
+  # This method is called from Vidibus' Oauth2Server gem.
+  #
+  # In this example from Vidibus the given client_id
+  # comprises the requesting service's uuid and realm,
+  # concatenated by -.
+  #
+  # Adjust this method to your needs.
+  #
+  def oauth2_client(client_id)
+    Service(*client_id.split("-"))
+  end
+
+
+=== Oauth2::UsersController
+
+This gem will also provide an action to obtain data of the user currently logged in. The following route will be added:
 
   get "/oauth/user" => "oauth2/users#show"
 
@@ -86,31 +130,22 @@ For a typical ActiveRecord model this would be:
     User.first(:conditions => {:uuid => uuid})
   end
 
-The default #show method delivers a JSON string including name, email and UUID of the current user:
+The default #show method of this controller delivers a JSON string including name, email and UUID of the current user:
 
   def show
     render :json => @user.attributes.only(*%w[name email uuid])
   end
 
+== And the client side?
 
-=== Client model
-
-Provide a #domain method to your OAuth client model that returns the domain name of the client. This method is used to validate the redirect_url.
+Well, this is just the server side of the story. To implement OAuth2 on your client applications, there are many solutions available. The basic tools are provided by the excellent {OAuth2}[https://github.com/intridea/oauth2] gem. For a sophisticated example, check out {OmniAuth}[https://github.com/intridea/omniauth].
 
-Before issuing a token, the Oauth2Controller will ensure that the given client_secret is valid. In order to perform this validation, a method #valid_oauth2_secret? must be given on your client model.
-
-If you use the vidibus-service gem, you'll get this method on the service model:
-
-  # Returns true if given client_secret matches signature.
-  def valid_oauth2_secret?(client_secret)
-    client_secret == Vidibus::Secure.sign("#{Service.this.url}#{uuid}", secret)
-  end
+In a typical Vidibus service-oriented environment, clients are equipped with the {Vidibus::User}[https://github.com/vidibus/vidibus-user] gem.
 
 
 == TODO
 
 * Write specs!
-* Explain usage and integration
 * Implement token expiry
 * Apply changes made in http://tools.ietf.org/html/draft-ietf-oauth2-v2-10?
 

data/Rakefile

@@ -1,5 +1,8 @@
 require "rubygems"
 require "rake"
+require "rake/rdoctask"
+require "rspec"
+require "rspec/core/rake_task"
 
 begin
   require "jeweler"
@@ -16,3 +19,18 @@ begin
 rescue LoadError
   puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
 end
+
+Rspec::Core::RakeTask.new(:rcov) do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  t.rcov = true
+  t.rcov_opts = ["--exclude", "^spec,/gems/"]
+end
+
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?("VERSION") ? File.read("VERSION") : ""
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title = "vidibus-oauth2_server #{version}"
+  rdoc.rdoc_files.include("README*")
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.options << "--charset=utf-8"
+end

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/app/controllers/oauth2/authentication_controller.rb

@@ -1,102 +1,100 @@
-module Oauth2
-  class AuthenticationController < ApplicationController
-    skip_before_filter :verify_authenticity_token
+class Oauth2::AuthenticationController < Oauth2Controller
+  skip_before_filter :verify_authenticity_token
 
-    around_filter :oauth2_error_handler
+  around_filter :oauth2_error_handler
 
-    before_filter :validate_oauth2_type!
-    before_filter :validate_oauth2_client_id!
-    before_filter :validate_oauth2_redirect_url!
+  before_filter :validate_oauth2_type!
+  before_filter :validate_oauth2_client_id!
+  before_filter :validate_oauth2_redirect_url!
 
-    before_filter :authenticate_user!, :only => :authorize
-    before_filter :validate_oauth2_client_secret!, :only => :access_token
+  before_filter :authenticate_user!, :only => :authorize
+  before_filter :validate_oauth2_client_secret!, :only => :access_token
 
-    def authorize
-      args = params.slice(:client_id, :redirect_url)
-      args[:user_id] = current_user.uuid
-      token = Oauth2Token.create!(args)
-      uri_params = { :code => token.code }
-      uri_params[:state] = params[:state] if params.has_key?(:state)
-      uri = params[:redirect_url].with_params(uri_params)
-      redirect_to(uri)
-    end
+  def authorize
+    args = params.slice(:client_id, :redirect_url)
+    args[:user_id] = current_user.uuid
+    token = Oauth2Token.create!(args)
+    uri_params = { :code => token.code }
+    uri_params[:state] = params[:state] if params.has_key?(:state)
+    uri = params[:redirect_url].with_params(uri_params)
+    redirect_to(uri)
+  end
 
-    def access_token
-      token = Oauth2Token.find!(params)
-      render :text => { :access_token => token.token }.to_uri, :type => :url_encoded_form, :status => :ok
-    end
+  def access_token
+    token = Oauth2Token.find!(params)
+    render :text => { :access_token => token.token }.to_uri, :type => :url_encoded_form, :status => :ok
+  end
 
-    protected
+  protected
 
-    # Ensures that the type of flow is supported
-    def validate_oauth2_type!
-      type = params[:type]
-      raise Vidibus::Oauth2Server::MissingTypeError if type.blank?
-      raise Vidibus::Oauth2Server::UnsupportedTypeError unless Vidibus::Oauth2Server::FLOWS.include?(type)
-    end
+  # Ensures that the type of flow is supported
+  def validate_oauth2_type!
+    type = params[:type]
+    raise Vidibus::Oauth2Server::MissingTypeError if type.blank?
+    raise Vidibus::Oauth2Server::UnsupportedTypeError unless Vidibus::Oauth2Server::FLOWS.include?(type)
+  end
 
-    # Ensures that given client id is valid
-    def validate_oauth2_client_id!
-      raise Vidibus::Oauth2Server::MissingClientIdError if params[:client_id].blank?
-      @oauth2_client = oauth2_client(params[:client_id])
-      raise Vidibus::Oauth2Server::InvalidClientIdError unless @oauth2_client
-    end
+  # Ensures that given client id is valid
+  def validate_oauth2_client_id!
+    raise Vidibus::Oauth2Server::MissingClientIdError if params[:client_id].blank?
+    @oauth2_client = oauth2_client(params[:client_id])
+    raise Vidibus::Oauth2Server::InvalidClientIdError unless @oauth2_client
+  end
 
-    # Ensures that redirect_url is valid for given client.
-    def validate_oauth2_redirect_url!
-      redirect_url = params[:redirect_url]
-      raise Vidibus::Oauth2Server::MissingRedirectUrlError if redirect_url.blank?
-      raise Vidibus::Oauth2Server::MalformedRedirectUrlError unless valid_uri?(redirect_url)
-      unless redirect_url.match(/^https?:\/\/([a-z0-9]+\.)?#{@oauth2_client.domain}/) # allow subdomains but ensure host of client application
-        raise Vidibus::Oauth2Server::InvalidRedirectUrlError
-      end
+  # Ensures that redirect_url is valid for given client.
+  def validate_oauth2_redirect_url!
+    redirect_url = params[:redirect_url]
+    raise Vidibus::Oauth2Server::MissingRedirectUrlError if redirect_url.blank?
+    raise Vidibus::Oauth2Server::MalformedRedirectUrlError unless valid_uri?(redirect_url)
+    unless redirect_url.match(/^https?:\/\/([a-z0-9]+\.)?#{@oauth2_client.domain}/) # allow subdomains but ensure host of client application
+      raise Vidibus::Oauth2Server::InvalidRedirectUrlError
     end
+  end
 
-    # Ensures that given client_secret is valid for given client.
-    def validate_oauth2_client_secret!
-      raise Vidibus::Oauth2Server::InvalidClientSecretError unless @oauth2_client.valid_oauth2_secret?(params[:client_secret])
-    end
+  # Ensures that given client_secret is valid for given client.
+  def validate_oauth2_client_secret!
+    raise Vidibus::Oauth2Server::InvalidClientSecretError unless @oauth2_client.valid_oauth2_secret?(params[:client_secret])
+  end
 
-    # Returns error message for given exception.
-    def oauth2_error_handler
-      begin
-        yield
-      rescue Vidibus::Oauth2Server::MissingTypeError
-        error = "missing_type"
-      rescue Vidibus::Oauth2Server::UnsupportedTypeError
-        error = "unsupported_type"
-      rescue Vidibus::Oauth2Server::MissingClientIdError
-        error = "missing_client_id"
-      rescue Vidibus::Oauth2Server::InvalidClientIdError
-        error = "invalid_client_id"
-      rescue Vidibus::Oauth2Server::InvalidClientSecretError
-        error = "invalid_client_secret"
-      rescue Vidibus::Oauth2Server::MissingRedirectUrlError
-        error = "missing_redirect_url"
-      rescue Vidibus::Oauth2Server::MalformedRedirectUrlError
-        error = "malformed_redirect_url"
-      rescue Vidibus::Oauth2Server::InvalidRedirectUrlError
-        error = "invalid_redirect_url"
-      rescue Vidibus::Oauth2Server::MissingCodeError
-        error = "missing_code"
-      rescue Vidibus::Oauth2Server::InvalidCodeError
-        error = "invalid_code"
-      rescue Vidibus::Oauth2Server::ExpiredCodeError
-        error = "expired_code"
-      rescue Vidibus::Oauth2Server::InvalidTokenError
-        error = "invalid_token"
-      rescue Vidibus::Oauth2Server::ExpiredTokenError
-        error = "expired_token"
-      ensure
-        if error
-          status ||= :bad_request
-          render :text => I18n.t("oauth2_server.errors.#{error}"), :status => status
-        end
+  # Returns error message for given exception.
+  def oauth2_error_handler
+    begin
+      yield
+    rescue Vidibus::Oauth2Server::MissingTypeError
+      error = "missing_type"
+    rescue Vidibus::Oauth2Server::UnsupportedTypeError
+      error = "unsupported_type"
+    rescue Vidibus::Oauth2Server::MissingClientIdError
+      error = "missing_client_id"
+    rescue Vidibus::Oauth2Server::InvalidClientIdError
+      error = "invalid_client_id"
+    rescue Vidibus::Oauth2Server::InvalidClientSecretError
+      error = "invalid_client_secret"
+    rescue Vidibus::Oauth2Server::MissingRedirectUrlError
+      error = "missing_redirect_url"
+    rescue Vidibus::Oauth2Server::MalformedRedirectUrlError
+      error = "malformed_redirect_url"
+    rescue Vidibus::Oauth2Server::InvalidRedirectUrlError
+      error = "invalid_redirect_url"
+    rescue Vidibus::Oauth2Server::MissingCodeError
+      error = "missing_code"
+    rescue Vidibus::Oauth2Server::InvalidCodeError
+      error = "invalid_code"
+    rescue Vidibus::Oauth2Server::ExpiredCodeError
+      error = "expired_code"
+    rescue Vidibus::Oauth2Server::InvalidTokenError
+      error = "invalid_token"
+    rescue Vidibus::Oauth2Server::ExpiredTokenError
+      error = "expired_token"
+    ensure
+      if error
+        status ||= :bad_request
+        render :text => I18n.t("oauth2_server.errors.#{error}"), :status => status
       end
-
-      # Autorization error?
-      # :status => :unauthorized # The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource.
-      # :status => :forbidden # Maybe better?
     end
+
+    # Autorization error?
+    # :status => :unauthorized # The response MUST include a WWW-Authenticate header field (section 14.47) containing a challenge applicable to the requested resource.
+    # :status => :forbidden # Maybe better?
   end
 end

data/app/controllers/oauth2/users_controller.rb

@@ -1,20 +1,18 @@
-module Oauth2
-  class UsersController < ApplicationController
-    before_filter :ensure_token!
-    before_filter :find_user
+class Oauth2::UsersController < Oauth2Controller
+  before_filter :ensure_token!
+  before_filter :find_user
 
-    def show
-      render :json => @user.attributes.only(*%w[name email uuid])
-    end
+  def show
+    render :json => @user.attributes.only(*%w[name email uuid])
+  end
 
-    protected
+  protected
 
-    def find_user
-      @user = find_user_by_uuid(@access_token.user_id) or render(:nothing => true, :status => :bad_request)
-    end
+  def find_user
+    @user = find_user_by_uuid(@access_token.user_id) or render(:nothing => true, :status => :bad_request)
+  end
 
-    def ensure_token!
-      @access_token = Oauth2Token.find!(:token => params[:access_token])
-    end
+  def ensure_token!
+    @access_token = Oauth2Token.find!(:token => params[:access_token])
   end
 end

data/app/controllers/oauth2_controller.rb

@@ -0,0 +1,2 @@
+class Oauth2Controller < ApplicationController
+end

data/vidibus-oauth2_server.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{vidibus-oauth2_server}
-  s.version = "0.0.2"
+  s.version = "0.0.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andre Pankratz"]
-  s.date = %q{2011-01-14}
+  s.date = %q{2011-02-23}
   s.description = %q{OAuth2 server for Rails 3 with Mongoid.}
   s.email = %q{andre@vidibus.com}
   s.extra_rdoc_files = [
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
     "VERSION",
     "app/controllers/oauth2/authentication_controller.rb",
     "app/controllers/oauth2/users_controller.rb",
+    "app/controllers/oauth2_controller.rb",
     "app/models/oauth2_token.rb",
     "config/locales/en.yml",
     "config/routes.rb",

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: vidibus-oauth2_server
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 25
   prerelease: false
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Andre Pankratz
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-14 00:00:00 +01:00
+date: 2011-02-23 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -189,6 +189,7 @@ files:
 - VERSION
 - app/controllers/oauth2/authentication_controller.rb
 - app/controllers/oauth2/users_controller.rb
+- app/controllers/oauth2_controller.rb
 - app/models/oauth2_token.rb
 - config/locales/en.yml
 - config/routes.rb