binarylogic-authlogic 2.1.0

data/lib/authlogic/session/params.rb

@@ -0,0 +1,100 @@
+module Authlogic
+  module Session
+    # This module is responsible for authenticating the user via params, which ultimately allows the user to log in using a URL like the following:
+    #
+    #   https://www.domain.com?user_credentials=4LiXF7FiGUppIPubBPey
+    #
+    # Notice the token in the URL, this is a single access token. A single access token is used for single access only, it is not persisted. Meaning the user
+    # provides it, Authlogic grants them access, and that's it. If they want access again they need to provide the token again. Authlogic will
+    # *NEVER* try to persist the session after authenticating through this method.
+    #
+    # For added security, this token is *ONLY* allowed for RSS and ATOM requests. You can change this with the configuration. You can also define if
+    # it is allowed dynamically by defining a single_access_allowed? method in your controller. For example:
+    #
+    #   class UsersController < ApplicationController
+    #     private
+    #       def single_access_allowed?
+    #         action_name == "index"
+    #       end
+    #
+    # Also, by default, this token is permanent. Meaning if the user changes their password, this token will remain the same. It will only change
+    # when it is explicitly reset.
+    #
+    # You can modify all of this behavior with the Config sub module.
+    module Params
+      def self.included(klass)
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          attr_accessor :single_access
+          persist :persist_by_params
+        end
+      end
+      
+      # Configuration for the params / single access feature.
+      module Config
+        # Works exactly like cookie_key, but for params. So a user can login via params just like a cookie or a session. Your URL would look like:
+        #
+        #   http://www.domain.com?user_credentials=my_single_access_key
+        #
+        # You can change the "user_credentials" key above with this configuration option. Keep in mind, just like cookie_key, if you supply an id
+        # the id will be appended to the front. Check out cookie_key for more details. Also checkout the "Single Access / Private Feeds Access" section in the README.
+        #
+        # * <tt>Default:</tt> cookie_key
+        # * <tt>Accepts:</tt> String
+        def params_key(value = nil)
+          rw_config(:params_key, value, cookie_key)
+        end
+        alias_method :params_key=, :params_key
+        
+        # Authentication is allowed via a single access token, but maybe this is something you don't want for your application as a whole. Maybe this is something you only want for specific request types.
+        # Specify a list of allowed request types and single access authentication will only be allowed for the ones you specify.
+        #
+        # * <tt>Default:</tt> ["application/rss+xml", "application/atom+xml"]
+        # * <tt>Accepts:</tt> String of a request type, or :all or :any to allow single access authentication for any and all request types
+        def single_access_allowed_request_types(value = nil)
+          rw_config(:single_access_allowed_request_types, value, ["application/rss+xml", "application/atom+xml"])
+        end
+        alias_method :single_access_allowed_request_types=, :single_access_allowed_request_types
+      end
+      
+      # The methods available for an Authlogic::Session::Base object that make up the params / single access feature.
+      module InstanceMethods
+        private
+          def persist_by_params
+            return false if !params_enabled?
+            self.unauthorized_record = search_for_record("find_by_single_access_token", params_credentials)
+            self.single_access = valid?
+          end
+          
+          def params_enabled?
+            return false if !params_credentials || !klass.column_names.include?("single_access_token")
+            return controller.single_access_allowed? if controller.responds_to_single_access_allowed?
+            
+            case single_access_allowed_request_types
+            when Array
+              single_access_allowed_request_types.include?(controller.request_content_type) || single_access_allowed_request_types.include?(:all)
+            else
+              [:all, :any].include?(single_access_allowed_request_types)
+            end
+          end
+          
+          def params_key
+            build_key(self.class.params_key)
+          end
+          
+          def single_access?
+            single_access == true
+          end
+          
+          def single_access_allowed_request_types
+            self.class.single_access_allowed_request_types
+          end
+          
+          def params_credentials
+            controller.params[params_key]
+          end
+      end
+    end
+  end
+end

data/lib/authlogic/session/password.rb

