ucb_rails_security 2.0.7

data/lib/ucb_rs_controller_methods.rb

@@ -0,0 +1,496 @@
+module UCB #:nodoc:
+  module Rails #:nodoc:
+    module Security
+      # == Overview
+      # These methods are added to ActionController::Base
+      # so they are available to all of your application's controllers.
+      # 
+      # Most of the time you will be using the various <tt>filter_*</tt> 
+      # methods.  Note that most of these methods are implemented via method_missing
+      # and are not explicitly listed in the "methods" section of this document.
+      # For details see examples below as well as method_missing, filter_ldap and
+      # filter_db_role.
+      # 
+      # There are several methods used primarily by the filter methods, but you
+      # may find use for these in your controllers.  Many of these methods
+      # are marked as "helper methods" and are available for use in your
+      # views (*.rhtml templates) and helpers.  See ApplicationHelper for
+      # more information.
+      #
+      # == How Does This Work?
+      # Take a look at the following controller: +RAILS_ROOT/app/controllers/ucb_security/base_controller.rb+
+      #
+      # You should see the following:
+      #
+      #  class UcbSecurity::BaseController < ApplicationController
+      #    # Move this include into your ApplicationController to add security to your entire application
+      #    include UCB::Rails::Security::ControllerMethods
+      #
+      #    layout 'layouts/ucb_security/application'
+      #    before_filter :filter_role_security, :except => [:not_authorized, :logout]
+      #  end
+      #
+      # The +include+ line adds several methods to this base controller, many 
+      # of which are filters.  The line <tt>before_filter :filter_role_security, :except => [:not_authorized, :logout]</tt> 
+      # tells this controller to only allow a user with the 
+      # security role access to the actions in this controller. Since all 
+      # of the ucb_security controllers extend this base controller, that has 
+      # the requires the user to have the security role for all actions
+      # in the ucb_security module (with the exception of not_authorized and 
+      # logout)
+      #
+      # When you add one of these filters to your controller, behind the scenes 
+      # CAS authentication is handled for you: if the user has not yet authenticated 
+      # they will be directed to CAS otherwise your filter will be run.
+      # 
+      # You may want to add this filter to your application controller.  If your 
+      # entire site requires authentication then that is definitely the way to go.  
+      # If only a handful of controllers require auth, then only add these filter 
+      # methods to those specific controllers.
+      #
+      #   
+      # ==Explicit Filters
+      # 
+      # User must be logged in:
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_logged_in
+      #   end
+      #   
+      # User must be in user table (assumes your application has
+      # a +User+ table -- see UCB::Rails::Security):
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_in_user_table
+      #   end
+      # 
+      # ==LDAP Filters
+      # 
+      # Any LDAP attribute can be used in a dynamic LDAP filter.  More accurately, any method
+      # that an instance of UCB::LDAP::Person responds to can be used in a filter.
+      # 
+      # To satisfy the filter, the method must return a broader-than-normal
+      # definition of <tt>true</tt>: strings containing only spaces and empty arrays
+      # are considered <tt>false</tt>.
+      #  
+      # Since UCB::LDAP::Person has <tt>employee?</tt> and <tt>student?</tt> methods,
+      # we can do the following:
+      #
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_ldap_employee?
+      #     before_filter :filter_ldap_student?
+      #   end
+      # 
+      # You can use any valid UCB::LDAP::Person method or LDAP attribute as the
+      # "method" part of :filter_ldap_method.  Just keep in mind what constitutes
+      # "true".
+      # 
+      # Since there is no "bogus" attribute, the following raises a <tt>NoMethodError</tt>
+      # exception:
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_ldap_bogus
+      #   end
+      #
+      # You can filter based on the value of a particular attribute.
+      # Currently supported operators are "eq" and "ne":
+      #
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_ldap_deptid__eq__JKASD
+      #     before_filter :filter_ldap_lastname__ne__Badenov
+      #   end
+      # 
+      # === Note
+      # 
+      # LDAP filters call the filter_logged_in filter.
+      # 
+      # == User Filters
+      # 
+      # If your application has a user table you can do controller filtering
+      # based on your user table:
+      # 
+      # The following only allows people who can update to access the controller:
+      # 
+      #   class User < ActiveRecord::Base
+      #     def can_update?
+      #       <complicated logic>
+      #     end
+      #   end
+      # 
+      #   class UpdateController < ActionController::Base
+      #      before_filter :filter_user_can_update?
+      #   end
+      #
+      # Filters of the form <tt>:filter_user_method</tt> are passed/failed
+      # based on the return value of <tt>User#method</tt>. 
+      #
+      # === Non-boolean User Filters
+      #
+      # You can filter based on the value of a particular +User+ table
+      # method.  Currently supported operators are "eq" and "ne":
+      #
+      #   class DoeNotJohnController < ActionController::Base
+      #      before_filter :filter_user_lastname__eq__Doe
+      #      before_filter :filter_user_firstname__ne__John
+      #   end
+      #
+      # === Note
+      # 
+      # All User filters call the filter_logged_in and filter_in_user_table filters.
+      #
+      # ==Role Filters
+      # 
+      # If your application has both a user and
+      # a roles table (see UCB::Rails::Security) 
+      # you can use dynamic database role filters.  
+      # 
+      # Your user class must repond to the "roles" message
+      # by returning an Array of objects that respond to the "name"
+      # message.
+      #
+      # The following verifies the user has the "admin" role:
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_role_admin
+      #   end
+      #
+      # In general, the ":filter_role_rolename" filter verifies that the
+      # user holds the "rolename" role.
+      # 
+      # The following verifies the user has the "admin" <b>and</b> "super_user" roles:
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_role_has_all_of_admin_and_super_user
+      #   end
+      #
+      # The following verifies the user has either the "guest" <b>or</b> "user" roles:
+      # 
+      #   class MyController < ActionController::Base
+      #     before_filter :filter_role_has_one_of_guest_or_user
+      #   end
+      #
+      # === Note
+      # 
+      # Role filters call the filter_logged_in and filter_in_user_table filters.
+      #
+      # == Helper Methods
+      #
+      # Several of the methods in this module are exposed as helper methods
+      # that you can use in your views (<tt>../app/views/<controller>/*.rhtml</tt>)
+      # and helpers (<tt>../app/helpers/<controller>_helper.rb</tt>).
+      #
+      #   # in your view
+      #
+      #   <% if logged_in? %>
+      #   Logged in as: <%= "#{ldap_user.firstname} #{ldap_user.lastname}"%>
+      #   <% end %>
+      #
+      # Or even better, used in a helper method you write:
+      #
+      #   # in your view
+      #
+      #   <%= logged_in_html %>
+      #
+      #   # in your controller's helper
+      #
+      #   def logged_in_html
+      #     logged_in? ? "" : "Logged in as #{ldap_user.firstname} #{ldap_user.lastname}"
+      #   end
+      #
+      # See the HELPER_METHODS constant below for a list of the methods.
+      #
+      module ControllerMethods 
+
+        # These methods are available has helpers in your views and helpers.
+        HELPER_METHODS = [
+          :in_user_table?,
+          :ldap_user, 
+          :logged_in,
+          :role_names, 
+          :roles, 
+          :ldap_uid,
+          :user_table_user, 
+          :user_table_id,
+          :using_user_table?,
+          :logout,
+        ]
+        
+        # Operators available for non-boolean LDAP and User filters.
+        OPERATOR_METHODS = {
+          "eq" => "==",
+          "ne" => "!=",
+        }
+        
+        def not_authorized
+          render :text => "Not Authorized", :status => 401
+        end
+        
+        # Logs user out of application
+        def logout
+          application_logout
+          protocol = request.ssl? ? 'https://' : 'http://'
+          url = UCB::Rails::Security::CASAuthentication.home_url
+          logout_url = UCB::Rails::Security::CASAuthentication.logout_url
+          redirect_to("#{logout_url}?url=#{protocol}#{request.host_with_port}/#{url}")
+        end
+        
+        private unless $TESTING
+        
+        def application_logout()
+          [ :cas_user, :ldap_user, :user_table_id, :casfilterpgt,
+            :casfilterreceipt, :caslastticket, :casfiltergateway ].each{ |k| session[k] = nil }
+        end
+        
+        # CAS authentication before_filter.  Use this filter to ensure
+        # users have logged in, i.e. authenticated with CAS.
+        def filter_logged_in() #:doc:
+          _logger.debug("In filter_logged_in")
+          if logged_in?
+            _logger.debug("\tlogged_in? returned true")
+            return true
+          elsif !UCB::Rails::Security::CASAuthentication.filter(self)
+            _logger.debug("\tUCB::Rails::Security::CASAuthentication.filter returned false")
+            return false
+          end
+          application_login
+          true
+        end
+
+        # Logs ldap_uid into application.  
+        # 
+        # * get LDAP entry (available via ActionController::Base#ldap_user)
+        # * check for user in User table (if using_user_table?)
+        # * update User table columns with LDAP values 
+        # 
+        # This happens upon successful CAS authentication.  You can login
+        # a particular user to your application by calling this method
+        # with the corresponding ldap_uid.
+        def application_login(ldap_uid=ldap_uid) #:doc:
+          _logger.debug("In application_login")
+          UCB::LDAP::Person.include_test_entries = UCB::Rails::Security::CASAuthentication.allow_test_entries?
+          _logger.debug("\tLDAP test entries will #{UCB::LDAP::Person.include_test_entries? || "NOT"} be included")
+          _logger.debug("Looking for authenticated user in LDAP: #{ldap_uid}")
+          self.ldap_user = UCB::LDAP::Person.find_by_uid(ldap_uid)
+          if ldap_user().nil?
+            _logger.debug("Unable to find user in LDAP.")
+            redirect_to(not_authorized_url())
+            return false
+          end
+          _logger.debug("Found user in LDAP.")
+          look_for_user_in_user_table(ldap_uid) if using_user_table?
+        end
+        
+        # Check if user is in user table.  If found, update columns
+        # with LDAP attributes of same name.
+        def look_for_user_in_user_table(ldap_uid)
+          _logger.debug("Looking for user in user table.")
+          if ar_user = User.find_by_ldap_uid(ldap_uid)
+            _logger.debug("Found user.")
+            self.user_table_id = ar_user.id
+            update_user_table(ldap_user, ar_user)
+            return true
+          else
+            _logger.debug("User NOT found.")
+          end
+        end
+
+        # Update User table entry with values from UCB::LDAP::Person instance.
+        # This happens automatically when a user logs in and is found in
+        # the User table.
+        #
+        # Applications can call this to update user table entries with
+        # (presumably more current) LDAP information.  Each column name that
+        # has a corresponding LDAP attribute or alias will be updated.
+        def update_user_table(ldap_user, ar_user) #:doc:
+          _logger.debug("Updating users attributes to match LDAP.")
+          User.content_columns.each do |col|
+            begin
+              ar_user.send("#{col.name}=", ldap_user.send(col.name.to_sym) )
+            rescue NoMethodError
+              # It's okay.  Don't have LDAP attribute for given column.
+            end
+          end
+          ar_user.save
+        end
+        
+        # Returns +true+ if using a User table.  
+        # Gets value from UCB::Rails::Security::using_user_table?.
+        def using_user_table?() #:doc:
+          UCB::Rails::Security::using_user_table?
+        end
+        
+        # Returns LDAP_UID of logged in user 
+        def ldap_uid() #:doc:
+          session[:cas_user]
+        end
+
+        # Returns UCB::LDAP::Person instance of logged in user.
+        def ldap_user() #:doc:
+          session[:ldap_user]
+        end
+
+        # Returns +id+ column from User table for logged in user.
+        def user_table_id() #:doc:
+          session[:user_table_id]
+        end
+        
+        # Returns the User table instance for the logged in user.
+        def user_table_user() #:doc:
+          user_table_id && (@user_table_user ||= User.find(user_table_id))
+        end
+
+        # Returns +true+ if user is logged in.  Does <b>not</b>
+        # attempt to authenticate.
+        def logged_in?() #:doc:
+          ldap_user ? true : false
+        end
+
+        # Returns +true+ if user is logged in and was found in User table.
+        # At authentication time.  Does <b>not</b> attempt to find user.
+        def in_user_table?() #:doc:
+          user_table_id ? true : false
+        end
+
+        # Setter for ldap_user.
+        def ldap_user=(ldap_user) 
+          session[:ldap_user] = ldap_user
+        end
+
+        # Setter for user_table_id.
+        def user_table_id=(user_table_id) 
+          session[:user_table_id] = user_table_id
+        end
+
+        # Setter for user_table_user.
+        def user_table_user=(user_table_instance)
+          @user_table_user = user_table_instance
+        end
+
+        # Dynamic filter implementation.
+        def method_missing(method, *args)
+          return super unless method.to_s =~ /^filter_(ldap|user|role)_(.+)$/
+          
+          _logger.debug("#{method} dispatched to method_missing()")
+          
+          _logger.debug("before filter_logged_in")
+          filter_logged_in or return false
+          _logger.debug("after filter_logged_in")
+          
+          _logger.debug("Beginning Authorization")
+          return true if case
+            when $1 == "ldap": filter_ldap($2)
+            when $1 == "user": filter_user($2)
+            when $1 == "role": filter_role($2)
+          end
+          
+          redirect_to(not_authorized_url)
+          _logger.debug("Authorization Failed")
+          return false
+        end  
+      
+        # Processes LDAP filters.
+        def filter_ldap(method)
+          _logger.debug("In filter_ldap(): processing LDAP based authorization filters")
+          (method =~ /(.+)__(.+)__(.+)/) ? filter_extended(ldap_user.send($1), $2, $3) : ldap_boolean(ldap_user.send(method))
+        end
+    
+        # Implements a special definition of truth for the purposes
+        # of the ldap filters.  Empty strings, empty arrays,
+        # and arrays that only have nil/empty elements are all false.
+        def ldap_boolean(ldap_attribute_value)
+          ( ldap_attribute_value && ("#{ldap_attribute_value}".strip != '') ) ? true : false
+        end
+    
+        # +eval+ a boolean expression
+        def filter_extended(left, operator, right)
+          return eval("'#{left}' #{OPERATOR_METHODS[operator]} '#{right}'")
+        end
+
+        # Returns +true+ if user in user table.  If not logged in, user
+        # is redirected to CAS authentication.
+        def filter_in_user_table() #:doc:
+          filter_logged_in or return false
+          user_table_id ? true : false
+        end
+    
+        # Prcoess User-based filters
+        def filter_user(method)
+          _logger.debug("In filter_user(): processing user based authorization filters")
+          unless UCB::Rails::Security.using_user_table?
+            _logger.debug("User table not enabled.")
+            raise(Exception, "You must enable the user table to use user based filters")
+            return false
+          end
+          filter_in_user_table or return false
+          return filter_extended(user_table_user.send($1), $2, $3) if method =~ /(.+)__(.+)__(.+)/ 
+          user_table_user.send(method)
+        end
+  
+        # Process Role-based filters
+        def filter_role(method)
+          _logger.debug("In filter_role(): processing role based authorization filters")
+          unless UCB::Rails::Security.using_user_table?
+             _logger.debug("User table not enabled.")
+             raise(Exception, "You must enable the user table to use role based filters")
+             return false
+           end
+          filter_in_user_table or return false
+          return roles_has_one_of($1) if method =~ /^has_one_of_(.+)$/
+          return roles_has_all_of($1) if method =~ /^has_all_of_(.+)$/
+          role_names.include?(method.downcase)
+        end
+
+        # Returns +true+ if user has one of specified roles.
+        # 
+        # Called like:
+        # 
+        #   before_filter filter_role_has_one_of_role1_or_role2_or_role3
+        #
+        def roles_has_one_of(roles_string)
+          (roles_array(roles_string) & role_names).size > 0
+        end
+        
+        # Returns +true+ if user has all specified roles.
+        # 
+        # Called like:
+        # 
+        #   before_filter filter_role_has_all_of_role1_and_role2_and_role3
+        #
+        def roles_has_all_of(roles_string)
+          (roles_array(roles_string) - role_names).size == 0
+        end
+        
+        # Parse role string.
+        def roles_array(roles_string)
+          roles_string.downcase.split(/_and_|_or_/)
+        end
+        
+        # Returns +Array+ of +Role+ for logged in user.
+        def roles() #:doc:
+          user_table_user && user_table_user.roles
+        end
+        
+        # Returns +Array+ of user's role names, lowercased.  Returns
+        # +nil+ if user is not in user table (or not logged in).
+        def role_names() #:doc:
+          roles && roles.map{|r| r.name.downcase}
+        end
+
+        # Returns url where user is redirected upon failed authorization.
+        def not_authorized_url() #:doc:
+          UCB::Rails::Security.not_authorized_url
+        end
+
+        # Add HELPER_METHODS to controller classes including this module.
+        def self.included(base)
+          base.send(:helper_method, HELPER_METHODS)
+        end 
+        
+        def _logger
+          UCB::Rails::Security.logger
+        end
+        
+      end
+    end
+  end
+end

