authlogic-rails3 2.2

data/lib/authlogic/session/session.rb

@@ -0,0 +1,62 @@
+module Authlogic
+  module Session
+    # Handles all parts of authentication that deal with sessions. Such as persisting a session and saving / destroy a session.
+    module Session
+      def self.included(klass)
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          persist :persist_by_session
+          after_save :update_session
+          after_destroy :update_session
+          after_persisting :update_session, :unless => :single_access?
+        end
+      end
+      
+      # Configuration for the session feature.
+      module Config
+        # Works exactly like cookie_key, but for sessions. See cookie_key for more info.
+        #
+        # * <tt>Default:</tt> cookie_key
+        # * <tt>Accepts:</tt> Symbol or String
+        def session_key(value = nil)
+          rw_config(:session_key, value, cookie_key)
+        end
+        alias_method :session_key=, :session_key
+      end
+      
+      # Instance methods for the session feature.
+      module InstanceMethods
+        private
+          # Tries to validate the session from information in the session
+          def persist_by_session
+            persistence_token, record_id = session_credentials
+            if !persistence_token.nil?
+              # Allow finding by persistence token, because when records are created the session is maintained in a before_save, when there is no id.
+              # This is done for performance reasons and to save on queries.
+              record = record_id.nil? ?
+                search_for_record("find_by_persistence_token", persistence_token) :
+                search_for_record("find_by_#{klass.primary_key}", record_id)
+              self.unauthorized_record = record if record && record.persistence_token == persistence_token
+              valid?
+            else
+              false
+            end
+          end
+          
+          def session_credentials
+            [controller.session[session_key], controller.session["#{session_key}_#{klass.primary_key}"]].compact
+          end
+          
+          def session_key
+            build_key(self.class.session_key)
+          end
+          
+          def update_session
+            controller.session[session_key] = record && record.persistence_token
+            controller.session["#{session_key}_#{klass.primary_key}"] = record && record.send(record.class.primary_key)
+          end
+      end
+    end
+  end
+end

data/lib/authlogic/session/timeout.rb

@@ -0,0 +1,82 @@
+module Authlogic
+  module Session
+    # Think about financial websites, if you are inactive for a certain period of time you will be asked to
+    # log back in on your next request. You can do this with Authlogic easily, there are 2 parts to this:
+    #
+    # 1. Define the timeout threshold:
+    #
+    #   acts_as_authentic do |c|
+    #     c.logged_in_timeout = 10.minutes # default is 10.minutes
+    #   end
+    #
+    # 2. Enable logging out on timeouts
+    #
+    #   class UserSession < Authlogic::Session::Base
+    #     logout_on_timeout true # default if false
+    #   end
+    #
+    # This will require a user to log back in if they are inactive for more than 10 minutes. In order for
+    # this feature to be used you must have a last_request_at datetime column in your table for whatever model
+    # you are authenticating with.
+    module Timeout
+      def self.included(klass)
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          before_persisting :reset_stale_state
+          after_persisting :enforce_timeout
+          attr_accessor :stale_record
+        end
+      end
+      
+      # Configuration for the timeout feature.
+      module Config
+        # With acts_as_authentic you get a :logged_in_timeout configuration option. If this is set, after this amount of time has passed the user
+        # will be marked as logged out. Obviously, since web based apps are on a per request basis, we have to define a time limit threshold that
+        # determines when we consider a user to be "logged out". Meaning, if they login and then leave the website, when do mark them as logged out?
+        # I recommend just using this as a fun feature on your website or reports, giving you a ballpark number of users logged in and active. This is
+        # not meant to be a dead accurate representation of a users logged in state, since there is really no real way to do this with web based apps.
+        # Think about a user that logs in and doesn't log out. There is no action that tells you that the user isn't technically still logged in and
+        # active.
+        #
+        # That being said, you can use that feature to require a new login if their session timesout. Similar to how financial sites work. Just set this option to
+        # true and if your record returns true for stale? then they will be required to log back in.
+        #
+        # Lastly, UserSession.find will still return a object is the session is stale, but you will not get a record. This allows you to determine if the
+        # user needs to log back in because their session went stale, or because they just aren't logged in. Just call current_user_session.stale? as your flag.
+        #
+        # * <tt>Default:</tt> false
+        # * <tt>Accepts:</tt> Boolean
+        def logout_on_timeout(value = nil)
+          rw_config(:logout_on_timeout, value, false)
+        end
+        alias_method :logout_on_timeout=, :logout_on_timeout
+      end
+      
+      # Instance methods for the timeout feature.
+      module InstanceMethods
+        # Tells you if the record is stale or not. Meaning the record has timed out. This will only return true if you set logout_on_timeout to true in your configuration.
+        # Basically how a bank website works. If you aren't active over a certain period of time your session becomes stale and requires you to log back in.
+        def stale?
+          !stale_record.nil? || (logout_on_timeout? && record && record.logged_out?)
+        end
+    
+        private
+          def reset_stale_state
+            self.stale_record = nil
+          end
+          
+          def enforce_timeout
+            if stale?
+              self.stale_record = record
+              self.record = nil
+            end
+          end
+          
+          def logout_on_timeout?
+            self.class.logout_on_timeout == true
+          end
+      end
+    end
+  end
+end