@@ -0,0 +1,218 @@
+module Authlogic
+  module Session
+    # Handles authenticating via a traditional username and password.
+    module Password
+      def self.included(klass)
+        klass.class_eval do
+          extend Config
+          include InstanceMethods
+          validate :validate_by_password, :if => :authenticating_with_password?
+          
+          class << self
+            attr_accessor :configured_password_methods
+          end
+        end
+      end
+      
+      # Password configuration
+      module Config
+        # Authlogic tries to validate the credentials passed to it. One part of validation is actually finding the user and making sure it exists. What method it uses the do this is up to you.
+        #
+        # Let's say you have a UserSession that is authenticating a User. By default UserSession will call User.find_by_login(login). You can change what method UserSession calls by specifying it here. Then
+        # in your User model you can make that method do anything you want, giving you complete control of how users are found by the UserSession.
+        #
+        # Let's take an example: You want to allow users to login by username or email. Set this to the name of the class method that does this in the User model. Let's call it "find_by_username_or_email"
+        #
+        #   class User < ActiveRecord::Base
+        #     def self.find_by_username_or_email(login)
+        #       find_by_username(login) || find_by_email(login)
+        #     end
+        #   end
+        #
+        # Now just specify the name of this method for this configuration option and you are all set. You can do anything you want here. Maybe you allow users to have multiple logins
+        # and you want to search a has_many relationship, etc. The sky is the limit.
+        #
+        # * <tt>Default:</tt> "find_by_smart_case_login_field"
+        # * <tt>Accepts:</tt> Symbol or String
+        def find_by_login_method(value = nil)
+          rw_config(:find_by_login_method, value, "find_by_smart_case_login_field")
+        end
+        alias_method :find_by_login_method=, :find_by_login_method
+        
+        # The text used to identify credentials (username/password) combination when a bad login attempt occurs.
+        # When you show error messages for a bad login, it's considered good security practice to hide which field
+        # the user has entered incorrectly (the login field or the password field). For a full explanation, see
+        # http://www.gnucitizen.org/blog/username-enumeration-vulnerabilities/
+        #
+        # Example of use:
+        #
+        #   class UserSession < Authlogic::Session::Base
+        #     generalize_credentials_error_messages true
+        #   end
+        #
+        # This would make the error message for bad logins and bad passwords look identical:
+        #
+        #   Login/Password combination is not valid
+        #
+        # The downside to enabling this is that is can be too vague for a user that has a hard time remembering
+        # their username and password combinations. It also disables the ability to to highlight the field
+        # with the error when you use form_for.
+        #
+        # If you are developing an app where security is an extreme priority (such as a financial application),
+        # then you should enable this. Otherwise, leaving this off is fine.
+        # 
+        # * <tt>Default</tt> false
+        # * <tt>Accepts:</tt> Boolean
+        def generalize_credentials_error_messages(value = nil)
+          rw_config(:generalize_credentials_error_messages, value, false)
+        end
+        alias_method :generalize_credentials_error_messages=, :generalize_credentials_error_messages
+        
+        # The name of the method you want Authlogic to create for storing the login / username. Keep in mind this is just for your
+        # Authlogic::Session, if you want it can be something completely different than the field in your model. So if you wanted people to
+        # login with a field called "login" and then find users by email this is compeltely doable. See the find_by_login_method configuration
+        # option for more details.
+        #
+        # * <tt>Default:</tt> klass.login_field || klass.email_field
+        # * <tt>Accepts:</tt> Symbol or String
+        def login_field(value = nil)
+          rw_config(:login_field, value, klass.login_field || klass.email_field)
+        end
+        alias_method :login_field=, :login_field
+        
+        # Works exactly like login_field, but for the password instead. Returns :password if a login_field exists.
+        #
+        # * <tt>Default:</tt> :password
+        # * <tt>Accepts:</tt> Symbol or String
+        def password_field(value = nil)
+          rw_config(:password_field, value, login_field && :password)
+        end
+        alias_method :password_field=, :password_field
+        
+        # The name of the method in your model used to verify the password. This should be an instance method. It should also be prepared to accept a raw password and a crytped password.
+        #
+        # * <tt>Default:</tt> "valid_password?"
+        # * <tt>Accepts:</tt> Symbol or String
+        def verify_password_method(value = nil)
+          rw_config(:verify_password_method, value, "valid_password?")
+        end
+        alias_method :verify_password_method=, :verify_password_method
+      end
+      
+      # Password related instance methods
+      module InstanceMethods
+        def initialize(*args)
+          if !self.class.configured_password_methods
+            if login_field
+              self.class.send(:attr_writer, login_field) if !respond_to?("#{login_field}=")
+              self.class.send(:attr_reader, login_field) if !respond_to?(login_field)
+            end
+            
+            if password_field
+              self.class.send(:attr_writer, password_field) if !respond_to?("#{password_field}=")
+              self.class.send(:define_method, password_field) {} if !respond_to?(password_field)
+
+              self.class.class_eval <<-"end_eval", __FILE__, __LINE__
+                private
+                  # The password should not be accessible publicly. This way forms using form_for don't fill the password with the attempted password. To prevent this we just create this method that is private.
+                  def protected_#{password_field}
+                    @#{password_field}
+                  end
+              end_eval
+            end
+
+            self.class.configured_password_methods = true
+          end
+          
+          super
+        end
+        
+        # Returns the login_field / password_field credentials combination in hash form.
+        def credentials
+          if authenticating_with_password?
+            details = {}
+            details[login_field.to_sym] = send(login_field)
+            details[password_field.to_sym] = "<protected>"
+            details
+          else
+            super
+          end
+        end
+        
+        # Accepts the login_field / password_field credentials combination in hash form.
+        def credentials=(value)
+          super
+          values = value.is_a?(Array) ? value : [value]
+          if values.first.is_a?(Hash)
+            values.first.with_indifferent_access.slice(login_field, password_field).each do |field, value|
+              next if value.blank?
+              send("#{field}=", value)
+            end
+          end
+        end
+        
+        def invalid_password?
+          invalid_password == true
+        end
+        
+        private
+          def authenticating_with_password?
+            login_field && (!send(login_field).nil? || !send("protected_#{password_field}").nil?)
+          end
+          
+          def validate_by_password
+            self.invalid_password = false
+            
+            errors.add(login_field, I18n.t('error_messages.login_blank', :default => "cannot be blank")) if send(login_field).blank?
+            errors.add(password_field, I18n.t('error_messages.password_blank', :default => "cannot be blank")) if send("protected_#{password_field}").blank?
+            return if errors.count > 0
+
+            self.attempted_record = search_for_record(find_by_login_method, send(login_field))
+
+            if attempted_record.blank?
+              generalize_credentials_error_messages? ? add_general_credentials_error : errors.add(login_field, I18n.t('error_messages.login_not_found', :default => "is not valid"))
+              return
+            end
+
+            if !attempted_record.send(verify_password_method, send("protected_#{password_field}"))
+              self.invalid_password = true
+              generalize_credentials_error_messages? ? add_general_credentials_error : errors.add(password_field, I18n.t('error_messages.password_invalid', :default => "is not valid"))
+              return
+            end
+          end
+          
+          def invalid_password
+            @invalid_password
+          end
+          
+          def invalid_password=(value)
+            @invalid_password = value
+          end
+          
+          def find_by_login_method
+            self.class.find_by_login_method
+          end
+          
+          def login_field
+            self.class.login_field
+          end
+          
+          def add_general_credentials_error
+            errors.add(:base, I18n.t('error_messages.general_credentials_error', :default => "#{login_field.to_s.humanize}/Password combination is not valid"))
+          end
+          
+          def generalize_credentials_error_messages?
+            self.class.generalize_credentials_error_messages == true
+          end
+          
+          def password_field
+            self.class.password_field
+          end
+          
+          def verify_password_method
+            self.class.verify_password_method
+          end
+      end
+    end
+  end
+end

