expertiza-authlogic 2.1.6.1

data/CHANGELOG.rdoc

@@ -0,0 +1,345 @@
+== 2.1.2
+
+* Return the newly create object for the class level create method, instead of a boolean
+* Add a model_name class method for Authlogic::Session for rails 3 compatibility. Will be using ActiveModel eventually, but this should be a quick fix.
+
+== 2.1.1 released 2009-7-04
+
+* Use mb_chars when downcasing the login string to support international characters.
+* Check for the existence of the :remember_me key before setting remember_me off of a hash.
+* Added check to make sure Authlogic is not loaded too late, causing a NotActivated error.
+
+== 2.1.0 released 2009-6-27
+
+* Fixed bug when using act_like_restful_authentication and setting passwords, needed to add a 2nd parameter to tell if to check against the database or not.
+* Don't save record if they are read only.
+
+== 2.0.14 released 2009-6-13
+
+* Fixed issue with using brute force protection AND generalize_credentials_error_messages. Brute force protection was looking to see if there were password errors, which generalize_credentials_error_messages was obfuscating.
+* Added db_setup? method to avoid errors during rake tasks where the db might not be set up. Ex: migrations
+* Stop using errors.on(key) since that is now deprecated in Rails. Use errors[key] instead.
+* Use valid_password? for the method name to validate a password instead of valid_#{password_field}?.
+
+== 2.0.13 released 2009-5-13
+
+* Add authlogic/regex.rb to manifest
+
+== 2.0.12 released 2009-5-13
+
+* Added the ability to add a last_request_update_allowed? method in your controller to pragmatically tell Authlogic when and when not to update the last_request_at field in your database. This only takes effect if the method if present.
+* Extracted Authlogic's regular expressions into it's own module to allow easy use of them outside of Authlogic. See Authlogic::Regex for more info.
+* Made being_brute_force_protected? true for the Authlogic::Session::BruteForceProtection module.
+* Added the configuration option generalize_credentials_error_messages for the Authlogic::Session::Password module. This allows you to generalize your login / password errors messages as to not reveal was the problem was when authenticating. If enabled, when an invalid login is supplied it will use the same exact error message when an invalid password is supplied.
+* Update email regular expression to use A-Z0-9 instead of /w as to not allow for diacritical marks in an email address.
+* Changed config() convenience method to rw_config() to be more descriptive and less vague.
+
+== 2.0.11 released 2009-4-25
+
+* Fix bug when password is turned off and the SingleAccessToken module calls the after_password_set callback.
+* HTTP basic auth can now be toggled on or off. It also checks for the existence of a standard username and password before enabling itself.
+* Added option check_passwords_against_database for Authlogic::ActsAsAuthentic::Password to toggle between checking the password against the database value or the object value. Also added the same functionality to the instance method: valid_password?("password", true), where the second argument tells Authlogic to check the password against the database value. The default for this new feature is true.
+* Add a maintain_sessions configuration option to Authlogic::ActsAsAuthentic::SessionMaintenance as a "clearer" option to disable automatic session maintenance.
+* single_access_allowed_request_types can also be equal to :all instead of just [:all].
+* Refactor params_enabled? so that the single_access_allowed? method in controllers takes precedence.
+* Added testing comments in the README and expanded on the documentation in Authlogic::TestCase
+
+== 2.0.10 released 2009-4-21
+
+* Mock request is now transparent to non existent methods. Since the methods calls really have no functional value when testing authlogic.
+* Allow password confirmation to be disabled.
+* Modified login format validation to allow for the + character since emails addresses allow that as a valid character.
+* Added merge_* configuration methods for acts_as_authentic to make merging options into configuration options that default to hashes. Just a few convenience methods.
+
+== 2.0.9 released 2009-4-9
+
+* Fixed bug where hooks provided by the password module were called when the password module was not being used due to the fact that the password field did not exist.
+* Fixed bug where the find_with_login method was not being aliased if you were using an alternate field besides login.
+
+== 2.0.8 release 2009-4-9
+
+* Dont reset the @password_changed instance variable to false because its halts the callback chain, instead reset it to nil.
+
+== 2.0.7 released 2009-4-9
+
+* Rename TestCase::ControllerAdapter to TestCase::RailsRequestAdapter to help clarify it's usage and fix a constant typo.
+
+== 2.0.6 released 2009-4-9
+
+* Don't use second, use [1] instead so older rails versions don't complain.
+* Update email regular expression to be less TLD specific: (?:[A-Z]{2,4}|museum|travel)
+* Update shoulda macro for 2.0
+* validates_length_of_password_confirmation_field_options defaults to validates_confirmation_of_password_field_options
+* Use MockCookieJar in tests instead of a Hash in the MockController.
+* Cookies now store the record id as well, for faster lookup. Also to avoid the need to use sessions since sessions are lazily loaded in rails 2.3+
+* Add configuration option for Authlogic::ActsAsAuthentic: ignore_blank_passwords
+* Fix cookie_domain in rails adapter
+* Make password and login fields optional. This allows you to have an alternate authentication method as your main authentication source. Such as OpenID, LDAP, or whatever you want.
+* Reset the @password_changed instance variable after the record has been saved.
+* Add referer and user_agent to mock requests for testing purposes.
+* Add :case_sensitive => false to validates_uniqueness_of calls on the login and email fields.
+* MockRequest not tries to use controller.env['REMOTE_ADDR'] for the IP address in tests.
+* Add in custom find_with_email and find_with_login methods to perform case insensitive searches for databases that are case sensitive by default. This is only done if the :case_insensitive option for validates_uniqueness_of_login_field_options or validates_uniqueness_of_email_field_options is set to false. Which, as of this version, it is. If you are using MySQL this has been the default behavior all along. If you are using SQLite or Postgres this has NOT been the default behavior.
+* Added in exception explaining that you are using the old configuration for acts_as_authentic with an example of the new format.
+
+== 2.0.5 released 2009-3-30
+
+* Stub out authenticate_with_http_basic for TestCase::ControllerAdapter.
+* Added second parameter for add_acts_as_authentic module to specify the position: append or prepend.
+
+== 2.0.4 released 2009-3-28
+
+* Added validates_uniqueness_of_login_field_options and validates_uniqueness_of_email_field_options configuration options
+* Add in checks to make sure session_class is not nil.
+* Cleaned up TestCase some more and added functionality to log users in during functional tests.
+
+== 2.0.3 released 2009-3-26
+
+* Fixed error where default session class does not exist.
+* Fixed human_name for the model to use its own human name and not delegate to the associated model. Translation should be under authlogic.models.user_session (or whatever the name of your session is).
+* Fixed human_attribute_name to use Authlogic keys for translation instead of ActiveRecord: authlogic.attributes.user_session.login
+* For transitioning from restful_authentication, set the REST_AUTH_SITE_KEY to '' if it doesn't exist, instead of nil.
+* Completely rewrote Authlogic::Testing, it's now called Authlogic::TestCase. Testing Authlogic is much easier now. Please see Authlogic::TestCase for more info.
+
+== 2.0.2 released 2009-3-24
+
+* Reset failed_login_count if consecutive_failed_logins_limit has been exceed and the failed_login_ban_for has passed.
+* Update test helpers to use the new configuration scheme.
+* Fixed issue when logging doesn't update last_request_at, so the next persistence try would fail.
+
+== 2.0.1 released 2009-3-23
+
+* Validate length of password.
+* Dont save sessions with a ! during session maintenance.
+* Add self_and_descendants_from_active_record for Rails 2.3
+* Abort acts_as_authentic if there is no DB connection or table.
+
+== 2.0.0 released 2009-3-23
+
+* Refactored nearly all code and tests, especially acts_as_authentic. Got rid of the meta programming and rewrote to use modules and hooks. Also moved all configuration into their related modules.
+* Set up a strong API with hooks to allow you to modify behavior and most importantly, easily create "add on" modules or alternate authentication methods, etc.
+* Changed configuration method for acts_as_authentic to accept a block instead of a hash.
+* The record attribute will NEVER be set until after validation passes, similar to how ActiveRecord executes UPDATEs and CREATEs.
+* Fixed bug with session maintenance where user would log in as new user when creating another user account, typically an admin function.
+* Brute force protection is only a temporary ban by default, not a permanent one.
+* Switched to Hoe for gem management instead of Echoe.
+* Added MD5 crypto provider for legacy systems.
+* Make password salt field optional for legacy systems.
+
+== 1.4.4 released 2009-3-2
+
+* Moved session maintenance to a before_save, to save on queries executed and to skip an unexpected / additional save on the user object.
+* Extracted random string generation into its own class and leverages SecureRandom if it is available
+* Move cookies to a higher priority when trying to find the record to help with performance since Rails 3 lazily loads the sessions
+* Reset perishable token in a before_save instead of a before_validation
+
+== 1.4.3 released 2009-2-22
+
+* Fixed issue with brute force protection.
+
+== 1.4.2 released 2009-2-20
+
+* Cleaned up callbacks system to use hooks and execute in the proper order.
+* Added brute force protection. See the consecutive_failed_logins_limit configuration option in Authlogic::Session::Config. Also see Authlogic::Session:BruteForceProtection
+* Fixed issue with calling stale? when there is no record.
+* Simon Harris fixed the issue of using lock_version with the associated record and also optimized the library for better performance.
+* Implemented saving the record during the callback chain to execute as few queries as possible. This way modules can hook into Authlogic, modify the associated record, and not have to worry about saving the record.
+
+== 1.4.1 released 2009-2-8
+
+* Fixed I18n key misspelling.
+* Added I18n keys for ORM error messages.
+* Use the password_field configuration value for the alias_methods defined in acts_as_authentic/credentials.rb
+* Change shoulda macros implementation to follow the shoulda documentation
+* Rails >2.3 uses :domain for the session option instead of :session_domain. Authlogic now uses the proper key in the rails adapter.
+* Added validate_password attribute to force password validation regardless if the password is blank. This is useful for forms explicitly changing passwords.
+* The class level find method will return a session object if the session is stale. The protection is that there will be no record associated with that session. This allows you to receive an object and call the stale? method on it to determine why the user must log back in.
+* Added validate callbacks in Session::Base so you can run callbacks by calling validate :my_method, just like in AR.
+* Checked for blank persistence tokens when trying to validate passwords, this is where transitioning occurs. People transitioning from older systems never had a persistence token, which means it would be nil here.
+* Update allowed domain name extensions for email
+* Ignore default length options for validations if alternate length options are provided, since AR raises an error if 2 different length specifications are provided.
+
+== 1.4.0 released 2009-1-28
+
+* Added support for cookie domain, based on your frameworks session domain configuration
+* Updated test helper functions to use the persistence token config value
+* Check for UTC times when using Time.now for current_login_at and last_request_at
+* Single access now looks for a single_access_allowed? method in your controllers to determine if single access should be allowed or not. Allowing you to define exactly when single access is allowed.
+* Finding the authenticated record uses klass.primary_key instead of assuming id.
+* BREAKS BACKWARDS COMPATIBILITY: New I18n solution implemented. See Authlogic::I18n for more information.
+
+== 1.3.9 released 2009-1-9
+
+* Added the disable_perishable_token_maintenance option to disable the automatic resetting of the perishable_token, meaning you will have to maintain this yourself.
+* Changed shoulda macro to conform to standards so model is not required to be passed
+* Modified method definitions for the Session class to check for already defined methods, allowing you to write your own "credential" methods, and Authlogic will not overwrite your custom methods.
+* Fixed bug when passing :all to single_access_allowed_request_types
+* Added logout_on_timeout configuration option for Session::Base
+
+== 1.3.8 released 2008-12-24
+
+* Only change persistence token if the password is not blank
+* Normalize the last_request_at_threshold so that you can pass an integer or a date/time range.
+* Fixed bug where password length validations were not being run because the password value was not blank. It should be run if it is a new record, the password has changed, or the password is blank.
+* Added disable_magic_states option for sessions, to turn off the automatic checking of "magic states" such as active?, confirmed?, and approved?.
+
+== 1.3.7 released 2008-11-30
+
+* Added session generator: script/generate session UserSession
+* Added Test::Unit helpers file, see testing in the README
+
+== 1.3.6 released 2008-11-30
+
+* Modified validates_length_of for password so that there is a fallback validation if the passed "if statement" fails
+
+== 1.3.5 released 2008-11-30
+
+* :transition_from_crypto_provider for acts_as_authentic now accepts an array to transition from multiple providers. Which solves the problem of a double transition.
+* Added AES256 as a crypto_provider option, for those that want to use a reversible encryption method by supplying a key.
+* Fixed typo for using validates_format_of_options instead of validates_length_of_options
+* Fixed bug when accessing the dynamic method for accessing the session record in a namespace, since it uses class_name.underscore which replaces :: with a /
+* Added minimum length requirement of 4 for the password, and removed validates_presence_of for password since validates_length_of enforces this
+* Set before_validation to reset the persistence token if it is blank, since a password is not required for open id authentication
+
+== 1.3.4 released 2008-11-24
+
+* Delegate human_attribute_name to the ActiveRecord class to take advantage of the I18n feature.
+* Fixed issue with passwords from older versions of restful_authentication, the passwords end with --
+
+== 1.3.3 released 2008-11-23
+
+* Updated :act_like_restful_authentication for those using the older version where no site wide key is preset (REST_AUTH_SITE_KEY), Authlogic will adjust automatically based on the presence of this constant.
+* Added :transition_from_crypto_provider option for acts_as_authentic to transition your user's passwords to a new algorithm.
+* Added :transition_from_restful_authentication for acts_as_authentic to transition your users from restful_authentication to the Authlogic password system. Now you can choose to keep your passwords the same by using :act_like_restful_authentication, which will *NOT* do any transitioning, or you can use :transition_from_crypto_provider which will update your users passwords as they login or new accounts are created, while still allowing users with the old password system to log in.
+* Modified the "interface" for the crypto providers to only provide a class level encrypt and matches? method, instead of a class level encrypt and decrypt method.
+
+== 1.3.2 released 2008-11-22
+
+* Updated code to work better with BCrypt, using root level class now.
+
+== 1.3.1 released 2008-11-22
+
+* Fixed typo in acts_as_authentic config when passing the :scope option.
+* Added :act_like_restful_authentication option for acts_as_authentic
+* Added a new crypto provider: BCrypt, this is for those storing the nuclear launch codes in their apps
+
+== 1.3.0 released 2008-11-21
+
+* BREAKS BACKWARDS COMPATIBILITY: changed the confirm_password field to password_confirmation for acts_as_authentic, since the rails validates_confirmation_of handles creating this attribute and there is no option to change the name of this.
+* BREAKS BACKWARDS COMPATIBILITY: Cleaned up all of the validation configuration for acts_as_authentic, as well as the documentation that goes with it, you can accomplish the same things as before, but this is much more flexible and much more organized. This is mainly for those implementing i18n support. Instead of :whatever_message, its now :login_field_validates_length_of_options => {:message => "your i18n friendly message"}. As a side note, with the new i18n support in rails I would not be surprised if this is already done for you since Authlogic uses the ActiveRecord validation methods.
+* Got rid of simple delegator for the abstract controller, apparently this has performance issues.
+* Cleaned up validations to assume ActiveRecord dirty attributes are present, I think this is a safe assumption.
+
+== 1.2.2 released 2008-11-20
+
+* Added allow_blank_login_and_password_field and allow_blank_email_field options to acts_as_authentic, which allows you to have alternative logins, such as OpenID
+* In the session Authlogic now also stores the record id. We use this id to find the record and then check the token against the record, thus allowing for quicker database lookups, while getting the same security.
+* Skip validation for reset_perishable_token!
+* Added checks for uniqueness validations to only perform if the values have changed, this cuts down on DB queries
+* Abstract controller adapter now uses ruby's simple delegator class
+* Allow to save with a block: user_session.save { |result| }, result will either be false or self, this is useful when implementing OpenID and other methods
+
+== 1.2.1 released 2008-11-19
+
+* Added build method to authenticates_many association to act like AR association collections.
+* Added validation boolean configuration options for acts_as_authentic: validate_field, validate_login_field, validate_password_field, validate_email_field. This turns on and off validations for their respective fields.
+* Renamed all password_reset_token terms to perishable_token, including configuration, etc. I still allow for the old configurations so this will not break compatibility, but perishable token is a better name and can be used for account confirmation as well as a password reset token, or anything else you want.
+* Renamed all remember_token instances to persistence_token, the term "remember token" doesn't really make sense. I still allow for the old configuration, so this will not break backwards compatibility: persistence_token fits better and makes more sense.
+
+== 1.2.0 released 2008-11-16
+
+* Added check for database set up in acts_as_authentic to prevent errors during migrations.
+* Forced logged_in and logged_out named scopes to use seconds.
+* Hardened valid_password? method to only allow raw passwords.
+* controllers and scopes are no longer stored in class variables but in the Thread.current hash so their instances die out with the thread, which frees up memory.
+* Removed single_access_token_field and remember_token_field from Sesson::Config, they are not needed there.
+* Added password_reset_token to assist in resetting passwords.
+* Added email_field, email_field_regex, email_field_regex_failed_message configuration options to acts_as_authentic. So that you can validate emails as well as a login, instead of the either-or approach.
+* Added configuration for all validation messages for the session so that you can modify them and provide I18n support.
+
+== 1.1.1 released 2008-11-13
+
+* Removed ActiveRecord dependency.
+* Removed loading shoulda macros by default, moved to shoulda_macros dir.
+* Modified how params access works. Added in single_access_token_field which params now uses. See the single access section in the README. Various configuration options added as well.
+* Cleaned up acts_as_authentic configuration, added new config module to do this.
+* Cleaned up acts_as_authentic tests
+* Moved acts_as_authentic sub modules into the proper name spaces
+
+== 1.1.0 released 2008-11-13
+
+* Moved Rack standards into abstract_adapter for the controllers.
+* Added authenticating_with_credentials?, authenticating_with_unauthorized_record?
+* Fixed typo in abstract_adapter, black to block.
+* Cleaned up / reorganized tests.
+* Moved ActiveRecord additions to ORM Adapters name space to make way for Data Mapper.
+* Reorganized and modified acts_as_authentic to be free standing and not get info from the related session.
+* The session now gets its configuration from the model, since determining which fields are present is ORM specific.
+* Extracted session and cookie logic into their own modules for Session.
+* Moved crypto providers into their own module and added a Sha1 provider to help with the restful_authentication transition.
+* Allow the unique_token method to use the alternate crypto_provider if it is a hash algorithm, otherwise default to Sha512.
+* Added last_request_at_threshold configuration option.
+* Changed Scoped class to AuthenticatesManyAssociation, like AR has HasManyAssociation, etc.
+* Added should_be_authentic shoulda macro.
+* Removed some magic from how sessions are initialized. See the initialize documentation, this method is a little more structured now, which was required for adding in openid.
+* Added in logging via a params token, which is friendly for feed URLs. Works just like cookies and sessions when persisting the session.
+* Added the option to use session.user, instead of session.record. This is based off of what model your session is authenticating with.
+
+== 1.0.0 released 2008-11-05
+
+* Checked for blank login counts, if a default wasnt set in the migrations.
+* Added check for database table in acts_as_authentic to avoid errors in initial setup.
+* Completely rewrote tests to be more conventional and thorough tests, removed test_app.
+* Modified how validations work so that a validate method was added as well as callbacks for that method.
+* Extracted scope support into its own module to help organize code better.
+* Added in salt for encryption, just like hashes and removed :crypto_provider_type option for acts_as_authentic.
+* Added merb adapters.
+* Improved documentation throughout.
+
+== 0.10.4 released 2008-10-31
+
+* Changed configuration to use inheritable attributes
+* Cleaned up requires to be in their proper files
+* Added in scope support.
+
+== 0.10.3 released 2008-10-31
+
+* Instead of raising an error when extra fields are passed in credentials=, just ignore them.
+* Added remember_me config option to set the default value.
+* Only call credential methods if an argument was passed.
+* More unit tests
+* Hardened automatic session updating. Also automatically log the user in if they change their password when logged out.
+
+== 0.10.2 released 2008-10-24
+
+* Added in stretches to the default Sha512 encryption algorithm.
+* Use column_names instead of columns when determining if a column is present.
+* Improved validation callbacks. after_validation should only be run if valid? = true. Also clear errors before the "before_validation" callback.
+
+== 0.10.1 released 2008-10-24
+
+* Sessions now store the "remember token" instead of the id. This is much safer and guarantees all "sessions" that are logged in are logged in with a valid password. This way stale sessions can't be persisted.
+* Bumped security to Sha512 from Sha256.
+* Remove attr_protected call in acts_as_authentic
+* protected_password should use pasword_field configuration value
+* changed magic state "inactive" to "active"
+
+== 0.10.0 released 2008-10-24
+
+* Do not allow instantiation if the session has not been activated with a controller object. Just like ActiveRecord won't let you do anything without a DB connection.
+* Abstracted controller implementation to allow for rails, merb, etc adapters. So this is not confined to the rails framework.
+* Removed create and update methods and added save, like ActiveRecord.
+* after_validation should be able to change the result if it adds errors on callbacks.
+* Completed tests.
+
+== 0.9.1 released 2008-10-24
+
+* Changed scope to id. Makes more sense to call it an id and fits better with the ActiveRecord model.
+* Removed saving_from_session flag, apparently it is not needed.
+* Fixed updating sessions to make more sense and be stricter.
+* change last_click_at to last_request_at
+* Only run "after" callbacks if the result is successful.
+
+== 0.9.0 released 2008-10-24
+
+* Initial release.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Ben Johnson of Binary Logic
+
+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.rdoc