data/lib/authlogic/session/unauthorized_record.rb

@@ -0,0 +1,50 @@
+module Authlogic
+  module Session
+    # Allows you to create session with an object. Ex:
+    #
+    #   UserSession.create(my_user_object)
+    #
+    # Be careful with this, because Authlogic is assuming that you have already confirmed that the
+    # user is who he says he is.
+    #
+    # For example, this is the method used to persist the session internally. Authlogic finds the user with
+    # the persistence token. At this point we know the user is who he says he is, so Authlogic just creates a
+    # session with the record. This is particularly useful for 3rd party authentication methods, such as
+    # OpenID. Let that method verify the identity, once it's verified, pass the object and create a session.
+    module UnauthorizedRecord
+      def self.included(klass)
+        klass.class_eval do
+          attr_accessor :unauthorized_record
+          validate :validate_by_unauthorized_record, :if => :authenticating_with_unauthorized_record?
+        end
+      end
+      
+      # Returning meaningful credentials
+      def credentials
+        if authenticating_with_unauthorized_record?
+          details = {}
+          details[:unauthorized_record] = "<protected>"
+          details
+        else
+          super
+        end
+      end
+      
+      # Setting the unauthorized record if it exists in the credentials passed.
+      def credentials=(value)
+        super
+        values = value.is_a?(Array) ? value : [value]
+        self.unauthorized_record = values.first if values.first.class < ::ActiveRecord::Base
+      end
+      
+      private
+        def authenticating_with_unauthorized_record?
+          !unauthorized_record.nil?
+        end
+        
+        def validate_by_unauthorized_record
+          self.attempted_record = unauthorized_record
+        end
+    end
+  end
+end

data/lib/authlogic/session/validation.rb

@@ -0,0 +1,82 @@
+module Authlogic
+  module Session
+    # Responsible for session validation
+    module Validation
+      # The errors in Authlogic work JUST LIKE ActiveRecord. In fact, it uses the exact same ActiveRecord errors class. Use it the same way:
+      #
+      #   class UserSession
+      #     validate :check_if_awesome
+      #
+      #     private
+      #       def check_if_awesome
+      #         errors.add(:login, "must contain awesome") if login && !login.include?("awesome")
+      #         errors.add(:base, "You must be awesome to log in") unless attempted_record.awesome?
+      #       end
+      #   end
+      class Errors < (defined?(::ActiveModel) ? ::ActiveModel::Errors : ::ActiveRecord::Errors)
+        unless defined?(::ActiveModel)
+          def [](key)
+            value = super
+            value.is_a?(Array) ? value : [value].compact
+          end
+        end
+      end
+      
+      # You should use this as a place holder for any records that you find during validation. The main reason for this is to
+      # allow other modules to use it if needed. Take the failed_login_count feature, it needs this in order to increase
+      # the failed login count.
+      def attempted_record
+        @attempted_record
+      end
+      
+      # See attempted_record
+      def attempted_record=(value)
+        @attempted_record = value
+      end
+      
+      # The errors in Authlogic work JUST LIKE ActiveRecord. In fact, it uses the exact same ActiveRecord errors class.
+      # Use it the same way:
+      #
+      # === Example
+      #
+      #  class UserSession
+      #    before_validation :check_if_awesome
+      #
+      #    private
+      #      def check_if_awesome
+      #        errors.add(:login, "must contain awesome") if login && !login.include?("awesome")
+      #        errors.add(:base, "You must be awesome to log in") unless attempted_record.awesome?
+      #      end
+      #  end
+      def errors
+        @errors ||= Errors.new(self)
+      end
+      
+      # Determines if the information you provided for authentication is valid or not. If there is
+      # a problem with the information provided errors will be added to the errors object and this
+      # method will return false.
+      def valid?
+        errors.clear
+        self.attempted_record = nil
+        
+        before_validation
+        new_session? ? before_validation_on_create : before_validation_on_update
+        validate
+        ensure_authentication_attempted
+                
+        if errors.size == 0
+          new_session? ? after_validation_on_create : after_validation_on_update
+          after_validation
+        end
+        
+        save_record(attempted_record)
+        errors.size == 0
+      end
+      
+      private
+        def ensure_authentication_attempted
+          errors.add(:base, I18n.t('error_messages.no_authentication_details', :default => "You did not provide any details for authentication.")) if errors.empty? && attempted_record.nil?
+        end
+    end
+  end
+end

