devise-radius-authenticatable 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+Gemfile.lock
+log
+*~
+*.gem
+tmp
+rdoc
+

data/.rspec

@@ -0,0 +1,2 @@
+--color
+

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+bundler_args: --binstubs

data/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2012 Calvin Bascom
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,83 @@
+Devise Radius Authenticatable
+=============================
+
+[![Build Status](https://secure.travis-ci.org/cbascom/devise-radius-authenticatable.png)](http://travis-ci.org/cbascom/devise-radius-authenticatable)
+
+Devise Radius Authenticatable is a Radius authentication strategy for [Devise](http://github.com/plataformatec/devise).
+
+Dependencies
+------------
+
+- Rails ~> 3.2
+- Devise ~> 2.0
+- radiustar ~> 0.0.6
+
+Installation
+------------
+
+In the Gemfile for your application:
+
+    gem "devise", "~> 2.0"
+    gem "devise-radius-authenticatable"
+    
+Setup
+-----
+
+Run the rails generators for devise (please check the [devise](http://github.com/plataformatec/devise) documents for further instructions)
+
+    rails generate devise:install
+    rails generate devise MODEL_NAME
+
+Run the rails generator for devise-radius-authenticatable.  Note that the generator is named with underscores instead of hyphens due to rails restrictions.
+
+    rails generate devise_radius_authenticatable:install <IP> <SECRET> [options]
+
+This will update the devise.rb initializer. The IP and SECRET parameters specify the IP address and shared secret for the radius server.  There are also some options you can pass to the generator to customize some default settings:
+
+Options:
+
+    [--uid-field=UID_FIELD]  # What database column to use for the UID
+                             # Default: uid
+    [--port=PORT]            # The port to connect to the radius server on
+                             # Default: 1812
+    [--timeout=TIMEOUT]      # How long to wait for a response from the radius server
+                             # Default: 60
+    [--retries=RETRIES]      # How many times to retry a radius request
+                             # Default: 0
+
+Documentation
+-------------
+
+The rdocs for the gem are available here: http://rubydoc.info/github/cbascom/devise-radius-authenticatable/master/frames
+
+Usage
+-----
+
+In order to use the radius_authenticatable strategy, you must modify your user model to use the :radius_authenticatable module.  The radius_authenticatable strategy can be used standalone or along with database_authenticatable and any other strategies you wish to include. If you use radius_authenticatable alongside other authentication strategies, the default order for the strategies is determined by the order they are loaded in.  The last loaded strategy will be the first strategy executed. The order of these strategies can be configured in the devise.rb initializer as follows:
+
+    config.warden do |warden_config|
+      warden_config.default_strategies(:token_authenticatable,
+                                       :database_authenticatable,
+                                       :radius_authenticatable,
+                                       {:scope => :admin})
+    end
+
+The radius_authenticatable strategy will stop warden from continuing to the next strategy if authentication to the radius server is successful, but will have warden continue to the next stratgey if authentication to the radius server fails.
+
+The field that is used for logins is the first key that's configured in the Devise `config.authentication_keys` settings, which by default is email. For help changing this, please see the [Railscast](http://railscasts.com/episodes/210-customizing-devise) that goes through how to customize Devise.
+
+Configuration
+-------------
+
+The radius_authenticatable module is configured through the normal devise initializer `config/initializers/devise.rb`.  The initial values are added to the file when you run the devise_radius_authenticatable:install generator as describe previously.
+
+References
+----------
+
+* [FreeRadius](http://www.freeradius.org/)
+* [Devise](http://github.com/plataformatec/devise)
+* [Warden](http://github.com/hassox/warden)
+
+Released under the MIT license
+
+Copyright (c) 2012 Calvin Bascom

data/Rakefile

@@ -0,0 +1,16 @@
+require File.expand_path('spec/rails_app/config/environment', File.dirname(__FILE__))
+require 'rdoc/task'
+
+desc 'Default: run test suite.'
+task :default => :spec
+
+desc 'Generate documentation for the devise-radius-authenticatable gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Devise Radius Authenticatable'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+RailsApp::Application.load_tasks

data/devise-radius-authenticatable.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path("../lib/devise/radius_authenticatable/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "devise-radius-authenticatable"
+  s.version     = Devise::RadiusAuthenticatable::VERSION.dup
+  s.platform    = Gem::Platform::RUBY
+  s.summary     = "Devise extension to allow authentication via Radius"
+  s.email       = "cbascom@gmail.com"
+  s.homepage    = "http://github.com/cbascom/devise-radius-authenticatable"
+  s.description = "A new authentication strategy named radius_authenticatable is added to the list of warden strategies when the model requests it.  The radius server information is configured through the devise initializer.  When a user attempts to authenticate via radius, the radiustar gem is used to perform the authentication with the radius server.  This authentication strategy can be used in place of the database_authenticatable or alongside it depending on the needs of the application."
+  s.authors     = ['Calvin Bascom']
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.require_paths = ["lib"]
+
+  s.add_dependency('devise', '~> 2.0')
+  s.add_dependency('radiustar', '~> 0.0.6')
+
+  s.add_development_dependency('rake', '~> 0.9')
+  s.add_development_dependency('rails', '~> 3.2')
+  s.add_development_dependency('jquery-rails', '~> 2.0')
+  s.add_development_dependency('sqlite3', '~> 1.3')
+  s.add_development_dependency('rspec', '~> 2.10')
+  s.add_development_dependency('rspec-rails', '~> 2.10')
+  s.add_development_dependency('factory_girl', '~> 3.4')
+  s.add_development_dependency('capybara', '~> 1.1')
+  s.add_development_dependency('launchy')
+  s.add_development_dependency('ammeter', '~> 0.2')
+end

data/lib/devise/models/radius_authenticatable.rb

@@ -0,0 +1,131 @@
+require 'radiustar'
+require 'devise/strategies/radius_authenticatable'
+
+module Devise
+  module Models
+    # The RadiusAuthenticatable module is responsible for validating a user's credentials
+    # against the configured radius server.  When authentication is successful, the
+    # attributes returned by the radius server are made available via the
+    # +radius_attributes+ accessor in the user model.
+    #
+    # The RadiusAuthenticatable module works by using the configured
+    # +radius_uid_generator+ to generate a UID based on the username and the radius server
+    # hostname or IP address.  This UID is used to see if an existing record representing
+    # the user already exists.  If it does, radius authentication proceeds through that
+    # user record.  Otherwise, a new user record is built and authentication proceeds.
+    # If authentication is successful, the +after_radius_authentication+ callback is
+    # invoked, the default implementation of which simply saves the user record with
+    # validations disabled.
+    #
+    # The radius username is extracted from the parameters hash by using the first
+    # configured value in the +Devise.authentication_keys+ array.  If the authentication
+    # key is in the list of case insensitive keys, the username will be converted to
+    # lowercase prior to authentication.
+    #
+    # == Options
+    #
+    # RadiusAuthenticable adds the following options to devise_for:
+    # * +radius_server+: The hostname or IP address of the radius server.
+    # * +radius_server_port+: The port the radius server is listening on.
+    # * +radius_server_secret+: The shared secret configured on the radius server.
+    # * +radius_server_timeout+: The number of seconds to wait for a response from the
+    #   radius server.
+    # * +radius_server_retries+: The number of times to retry a request to the radius
+    #   server.
+    # * +radius_uid_field+: The database column to store the UID in
+    # * +radius_uid_generator+: A proc that takes the username and server as parameters
+    #   and returns a string representing the UID
+    #
+    # == Callbacks
+    #
+    # The +after_radius_authentication+ callback is invoked on the user record when
+    # radius authentication succeeds for that user but prior to Devise checking if the
+    # user is active for authentication.  Its default implementation simply saves the
+    # user record with validations disabled.  This method should be overriden if further
+    # actions should be taken to make the user valid or active for authentication.  If
+    # you override it, be sure to either call super to save the record or to save the
+    # record yourself.
+    module RadiusAuthenticatable
+      extend ActiveSupport::Concern
+
+      included do
+        attr_accessor :radius_attributes
+      end
+
+      # Use the currently configured radius server to attempt to authenticate the
+      # supplied username and password.  If authentication succeeds, make the radius
+      # attributes returned by the server available via the radius_attributes accessor.
+      # Returns true if authentication was successful and false otherwise.
+      #
+      # Parameters::
+      # * +username+: The username to send to the radius server
+      # * +password+: The password to send to the radius server
+      def valid_radius_password?(username, password)
+        server = self.class.radius_server
+        port = self.class.radius_server_port
+        secret = self.class.radius_server_secret
+        options = {
+          :reply_timeout => self.class.radius_server_timeout,
+          :retries_number => self.class.radius_server_retries
+        }
+
+        req = Radiustar::Request.new("#{server}:#{port}", options)
+        reply = req.authenticate(username, password, secret)
+
+        if reply[:code] == 'Access-Accept'
+          reply.extract!(:code)
+          self.radius_attributes = reply
+          true
+        else
+          false
+        end
+      end
+
+      # Callback invoked by the RadiusAuthenticatable strategy after authentication
+      # with the radius server has succeeded and devise has indicated the model is valid.
+      # This callback is invoked prior to devise checking if the model is active for
+      # authentication.
+      def after_radius_authentication
+        self.save(:validate => false)
+      end
+
+      module ClassMethods
+
+        Devise::Models.config(self, :radius_server, :radius_server_port,
+                              :radius_server_secret, :radius_server_timeout,
+                              :radius_server_retries, :radius_uid_field,
+                              :radius_uid_generator)
+
+        # Invoked by the RadiusAuthenticatable stratgey to perform the authentication
+        # against the radius server.  The username is extracted from the authentication
+        # hash and a UID is generated from the username and server IP.  We then search
+        # for an existing resource using the UID and configured UID field.  If no resource
+        # is found, a new resource is built (not created).  If authentication is
+        # successful the callback is responsible for saving the resource.  Returns the
+        # resource if authentication succeeds and nil if it does not.
+        def find_for_radius_authentication(authentication_hash)
+          uid_field = self.radius_uid_field.to_sym
+          username, password = radius_credentials(authentication_hash)
+          uid = self.radius_uid_generator.call(username, self.radius_server)
+
+          resource = find_for_authentication({ uid_field => uid }) ||
+            new(uid_field => uid)
+
+          resource.valid_radius_password?(username, password) ? resource : nil
+        end
+
+        # Extract the username and password from the supplied authentication hash.  The
+        # username is extracted using the first value from +Devise.authentication_keys+.
+        # The username is converted to lowercase if the authentication key is in the list
+        # of case insensitive keys configured for Devise.
+        def radius_credentials(authentication_hash)
+          key = self.authentication_keys.first
+          value = authentication_hash[key]
+          value.downcase! if (self.case_insensitive_keys || []).include?(key)
+
+          [value, authentication_hash[:password]]
+        end
+      end
+    end
+  end
+end

data/lib/devise/radius_authenticatable/version.rb

@@ -0,0 +1,5 @@
+module Devise
+  module RadiusAuthenticatable
+    VERSION = "0.0.1".freeze
+  end
+end

data/lib/devise/radius_authenticatable.rb

@@ -0,0 +1,32 @@
+require 'devise'
+
+module Devise
+  # The hostname or IP address of the radius server
+  mattr_accessor :radius_server
+
+  # The port for the radius server
+  mattr_accessor :radius_server_port
+  @@radius_server_port = 1812
+
+  # The secret for the radius server
+  mattr_accessor :radius_server_secret
+
+  # The timeout in seconds for radius requests
+  mattr_accessor :radius_server_timeout
+  @@radius_server_timeout = 60
+
+  # The number of times to retry radius requests
+  mattr_accessor :radius_server_retries
+  @@radius_server_retries = 0
+
+  # The database column that holds the unique identifier for the radius user
+  mattr_accessor :radius_uid_field
+  @@radius_uid_field = :radius_uid
+
+  # The procedure to use to build the unique identifier for the radius user
+  mattr_accessor :radius_uid_generator
+  @@radius_uid_generator = Proc.new { |username, server| "#{username}@#{server}" }
+end
+
+Devise.add_module(:radius_authenticatable, :route => :session, :strategy => true,
+                  :controller => :sessions, :model  => true)

data/lib/devise/strategies/radius_authenticatable.rb

@@ -0,0 +1,27 @@
+require 'devise/strategies/authenticatable'
+
+module Devise
+  module Strategies
+    # Strategy for authenticating users with a radius server.  If authentication with
+    # the radius server fails, allow warden to move on to the next strategy.  When
+    # authentication succeeds and Devise indicates that the resource has been
+    # successfully validated, invoke the +after_radius_authentication+ callback on the
+    # resource and let warden know we were successful and not to continue with executing
+    # further strategies.
+    class RadiusAuthenticatable < Authenticatable
+      # Invoked by warden to execute the strategy.
+      def authenticate!
+        resource = valid_password? &&
+          mapping.to.find_for_radius_authentication(params[scope])
+        return fail(:invalid) unless resource
+
+        if validate(resource)
+          resource.after_radius_authentication
+          success!(resource)
+        end
+      end
+    end
+  end
+end
+
+Warden::Strategies.add(:radius_authenticatable, Devise::Strategies::RadiusAuthenticatable)

data/lib/devise-radius-authenticatable.rb

@@ -0,0 +1,2 @@
+require 'devise/radius_authenticatable'
+

data/lib/generators/devise_radius_authenticatable/install_generator.rb

@@ -0,0 +1,78 @@
+module DeviseRadiusAuthenticatable
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("../../templates", __FILE__)
+
+    desc <<-DESC.gsub(/ {6}/, '')
+      Description:
+        Adds radius_authenticatable strategy to the devise initializer
+
+        <SERVER IP> - The IP address of the radius server
+        <SHARED SECRET> - The shared secret for the radius server
+    DESC
+
+    argument(:server, :banner => '<SERVER IP>',
+             :desc => 'The IP address of the radius server')
+    argument(:secret, :banner => '<SHARED SECRET>',
+             :desc => 'The shared secret for the radius server')
+    class_option(:uid_field, :default => :uid,
+                 :desc => 'What database column to use for the UID')
+    class_option(:port, :default => 1812,
+                 :desc => 'The port to connect to the radius server on')
+    class_option(:timeout, :default => 60,
+                 :desc => 'How long to wait for a response from the radius server')
+    class_option(:retries, :default => 0,
+                 :desc => 'How many times to retry a radius request')
+
+    def install
+      inject_into_file("config/initializers/devise.rb", default_devise_settings,
+                       :before => /^\s*.*==> Scopes configuration/)
+    end
+
+    private
+
+    def default_devise_settings
+      <<-CONFIG.gsub(/ {6}/, '')
+
+        # ==> Configuration for radius_authenticatable
+        # The radius_authenticatable strategy can be used in place of the
+        # database_authenticatable strategy or alongside it.  The default order of the
+        # strategies is the reverse of how they were loaded.  You can control this
+        # order by explicitly telling warden the order in which to apply the strategies.
+        # See the Warden Configuration section for further details.
+        #
+        # Configure the hostname or IP address of the radius server to use.
+        config.radius_server = '#{server}'
+
+        # Configure the port to use when connecting to the radius server.
+        config.radius_server_port = #{options[:port]}
+
+        # Configure the shared secret needed to connect to the radius server.
+        config.radius_server_secret = '#{secret}'
+
+        # Configure the time in seconds to wait for a radius server to respond.
+        config.radius_server_timeout = #{options[:timeout]}
+
+        # Configure the number of times a request should be retried when a radius server
+        # does not immediately respond to requests.
+        config.radius_server_retries = #{options[:retries]}
+
+        # In some cases you may want to support authentication attempts against
+        # multiple radius servers.  In these cases the same username could be used on
+        # each of the servers.  In order to create unique database records, a unique
+        # username is generated by using the radius username and the radius server IP
+        # address once the authentication has succeeded.  This configuration option
+        # allows you to chose which database column this calculated UID field will be
+        # stored in.
+        config.radius_uid_field = :#{options[:uid_field]}
+
+        # If you want to control how the unique identifier is created for each radius
+        # user, this can be customized by configuring a proc that accepts the username
+        # and the radius server as parameters and returns the uid.
+        #
+        # config.radius_uid_generator = Proc.new do |username, server|
+        #  "\#{username}@\#{server}"
+        # end
+      CONFIG
+    end
+  end
+end

data/spec/devise/models/radius_authenticatable_spec.rb

@@ -0,0 +1,136 @@
+require 'spec_helper'
+
+class Configurable < Admin
+  devise(:radius_authenticatable, :radius_server => '1.2.3.4',
+         :radius_server_port => 1813, :radius_server_secret => 'secret',
+         :radius_server_timeout => 120, :radius_server_retries => 3,
+         :radius_uid_field => :email,
+         :radius_uid_generator => Proc.new { |username, server|
+           "#{username}_#{server}"
+         })
+end
+
+describe Devise::Models::RadiusAuthenticatable do
+  let(:auth_key) { Devise.authentication_keys.first }
+
+  it "allows configuration of the radius server IP" do
+    Configurable.radius_server.should == '1.2.3.4'
+  end
+
+  it "allows configuration of the radius server port" do
+    Configurable.radius_server_port.should == 1813
+  end
+
+  it "allows configuration of the radius server shared secret" do
+    Configurable.radius_server_secret.should == 'secret'
+  end
+
+  it "allows configuration of the radius server timeout" do
+    Configurable.radius_server_timeout.should == 120
+  end
+
+  it "allows configuration of the radius server retries" do
+    Configurable.radius_server_retries.should == 3
+  end
+
+  it "allows configuration of the radius uid field" do
+    Configurable.radius_uid_field.should == :email
+  end
+
+  it "allows configuration of the radius uid generator" do
+    Configurable.radius_uid_generator.call('test', '1.2.3.4').should == 'test_1.2.3.4'
+  end
+
+  it "extracts radius credentials based on the configured authentication keys" do
+    swap(Devise, :authentication_keys => [:username, :domain]) do
+      auth_hash = { :username => 'cbascom', :password => 'testing' }
+      Configurable.radius_credentials(auth_hash).should == ['cbascom', 'testing']
+    end
+  end
+
+  it "converts the username to lower case if the key is case insensitive" do
+    swap(Devise, {:authentication_keys => [:username, :domain],
+           :case_insensitive_keys => [:username]}) do
+      auth_hash = { :username => 'Cbascom', :password => 'testing' }
+      Configurable.radius_credentials(auth_hash).should == ['cbascom', 'testing']
+    end
+  end
+
+  it "does not convert the username to lower case if the key is not case insensitive" do
+    swap(Devise, {:authentication_keys => [:username, :domain],
+           :case_insensitive_keys => []}) do
+      auth_hash = { :username => 'Cbascom', :password => 'testing' }
+      Configurable.radius_credentials(auth_hash).should == ['Cbascom', 'testing']
+    end
+  end
+
+  context "when finding the user record for authentication" do
+    let(:good_auth_hash) { {auth_key => 'testuser', :password => 'password'} }
+    let(:bad_auth_hash) { {auth_key => 'testuser', :password => 'wrongpassword'} }
+
+    before do
+      @uid_field = Admin.radius_uid_field.to_sym
+      @uid = Admin.radius_uid_generator.call('testuser', Admin.radius_server)
+      create_radius_user('testuser', 'password')
+    end
+
+    it "uses the generated uid and configured uid field to find the record" do
+      Admin.should_receive(:find_for_authentication).with(@uid_field => @uid)
+      Admin.find_for_radius_authentication(good_auth_hash)
+    end
+
+    context "and authentication succeeds" do
+      it "creates a new user record if none was found" do
+        Admin.find_for_radius_authentication(good_auth_hash).should be_new_record
+      end
+
+      it "fills in the uid when creating the new record" do
+        admin = Admin.find_for_radius_authentication(good_auth_hash)
+        admin.send(@uid_field).should == @uid
+      end
+
+      it "uses the existing user record when one is found" do
+        admin = FactoryGirl.create(:admin, @uid_field => @uid)
+        Admin.find_for_radius_authentication(good_auth_hash).should == admin
+      end
+    end
+
+    context "and authentication fails" do
+      it "does not create a new user record" do
+        Admin.find_for_radius_authentication(bad_auth_hash).should be_nil
+      end
+    end
+  end
+
+  context "when validating a radius user's password" do
+    before do
+      @admin = Admin.new
+      create_radius_user('testuser', 'password')
+    end
+
+    it "passes the configured options when building the radius request" do
+      server_url = "#{Admin.radius_server}:#{Admin.radius_server_port}"
+      server_options = {
+        :reply_timeout => Admin.radius_server_timeout,
+        :retries_number => Admin.radius_server_retries
+      }
+      @admin.valid_radius_password?('testuser', 'password')
+
+      radius_server.url.should == server_url
+      radius_server.options.should == server_options
+    end
+
+    it "returns false when the password is incorrect" do
+      @admin.valid_radius_password?('testuser', 'wrongpassword').should be_false
+    end
+
+    it "returns true when the password is correct" do
+      @admin.valid_radius_password?('testuser', 'password').should be_true
+    end
+
+    it "stores the returned attributes in the model" do
+      @admin.valid_radius_password?('testuser', 'password')
+      @admin.radius_attributes.should == radius_server.attributes('testuser')
+    end
+  end
+end

data/spec/factories/admins.rb

@@ -0,0 +1,10 @@
+FactoryGirl.define do
+  sequence :admin_email do |n|
+    "admin#{n}@gmail.com"
+  end
+
+  factory :admin do
+    email     { FactoryGirl.generate(:admin_email) }
+    password  "password"
+  end
+end