data/rdoc_includes/application_controller_rb.txt

@@ -0,0 +1,9 @@
+
+You also neet to <tt>include<tt> UCB::Rails::Security::ControllerMethods</tt>
+in your controller class.  This can be done in each controller, but should probably be done in <tt>application.rb</tt>:
+
+  # ../app/controllers/application.rb
+  
+  class ApplicationController < ActionController::Base
+    include UCB::Rails::Security::ControllerMethods
+  end

data/rspec/_all_specs.rb

@@ -0,0 +1,5 @@
+# Run unit tests in files ending in "*_spec.rb".
+test_dir = File.dirname(__FILE__)
+Dir["#{test_dir}/*_spec.rb"].each do |file|
+  require file
+end

data/rspec/_setup.rb

@@ -0,0 +1,36 @@
+$TESTING = true
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "ucb_rails_security"
+
+# Swallow logger calls during testing
+module Mock
+  class Logger
+     def debug(msg); end
+     def info(msg); end
+  end
+end
+UCB::Rails::Security.logger = Mock::Logger.new
+
+def reset_cas_authentication_class()
+  ca = UCB::Rails::Security::CASAuthentication
+  ca.reset_instance_variables()
+  ca
+end
+
+# Mixin like a Rails application will
+module ActionController
+  class Base
+    include UCB::Rails::Security::ControllerMethods
+  end
+end
+
+# Return new ActionController::Base
+def new_controller
+  c = ActionController::Base.new
+  c.session = {}
+  c
+end
+
+class User
+end