data/lib/authlogic/test_case.rb

@@ -0,0 +1,120 @@
+require File.dirname(__FILE__) + "/test_case/rails_request_adapter"
+require File.dirname(__FILE__) + "/test_case/mock_cookie_jar"
+require File.dirname(__FILE__) + "/test_case/mock_controller"
+require File.dirname(__FILE__) + "/test_case/mock_logger"
+require File.dirname(__FILE__) + "/test_case/mock_request"
+
+module Authlogic
+  # This module is a collection of methods and classes that help you easily test Authlogic. In fact,
+  # I use these same tools to test the internals of Authlogic.
+  #
+  # === The quick and dirty
+  #
+  #   require "authlogic/test_case" # include at the top of test_helper.rb
+  #   setup :activate_authlogic # run before tests are executed
+  #   UserSession.create(users(:whomever)) # logs a user in
+  #
+  # For a more detailed explanation, see below.
+  #
+  # === Setting up
+  #
+  # Authlogic comes with some simple testing tools. To get these, you need to first require Authlogic's TestCase. If
+  # you are doing this in a rails app, you would require this file at the top of your test_helper.rb file:
+  #
+  #   require "authlogic/test_case"
+  #
+  # If you are using Test::Unit::TestCase, the standard testing library that comes with ruby, then you can skip this next part.
+  # If you are not, you need to include the Authlogic::TestCase into your testing suite as follows:
+  #
+  #   include Authlogic::TestCase
+  #
+  # Now that everything is ready to go, let's move onto actually testing. Here is the basic idea behind testing:
+  #
+  # Authlogic requires a "connection" to your controller to activate it. In the same manner that ActiveRecord requires a connection to
+  # your database. It can't do anything until it gets connnected. That being said, Authlogic will raise an
+  # Authlogic::Session::Activation::NotActivatedError any time you try to instantiate an object without a "connection".
+  # So before you do anything with Authlogic, you need to activate / connect Authlogic. Let's walk through how to do this in tests:
+  #
+  # === Fixtures / Factories
+  #
+  # Creating users via fixtures / factories is easy. Here's an example of a fixture:
+  #
+  #   ben:
+  #     email: whatever@whatever.com
+  #     password_salt: <%= salt = Authlogic::Random.hex_token %>
+  #     crypted_password: <%= Authlogic::CryptoProviders::Sha512.encrypt("benrocks" + salt) %>
+  #     persistence_token: <%= Authlogic::Random.hex_token %>
+  #     single_access_token: <%= Authlogic::Random.friendly_token %>
+  #     perishable_token: <%= Authlogic::Random.friendly_token %>
+  #
+  # Notice the crypted_password value. Just supplement that with whatever crypto provider you are using, if you are not using the default.
+  #
+  # === Functional tests
+  #
+  # Activating Authlogic isn't a problem here, because making a request will activate Authlogic for you. The problem is
+  # logging users in so they can access restricted areas. Solving this is simple, just do this:
+  #
+  #   setup :activate_authlogic
+  #
+  # For those of you unfamiliar with TestUnit, the setup method bascially just executes a method before any test is ran.
+  # It is essentially "setting up" your tests.
+  #
+  # Once you have done this, just log users in like usual:
+  #
+  #   UserSession.create(users(:whomever))
+  #   # access my restricted area here
+  #
+  # Do this before you make your request and it will act as if that user is logged in.
+  #
+  # === Integration tests
+  #
+  # Again, just like functional tests, you don't have to do anything. As soon as you make a request, Authlogic will be
+  # conntected. If you want to activate Authlogic before making a request follow the same steps described in the
+  # "functional tests" section above. It works in the same manner.
+  #
+  # === Unit tests
+  #
+  # The only time you need to do any trickiness here is if you want to test Authlogic models. Maybe you added some custom
+  # code or methods in your Authlogic models. Maybe you are writing a plugin or a library that extends Authlogic.
+  #
+  # That being said, in this environment there is no controller. So you need to use a "mock" controller. Something
+  # that looks like a controller, acts like a controller, but isn't a "real" controller. You are essentially connecting
+  # Authlogic to your "mock" controller, then you can test off of the mock controller to make sure everything is functioning
+  # properly.
+  # 
+  # I use a mock controller to test Authlogic myself. It's part of the Authlogic library that you can easily use. It's as simple
+  # as functional and integration tests. Just do the following:
+  #
+  #   setup :activate_authlogic
+  #
+  # You also get a controller method that you can test off of. For example:
+  #
+  #   ben = users(:ben)
+  #   assert_nil controller.session["user_credentials"]
+  #   assert UserSession.create(ben)
+  #   assert_equal controller.session["user_credentials"], ben.persistence_token
+  #
+  # See how I am checking that Authlogic is interacting with the controller properly? That's the idea here.
+  module TestCase
+    # Activates authlogic so that you can use it in your tests. You should call this method in your test's setup. Ex:
+    #
+    #   setup :activate_authlogic
+    def activate_authlogic
+      if @request && ! @request.respond_to?(:params)
+        class <<@request
+          alias_method :params, :parameters
+        end
+      end
+
+      Authlogic::Session::Base.controller = (@request && Authlogic::TestCase::RailsRequestAdapter.new(@request)) || controller
+    end
+    
+    # The Authlogic::TestCase::MockController object passed to Authlogic to activate it. You can access this in your test.
+    # See the module description for an example.
+    def controller
+      @controller ||= Authlogic::TestCase::MockController.new
+    end
+  end
+  
+  ::Test::Unit::TestCase.send(:include, TestCase) if defined?(::Test::Unit::TestCase)
+end