data/lib/authlogic/session/perishable_token.rb

@@ -0,0 +1,18 @@
+module Authlogic
+  module Session
+    # Maintains the perishable token, which is helpful for confirming records or authorizing records to reset their password. All that this
+    # module does is reset it after a session have been saved, just keep it changing. The more it changes, the tighter the security.
+    #
+    # See Authlogic::ActsAsAuthentic::PerishableToken for more information.
+    module PerishableToken
+      def self.included(klass)
+        klass.after_save :reset_perishable_token!
+      end
+      
+      private
+        def reset_perishable_token!
+          record.reset_perishable_token if record.respond_to?(:reset_perishable_token) && !record.disable_perishable_token_maintenance?
+        end
+    end
+  end
+end

data/lib/authlogic/session/persistence.rb

@@ -0,0 +1,70 @@
+module Authlogic
+  module Session
+    # Responsible for allowing you to persist your sessions.
+    module Persistence
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+        end
+      end
+      
+      module ClassMethods
+        # This is how you persist a session. This finds the record for the current session using
+        # a variety of methods. It basically tries to "log in" the user without the user having
+        # to explicitly log in. Check out the other Authlogic::Session modules for more information.
+        #
+        # The best way to use this method is something like:
+        #
+        #   helper_method :current_user_session, :current_user
+        #
+        #   def current_user_session
+        #     return @current_user_session if defined?(@current_user_session)
+        #     @current_user_session = UserSession.find
+        #   end
+        #
+        #   def current_user
+        #     return @current_user if defined?(@current_user)
+        #     @current_user = current_user_session && current_user_session.user
+        #   end
+        #
+        # Also, this method accepts a single parameter as the id, to find session that you marked with an id:
+        #
+        #   UserSession.find(:secure)
+        #
+        # See the id method for more information on ids.
+        def find(id = nil, priority_record = nil)
+          session = new({:priority_record => priority_record}, id)
+          session.priority_record = priority_record
+          if session.persisting?
+            session
+          else
+            nil
+          end
+        end
+      end
+      
+      module InstanceMethods
+        # Let's you know if the session is being persisted or not, meaning the user does not have to explicitly log in
+        # in order to be logged in. If the session has no associated record, it will try to find a record and persis
+        # the session. This is the method that the class level method find uses to ultimately persist the session.
+        def persisting?
+          return true if !record.nil?
+          self.attempted_record = nil
+          before_persisting
+          persist
+          ensure_authentication_attempted
+          if errors.empty? && !attempted_record.nil?
+            self.record = attempted_record
+            after_persisting
+            save_record
+            self.new_session = false
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/authlogic/session/priority_record.rb