data/rspec/filter_ldap_spec.rb

@@ -0,0 +1,87 @@
+require "#{File.dirname(__FILE__)}/_setup.rb"
+
+context "For an LDAP attribute" do
+  setup do
+    @controller = new_controller()
+  end
+  
+  specify "true is true" do
+    @controller.ldap_boolean(true).should be_true
+  end
+
+  specify "a string is true" do
+    @controller.ldap_boolean("x").should be_true
+  end
+
+  specify "a number, including 0, is true" do
+    @controller.ldap_boolean(0).should be_true
+  end
+
+  specify "a populated Array is true" do
+    @controller.ldap_boolean(["x"]).should be_true
+  end
+  
+  specify "false is false" do
+    @controller.ldap_boolean(false).should be_false
+  end
+  specify "nil is false" do
+    @controller.ldap_boolean(nil).should be_false
+  end
+  specify "' ' is false" do
+    @controller.ldap_boolean(' ').should be_false
+  end
+  specify "[] is false" do
+    @controller.ldap_boolean([]).should be_false
+  end
+end
+
+context "When a user is not logged in to the application" do
+  setup do
+    @controller = new_controller()
+    @controller.should_receive(:filter_logged_in)
+  end
+
+  specify "call to ldap_filter should call filter_logged_in" do
+    @controller.filter_ldap_anthing
+  end
+end
+
+context "When a user is logged in to the application" do
+  before(:all) do
+    RAILS_ENV = "re"
+  end
+  
+  setup do
+    @ldap_uid = '42'
+    @ldap_user = mock("ldap_user")
+    UCB::LDAP::Person.stub!(:find_by_uid).and_return(@ldap_user)
+    User.stub!(:find_by_ldap_uid)
+    @controller = new_controller()
+    @controller.application_login(@uid)
+    @controller.stub!(:redirect_to)
+    @controller.stub!(:not_authorized_url).and_return("nal")
+  end
+
+  specify "filter_ldap_method returns 'true' when ldap.method does" do
+    @ldap_user.stub!(:attr_true).and_return(true)
+    @controller.filter_ldap_attr_true.should be_true
+  end
+
+  specify "filter_ldap_method returns 'false' when ldap.method does" do
+    @ldap_user.stub!(:attr_false).and_return(false)
+    @controller.filter_ldap_attr_false.should be_false
+  end
+  
+  specify "filter_ldap_method__eq__value is true if ldap.method eq 'value'" do
+    @ldap_user.stub!(:attr).and_return("a")
+    @controller.filter_ldap_attr__eq__a.should be_true
+    @controller.filter_ldap_attr__eq__b.should be_false
+  end
+  
+  specify "filter_ldap_method__ne__value is true if ldap.method ne 'value'" do
+    @ldap_user.stub!(:attr).and_return("a")
+    @controller.filter_ldap_attr__ne__b.should be_true
+    @controller.filter_ldap_attr__ne__a.should be_false
+  end
+  
+end