@@ -0,0 +1,246 @@
+= Authlogic
+
+Authlogic is a clean, simple, and unobtrusive ruby authentication solution.
+
+A code example can replace a thousand words...
+
+Authlogic introduces a new type of model. You can have as many as you want, and name them whatever you want, just like your other models. In this example, we want to authenticate with the User model, which is inferred by the name:
+
+  class UserSession < Authlogic::Session::Base
+    # specify configuration here, such as:
+    # logout_on_timeout true
+    # ...many more options in the documentation
+  end
+
+Log in with any of the following. Create a UserSessionsController and use it just like your other models:
+
+  UserSession.create(:login => "bjohnson", :password => "my password", :remember_me => true)
+  session = UserSession.new(:login => "bjohnson", :password => "my password", :remember_me => true); session.save
+  UserSession.create(:openid_identifier => "identifier", :remember_me => true) # requires the authlogic-oid "add on" gem
+  UserSession.create(my_user_object, true) # skip authentication and log the user in directly, the true means "remember me"
+
+The above handles the entire authentication process for you. It first authenticates, then it sets up the proper session values and cookies to persist the session. Just like you would if you rolled your own authentication solution.
+
+You can also log out / destroy the session:
+
+  session.destroy
+
+After a session has been created, you can persist it across requests. Thus keeping the user logged in:
+
+  session = UserSession.find
+
+To get all of the nice authentication functionality in your model just do this:
+
+  class User < ActiveRecord::Base
+    acts_as_authentic do |c|
+      c.my_config_option = my_value
+    end # the configuration block is optional
+  end
+
+This handles validations, etc. It is also "smart" in the sense that it if a login field is present it will use that to authenticate, if not it will look for an email field, etc. This is all configurable, but for 99% of cases that above is all you will need to do.
+
+Also, sessions are automatically maintained. You can switch this on and off with configuration, but the following will automatically log a user in after a successful registration:
+
+  User.create(params[:user])
+
+This also updates the session when the user changes his/her password.
+
+Authlogic is very flexible, it has a strong public API and a plethora of hooks to allow you to modify behavior and extend it. Check out the helpful links below to dig deeper.
+
+== Helpful links
+
+* <b>Documentation:</b> http://rdoc.info/projects/binarylogic/authlogic
+* <b>Repository:</b> http://github.com/binarylogic/authlogic/tree/master
+* <b>Railscasts Screencast:</b> http://railscasts.com/episodes/160-authlogic
+* <b>Live example with OpenID "add on":</b> http://authlogicexample.binarylogic.com
+* <b>Live example repository with tutorial in README:</b> http://github.com/binarylogic/authlogic_example/tree/master
+* <b>Tutorial: Reset passwords with Authlogic the RESTful way:</b> http://www.binarylogic.com/2008/11/16/tutorial-reset-passwords-with-authlogic
+* <b>Issues:</b> http://github.com/binarylogic/authlogic/issues
+* <b>Google group:</b> http://groups.google.com/group/authlogic
+
+<b>Before contacting me directly, please read:</b>
+
+If you find a bug or a problem please post it in the issues section. If you need help with something, please use google groups. I check both regularly and get emails when anything happens, so that is the best place to get help. This also benefits other people in the future with the same questions / problems. Thank you.
+
+== Authlogic "add ons"
+
+* <b>Authlogic OpenID addon:</b> http://github.com/binarylogic/authlogic_openid
+* <b>Authlogic LDAP addon:</b> http://github.com/binarylogic/authlogic_ldap
+* <b>Authlogic Facebook Connect:</b> http://github.com/kalasjocke/authlogic_facebook_connect
+* <b>Authlogic OAuth (Twitter):</b> http://github.com/jrallison/authlogic_oauth
+* <b>Authlogic PAM:</b> http://github.com/nbudin/authlogic_pam
+
+If you create one of your own, please let me know about it so I can add it to this list. Or just fork the project, add your link, and send me a pull request.
+
+== Session bugs (please read if you are having issues with logging in / out)
+
+Apparently there is a bug with apache / passenger for v2.1.X with sessions not working properly. This is most likely your problem if you are having trouble logging in / out. This is *not* an Authlogic issue. This can be solved by updating passener or using an alternative session store solution, such as active record store.
+
+== Documentation explanation
+
+You can find anything you want about Authlogic in the {documentation}[http://rdoc.info/projects/binarylogic/authlogic], all that you need to do is understand the basic design behind it.
+
+That being said, there are 2 models involved during authentication. Your Authlogic model and your ActiveRecord model:
+
+1. <b>Authlogic::Session</b>, your session models that extend Authlogic::Session::Base.
+2. <b>Authlogic::ActsAsAuthentic</b>, which adds in functionality to your ActiveRecord model when you call acts_as_authentic.
+
+Each of the above has its various sub modules that contain common logic. The sub modules are responsible for including *everything* related to it: configuration, class methods, instance methods, etc.
+
+For example, if you want to timeout users after a certain period of inactivity, you would look in <b>Authlogic::Session::Timeout</b>. To help you out, I listed the following publicly relevant modules with short descriptions. For the sake of brevity, there are more modules than listed here, the ones not listed are more for internal use, but you can easily read up on them in the {documentation}[http://rdoc.info/projects/binarylogic/authlogic].
+
+=== Authlogic::ActsAsAuthentic sub modules
+
+These modules are for the ActiveRecord side of things, the models that call acts_as_authentic.
+
+* <b>Authlogic::ActsAsAuthentic::Base</b> - Provides the acts_as_authentic class method and includes all of the submodules.
+* <b>Authlogic::ActsAsAuthentic::Email</b> - Handles everything related to the email field.
+* <b>Authlogic::ActsAsAuthentic::LoggedInStatus</b> - Provides handy named scopes and methods for determining if the user is logged in or out.
+* <b>Authlogic::ActsAsAuthentic::Login</b> - Handles everything related to the login field.
+* <b>Authlogic::ActsAsAuthentic::MagicColumns</b> - Handles everything related to the "magic" fields: login_count, failed_login_count, last_request_at, etc.
+* <b>Authlogic::ActsAsAuthentic::Password</b> - This one is important. It handles encrypting your password, salting it, etc. It also has support for transitioning password algorithms.
+* <b>Authlogic::ActsAsAuthentic::PerishableToken</b> - Handles maintaining the perishable token field, also provides a class level method for finding record using the token.
+* <b>Authlogic::ActsAsAuthentic::PersistenceToken</b> - Handles maintaining the persistence token. This is the token stored in cookies and sessions to persist the users session.
+* <b>Authlogic::ActsAsAuthentic::RestfulAuthentication</b> - Provides configuration options to easily migrate from the restful_authentication plugin.
+* <b>Authlogic::ActsAsAuthentic::SessionMaintenance</b> - Handles automatic session maintenance. EX: a new user registers, automatically log them in. Or a user changes their password, update their session.
+* <b>Authlogic::ActsAsAuthentic::SingleAccessToken</b> - Handles maintaining the single access token.
+* <b>Authlogic::ActsAsAuthentic::ValidationsScope</b> - Allows you to scope all validations, etc. Just like the :scope option for validates_uniqueness_of
+
+=== Authlogic::Session sub modules
+
+These modules are for the models that extend Authlogic::Session::Base.
+
+* <b>Authlogic::Session::BruteForceProtection</b> - Disables accounts after a certain number of consecutive failed logins attempted.
+* <b>Authlogic::Session::Callbacks</b> - Your tools to extend, change, or add onto Authlogic. Lets you hook in and do just about anything you want. Start here if you want to write a plugin or add-on for Authlogic
+* <b>Authlogic::Session::Cookies</b> - Authentication via cookies.
+* <b>Authlogic::Session::Existence</b> - Creating, saving, and destroying objects.
+* <b>Authlogic::Session::HttpAuth</b> - Authentication via basic HTTP authentication.
+* <b>Authlogic::Session::Id</b> - Allows sessions to be separated by an id, letting you have multiple sessions for a single user.
+* <b>Authlogic::Session::MagicColumns</b> - Maintains "magic" database columns, similar to created_at and updated_at for ActiveRecord.
+* <b>Authlogic::Session::MagicStates</b> - Automatically validates based on the records states: active?, approved?, and confirmed?. If those methods exist for the record.
+* <b>Authlogic::Session::Params</b> - Authentication via params, aka single access token.
+* <b>Authlogic::Session::Password</b> - Authentication via a traditional username and password.
+* <b>Authlogic::Session::Persistence</b> - Persisting sessions / finding sessions.
+* <b>Authlogic::Session::Session</b> - Authentication via the session, the controller session that is.
+* <b>Authlogic::Session::Timeout</b> - Automatically logging out after a certain period of inactivity.
+* <b>Authlogic::Session::UnauthorizedRecord</b> - Handles authentication by passing an ActiveRecord object directly.
+* <b>Authlogic::Session::Validation</b> - Validation / errors.
+
+=== Miscellaneous modules
+
+Miscellaneous modules that shared across the authentication process and are more "utility" modules and classes.
+
+* <b>Authlogic::AuthenticatesMany</b> - Responsible for allowing you to scope sessions to a parent record. Similar to a has_many and belongs_to relationship. This lets you do the same thing with sessions.
+* <b>Authlogic::CryptoProviders</b> - Contains various encryption algorithms that Authlogic uses, allowing you to choose your encryption method.
+* <b>Authlogic::I18n</b> - Acts JUST LIKE the rails I18n library, and provides internationalization to Authlogic.
+* <b>Authlogic::Random</b> - A simple class to generate random tokens.
+* <b>Authlogic::Regex</b> - Contains regular expressions used in Authlogic. Such as those to validate the format of the log or email.
+* <b>Authlogic::TestCase</b> - Various helper methods for testing frameworks to help you test your code.
+* <b>Authlogic::Version</b> - A handy class for determine the version of Authlogic in a number of ways.
+
+== Quick Rails example
+
+What if creating sessions worked like an ORM library on the surface...
+
+  UserSession.create(params[:user_session])
+
+What if your user sessions controller could look just like your other controllers...
+
+  class UserSessionsController < ApplicationController
+    def new
+      @user_session = UserSession.new
+    end
+    
+    def create
+      @user_session = UserSession.new(params[:user_session])
+      if @user_session.save
+        redirect_to account_url
+      else
+        render :action => :new
+      end
+    end
+    
+    def destroy
+      current_user_session.destroy
+      redirect_to new_user_session_url
+    end
+  end
+
+As you can see, this fits nicely into the RESTful development pattern. What about the view...
+
+  <% form_for @user_session do |f| %>
+    <%= f.error_messages %>
+    <%= f.label :login %><br />
+    <%= f.text_field :login %><br />
+    <br />
+    <%= f.label :password %><br />
+    <%= f.password_field :password %><br />
+    <br />
+    <%= f.submit "Login" %>
+  <% end %>
+
+Or how about persisting the session...
+
+  class ApplicationController
+    helper_method :current_user_session, :current_user
+    
+    private
+      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
+  end
+
+== Install & Use
+
+Install the gem / plugin (recommended)
+
+From rubyforge:
+
+  $ sudo gem install authlogic
+
+Or from github:
+
+  $ sudo gem install binarylogic-authlogic
+
+Now just add the gem dependency in your projects configuration.
+
+Or you can install this as a plugin:
+
+  script/plugin install git://github.com/binarylogic/authlogic.git
+
+== Detailed Setup Tutorial
+
+See the {authlogic example}[http://github.com/binarylogic/authlogic_example/tree/master] for a detailed setup tutorial. I did this because not only do you have a tutorial to go by, but you have an example app that uses the same tutorial, so you can play around with with the code. If you have problems you can compare the code to see what you are doing differently.
+
+== Testing
+
+I think one of the best aspects of Authlogic is testing. For one, it cuts out <b>a lot</b> of redundant tests in your applications because Authlogic is already thoroughly tested for you. It doesn't include a bunch of tests into your application, because it comes tested, just like any other library.
+
+For example, think about ActiveRecord. You don't test the internals of ActiveRecord, because the creators of ActiveRecord have already tested the internals for you. It wouldn't make sense for ActiveRecord to copy it's hundreds of tests into your applications. The same concept applies to Authlogic. You only need to test code you write that is specific to your application, just like everything else in your application.
+
+That being said, testing your code that uses Authlogic is easy. Since everyone uses different testing suites, I created a helpful module called Authlogic::TestCase, which is basically a set of tools for testing code using Authlogic. I explain testing Authlogic thoroughly in the {Authlogic::TestCase section of the documentation}[http://rdoc.info/rdoc/binarylogic/authlogic/blob/f2f6988d3b97e11770b00b72a7a9733df69ffa5b/Authlogic/TestCase.html]. It should answer any questions you have in regards to testing Authlogic.
+
+== Tell me quickly how Authlogic works
+
+Interested in how all of this all works? Think about an ActiveRecord model. A database connection must be established before you can use it. In the case of Authlogic, a controller connection must be established before you can use it. It uses that controller connection to modify cookies, the current session, login with HTTP basic, etc. It connects to the controller through a before filter that is automatically set in your controller which lets Authlogic know about the current controller object. Then Authlogic leverages that to do everything, it's a pretty simple design. Nothing crazy going on, Authlogic is just leveraging the tools your framework provides in the controller object.
+
+== What sets Authlogic apart and why I created it
+
+What inspired me to create Authlogic was the messiness of the current authentication solutions. Put simply, they just didn't feel right, because the logic was not organized properly. As you may know, a common misconception with the MVC design pattern is that the model "M" is only for data access logic, which is wrong. A model is a place for domain logic. This is why the RESTful design pattern and the current authentication solutions don't play nice. Authlogic solves this by placing the session maintenance logic into its own domain (aka "model"). Moving session maintenance into its own domain has its benefits:
+
+1. <b>It's cleaner.</b> There are no generators in Authlogic. Authlogic provides a class that you can use, it's plain and simple ruby. More importantly, the code in your app is code you write, written the way you want, nice and clean. It's code that should be in your app and is specific to your app, not a redundant authentication pattern.
+2. <b>Easier to stay up-to-date.</b> To make my point, take a look at the commits to any other authentication solution, then look at the {commits for authlogic}[http://github.com/binarylogic/authlogic/commits/master]. How many commits could you easily start using if you already had an app using that solution? With an alternate solution, very few, if any. All of those cool new features and bug fixes are going to have be manually added or wait for your next application. Which is the main reason a generator is not suitable as an authentication solution. With Authlogic you can start using the latest code with a simple update of a gem. No generators, no mess.
+3. <b>It ties everything together on the domain level.</b> Take a new user registration for example, no reason to manually log the user in, authlogic handles this for you via callbacks. The same applies to a user changing their password. Authlogic handles maintaining the session for you.
+4. <b>No redundant tests.</b> Because Authlogic doesn't use generators, #1 also applies to tests. Authlogic is *thoroughly* tested for you. You don't go and test the internals of ActiveRecord in each of your apps do you? So why do the same for Authlogic? Your application tests should be for application specific code. Get rid of the noise and make your tests focused and concise, no reason to copy tests from app to app.
+5. <b>Framework agnostic</b>. Authlogic can be used in *any* ruby framework you want: Rails, Merb, Sinatra, Mack, your own framework, whatever. It's not tied down to Rails. It does this by abstracting itself from these framework's controllers by using a controller adapter. Thanks to {Rack}[http://rack.rubyforge.org/], there is a defined standard for controller structure, and that's what Authlogic's abstract adapter follows. So if your controller follows the rack standards, you don't need to do anything. Any place it deviates from this is solved by a simple adapter for your framework that closes these gaps. For an example, checkout the Authlogic::ControllerAdapters::MerbAdapter.
+5. <b>You are not restricted to a single session.</b> Think about Apple's me.com, where they need you to authenticate a second time before changing your billing information. Why not just create a second session for this? It works just like your initial session. Then your billing controller can require an "ultra secure" session.
+6. <b>Easily extendable.</b> One of the distinct advantages of using a library is the ability to use its API, assuming it has one. Authlogic has an *excellent* public API, meaning it can easily be extended and grow beyond the core library. Checkout the "add ons" list above to see what I mean.
+
+
+Copyright (c) 2009 {Ben Johnson of Binary Logic}[http://www.binarylogic.com], released under the MIT license