@@ -0,0 +1,34 @@
+module Authlogic
+  module Session
+    # The point of this module is to avoid the StaleObjectError raised when lock_version is implemented in ActiveRecord.
+    # We accomplish this by using a "priority record". Meaning this record is used if possible, it gets priority.
+    # This way we don't save a record behind the scenes thus making an object being used stale.
+    module PriorityRecord
+      def self.included(klass)
+        klass.class_eval do
+          attr_accessor :priority_record
+        end
+      end
+      
+      # Setting priority record if it is passed. The only way it can be passed is through an array:
+      #
+      #   session.credentials = [real_user_object, priority_user_object]
+      def credentials=(value)
+        super
+        values = value.is_a?(Array) ? value : [value]
+        self.priority_record = values[1] if values[1].class < ::ActiveRecord::Base
+      end
+      
+      private
+        def attempted_record=(value)
+          value = priority_record if value == priority_record
+          super
+        end
+        
+        def save_record(alternate_record = nil)
+          r = alternate_record || record
+          super if r != priority_record
+        end
+    end
+  end
+end

data/lib/authlogic/session/scopes.rb

@@ -0,0 +1,101 @@
+module Authlogic
+  module Session
+    # Authentication can be scoped, and it's easy, you just need to define how you want to scope everything. This should help you:
+    #
+    # 1. Want to scope by a parent object? Ex: An account has many users. Checkout Authlogic::AuthenticatesMany
+    # 2. Want to scope the validations in your model? Ex: 2 users can have the same login under different accounts. See Authlogic::ActsAsAuthentic::Scope
+    module Scopes # :nodoc:
+      def self.included(klass)
+        klass.class_eval do
+          extend ClassMethods
+          include InstanceMethods
+          attr_writer :scope
+        end
+      end
+      
+      # = Scopes
+      module ClassMethods
+        # The current scope set, should be used in the block passed to with_scope.
+        def scope
+          Thread.current[:authlogic_scope]
+        end
+        
+        # What with_scopes focuses on is scoping the query when finding the object and the name of the cookie / session. It works very similar to
+        # ActiveRecord::Base#with_scopes. It accepts a hash with any of the following options:
+        #
+        # * <tt>find_options:</tt> any options you can pass into ActiveRecord::Base.find. This is used when trying to find the record.
+        # * <tt>id:</tt> The id of the session, this gets merged with the real id. For information ids see the id method.
+        #
+        # Here is how you use it:
+        #
+        #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
+        #     UserSession.find
+        #   end
+        #
+        # Eseentially what the above does is scope the searching of the object with the sql you provided. So instead of:
+        #
+        #   User.find(:first, :conditions => "login = 'ben'")
+        #
+        # it would be:
+        #
+        #   User.find(:first, :conditions => "login = 'ben' and account_id = 2")
+        #
+        # You will also notice the :id option. This works just like the id method. It scopes your cookies. So the name of your cookie will be:
+        #
+        #   account_2_user_credentials
+        #
+        # instead of:
+        #
+        #   user_credentials
+        #
+        # What is also nifty about scoping with an :id is that it merges your id's. So if you do:
+        #
+        #   UserSession.with_scope(:find_options => {:conditions => "account_id = 2"}, :id => "account_2") do
+        #     session = UserSession.new
+        #     session.id = :secure
+        #   end
+        #
+        # The name of your cookies will be:
+        #
+        #   secure_account_2_user_credentials
+        def with_scope(options = {}, &block)
+          raise ArgumentError.new("You must provide a block") unless block_given?
+          self.scope = options
+          result = yield
+          self.scope = nil
+          result
+        end
+        
+        private
+          def scope=(value)
+            Thread.current[:authlogic_scope] = value
+          end
+      end
+      
+      module InstanceMethods
+        # Setting the scope if it exists upon instantiation.
+        def initialize(*args)
+          self.scope = self.class.scope
+          super
+        end
+        
+        # The scope of the current object
+        def scope
+          @scope ||= {}
+        end
+        
+        private
+          # Used for things like cookie_key, session_key, etc.
+          def build_key(last_part)
+            [scope[:id], super].compact.join("_")
+          end
+          
+          def search_for_record(*args)
+            klass.send(:with_scope, :find => (scope[:find_options] || {})) do
+              klass.send(*args)
+            end
+          end
+      end
+    end
+  end
+end