data/lib/authlogic/test_case/mock_controller.rb

@@ -0,0 +1,45 @@
+module Authlogic
+  module TestCase
+    # Basically acts like a controller but doesn't do anything. Authlogic can interact with this, do it's thing and then you
+    # can look at the controller object to see if anything changed.
+    class MockController < ControllerAdapters::AbstractAdapter
+      attr_accessor :http_user, :http_password
+      attr_writer :request_content_type
+  
+      def initialize
+      end
+  
+      def authenticate_with_http_basic(&block)
+        yield http_user, http_password
+      end
+  
+      def cookies
+        @cookies ||= MockCookieJar.new
+      end
+  
+      def cookie_domain
+        nil
+      end
+      
+      def logger
+        @logger ||= MockLogger.new
+      end
+  
+      def params
+        @params ||= {}
+      end
+  
+      def request
+        @request ||= MockRequest.new(controller)
+      end
+  
+      def request_content_type
+        @request_content_type ||= "text/html"
+      end
+  
+      def session
+        @session ||= {}
+      end
+    end
+  end
+end

data/lib/authlogic/test_case/mock_cookie_jar.rb

@@ -0,0 +1,14 @@
+module Authlogic
+  module TestCase
+    class MockCookieJar < Hash # :nodoc:
+      def [](key)
+        hash = super
+        hash && hash[:value]
+      end
+  
+      def delete(key, options = {})
+        super(key)
+      end
+    end
+  end
+end