data/rspec/filter_role_spec.rb

@@ -0,0 +1,56 @@
+require "#{File.dirname(__FILE__)}/_setup.rb"
+
+context "The Role filter" do
+  setup do
+    @controller = new_controller()
+    UCB::Rails::Security.using_user_table = true
+  end
+
+  specify "should call filter_logged_in when user not logged in" do
+    @controller.should_receive(:filter_logged_in).and_return(false)
+    @controller.filter_role_foo.should be_false
+  end
+  
+  specify "should call filter_in_user_table() when user logged in" do
+    @controller.stub!(:filter_logged_in).and_return(true)
+    @controller.should_receive(:filter_in_user_table).and_return(false)
+    @controller.stub!(:redirect_to)
+    @controller.stub!(:not_authorized_url).and_return("nal")
+    @controller.filter_role_foo.should be_false
+  end
+end
+
+describe "Role filters" do
+  before(:each) do
+    @controller = new_controller()
+    @controller.stub!(:role_names).and_return(%w{role1 role2 role3})
+    @controller.stub!(:filter_logged_in).and_return(true)
+    @controller.stub!(:filter_in_user_table).and_return(true)
+    @controller.stub!(:redirect_to)
+    @controller.stub!(:not_authorized_url).and_return("nal")
+  end
+  
+  it "filter_role_rolename should return true if one of user's roles is 'rolename'" do
+    @controller.filter_role_role1.should be_true
+  end
+  
+  it "filter_role_rolename should return false unless one of user's roles is 'rolename'" do
+    @controller.filter_role_bogus.should_not be_true
+  end
+  
+  it "filter_role_has_one_of_r1_or_r2_or_r3 returns true if user has one of the roles" do
+    @controller.filter_role_has_one_of_role3_or_role4.should be_true
+  end
+
+  it "filter_role_has_one_of_r1_or_r2_or_r3 returns false unless user has one of the roles" do
+    @controller.filter_role_has_one_of_role4_or_role5.should be_false
+  end
+
+  it "filter_role_has_all_of_r1_and_r2_and_r3 returns true if user has all of the roles" do
+    @controller.filter_role_has_all_of_role1_and_role2.should be_true
+  end
+
+  it "filter_role_has_one_of_r1_and_r2_and_r3 returns false unless user has one of the roles" do
+    @controller.filter_role_has_all_of_role3_and_role4.should be_false
+  end
+end