Released 1.2.1

CHANGELOG.rdoc

@@ -1,7 +1,9 @@
-== 1.2.1 released 2008-11-16
+== 1.2.1 released 2008-11-19
 
-* Added build method to authenticates_many association.
-* Added validation boolean configuration options for acts_as_authentic: validate_field, validate_login_field, validate_password_field, validate_email_field
+* 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
 

Manifest

@@ -8,7 +8,7 @@ lib/authlogic/crypto_providers/sha512.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/config.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/credentials.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/logged_in.rb
-lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/password_reset.rb
+lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/perishability.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/persistence.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/session_maintenance.rb
 lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/single_access.rb
@@ -22,7 +22,7 @@ lib/authlogic/session/config.rb
 lib/authlogic/session/cookies.rb
 lib/authlogic/session/errors.rb
 lib/authlogic/session/params.rb
-lib/authlogic/session/password_reset.rb
+lib/authlogic/session/perishability.rb
 lib/authlogic/session/scopes.rb
 lib/authlogic/session/session.rb
 lib/authlogic/version.rb
@@ -44,7 +44,7 @@ test/libs/ordered_hash.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/config_test.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/credentials_test.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/logged_in_test.rb
-test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/password_reset_test.rb
+test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/perishability_test.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/persistence_test.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/session_maintenance_test.rb
 test/orm_adapters_tests/active_record_adapter_tests/acts_as_authentic_tests/single_access_test.rb
@@ -55,7 +55,7 @@ test/session_tests/base_test.rb
 test/session_tests/config_test.rb
 test/session_tests/cookies_test.rb
 test/session_tests/params_test.rb
-test/session_tests/password_reset_test.rb
+test/session_tests/perishability_test.rb
 test/session_tests/scopes_test.rb
 test/session_tests/session_test.rb
 test/test_helper.rb

README.rdoc

@@ -32,6 +32,7 @@ What if your user sessions controller could look just like your other controller
 
     def destroy
       current_user_session.destroy
+      redirect_to new_user_session_url
     end
   end
 
@@ -109,9 +110,9 @@ The user model needs to have the following columns. The names of these columns c
     t.string    :login,                 :null => false
     t.string    :crypted_password,      :null => false
     t.string    :password_salt,         :null => false # not needed if you are encrypting your pw instead of using a hash algorithm.
-    t.string    :remember_token,        :null => false
-    t.string    :single_access_token,   :null => false # optional, see the single access section below.
-    t.string    :password_reset_token,  :null => false # optional, see the password reset section below.
+    t.string    :persistence_token,     :null => false
+    t.string    :single_access_token,   :null => false # optional, see the tokens section below.
+    t.string    :perishable_token,      :null => false # optional, see the tokens section below.
     t.integer   :login_count                           # optional, this is a "magic" column, see the magic columns section below
 
 === Set up your model
@@ -191,39 +192,67 @@ This will keep everything separate. The :secure session will store its info in a
 
 For more information on ids checkout Authlogic::Session::Base#id
 
-== Resetting passwords
+== Tokens (persistence, resetting passwords, private feed access, etc.)
 
-You may have noticed in the helpful links section is a tutorial on resetting password with Authlogic. I'm not going to repeat myself here, but I will touch on the basics, if you want more information please see the tutorial.
+To start, let me define tokens as Authlogic sees it. A token is a form of credentials that grants some type of access to their account. Depending on the type of access, a different type of token may be needed. Put simply, it's a way for the user to say "I am this person, let me proceed". What types of different access you ask? Here are just a few:
 
-Just add the following field to your database:
+1. Regular account access
+2. Access to reset their password
+3. Access to a private feed
+4. Access to confirm their account
 
-  t.string :password_reset_token, :null => false
+There could be many more depending on your application. What's great about Authlogic is that it doesn't care what you do or how you want to grant access to accounts. That's up to you and your application. Authlogic just cares about the type of tokens you need. Instead of giving you a token for each specific task, it gives you all of the necessary *types* of tokens, and you get to use them how you wish. It maintains the tokens and gives you all of the tools you need to use them. Just add the fields to your database and you are good to go.
 
-Authlogic will notice this field and take care of maintaining it for you. You should use the value of this field to verify your user before they reset their password. There is a finder method you can use to find users with this token, I highly recommend using this method, as it adds in extra security checks to verify the user. See Authlogic::ORMAdapters::ActiveRecordAdapter::ActsAsAuthentic::PasswordReset for more information.
+Here are the 3 tokens in more detail:
 
-== Single Access / Private Feeds Access
+=== Persistence token
 
-Need to provide a single / one time access to an account where the session does NOT get persisted? Take a private feed for example, if everyone followed standards, basic http auth should work just fine, but since we live in a world where following standards is not a standard (\*cough\* Microsoft \*cough\*), the feed url needs to have some sort of "credentials" to log the user in and get their user specific feed items. This is easy, Authlogic has a nifty little feature for doing just this. All that you need to do is add the following field in your table:
+This token is used to persist the user's session. This is the token that is stored in the session and the cookie, so that during each request the user stays logged in. What's unique about this token is that the first time it is used the value is stored in the session, thus persisting the session. This field is required and must be in your database.
+
+=== Single access token
+
+This 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* store this value in the session or a cookie. Also, for added security, by default this token is *ONLY* allowed for RSS and ATOM requests. Lastly, this token does *NOT* change with the password. Meaning if the user changes their password, this token will remain the same. You can change all of this with configuration (see Authlogic::Session::config), so if you don't like how this works by default, just set some simple configuration in your session.
+
+This field is optional, if you want to use it just add the field to your database:
 
   t.string :single_access_token, :null => false
   # or call it feeds_token, feed_token, or whatever you want with configuration
 
-Authlogic will notice you have this and adjust accordingly. By default single_access_tokens can only be used to login for rss and atom request types.
+This is great for private feed access. So your URL to that user's private feed could look something like:
+
+  http://www.mydomain.com/account/feed.rss?single_access_token=4LiXF7FiGUppIPubBPey
+
+The single_access_token parameter name is configurable (see Authlogic::Session::Config), but if that parameter exists Authlogic will automatically use it to try and grant that user access. You don't have to do a thing: UserSession.find will take care of it just like it does for everything else.
+
+For more information see: Authlogic::ORMAdapters::ActiveRecordAdapter::ActsAsAuthentic::SingleAccess
+
+=== Perishable token
+
+This token is used for temporary account access, hence the term "perishable". This token is constantly changing, it changes...
+
+1. In a before_validation in your model, so basically every time the record is saved
+2. Any time a new session is successfully saved (aka logged in)
+
+This is perfect for <b>resetting passwords</b> or <b>confirming accounts</b>. You email them a url with this token in it, and then use this token to find the record and perform your action.
+
+This field is optional, if you want to use it just add the field to your database:
+
+  t.string :perishable_token, :null => false
+  # or call it password_reset_token, pw_reset_token, activation_token, or whatever you want with configuration
 
-To tailor how this works, you have the following configuration options:
+Finding the record with this token couldn't be easier, Authlogic provides a special finder method that you can use. I highly recommend using it as it adds extra security:
 
-Session configuration (Authlogic::Session::Config)
+  User.find_using_perishable_token(token)
+  User.find_using_perishable_token(token, 20.minutes)
 
-1. params_key
-2. single_access_allowed_request_types
-3. single_access_token_field
+That's all you need to do to locate the record. Here is what it does for extra security:
 
-Model configuration (Authlogic::ORMAdapters::ActiveRecordAdapter::ActsAsAuthentic::Config)
+1. Ignores blank tokens all together. If a blank token is passed nil will be returned.
+2. It checks the age of the token, by default the threshold is 10 minutes, meaning if the token is older than 10 minutes, it is not valid and no record will be returned. You can change the default or just override it by passing the threshold as the second parameter. If you don't want a threshold at all, pass 0.
 
-1. single_access_token_field:
-2. change_single_access_token_with_password
+For a detailed tutorial on how to reset password using this token see the helpful links section above.
 
-Please use this with care and make sure you warn your users that the URL you provide them is to remain private. Even if Billy 13 year old gets this URL and tries to log in, the only way he can login is through a GET or POST parameter with an rss or atom request. Billy can't create a cookie with this token and Billy wont have access to anything else on the site, unless you change the above configuration.
+For more information see: Authlogic::ORMAdapters::ActiveRecordAdapter::ActsAsAuthentic::Perishability
 
 == Scoping
 

Rakefile

@@ -11,5 +11,4 @@ Echoe.new 'authlogic' do |p|
   p.summary = "A clean, simple, and unobtrusive ruby authentication solution."
   p.url = "http://github.com/binarylogic/authlogic"
   p.dependencies = %w(activesupport)
-  p.include_rakefile = true
 end

lib/authlogic.rb

@@ -13,7 +13,7 @@
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic"
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/credentials"
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/logged_in"
-  require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/password_reset"
+  require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/perishability"
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/persistence"
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/session_maintenance"
   require File.dirname(__FILE__) + "/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/single_access"
@@ -28,7 +28,7 @@
 require File.dirname(__FILE__) + "/authlogic/session/cookies"
 require File.dirname(__FILE__) + "/authlogic/session/errors"
 require File.dirname(__FILE__) + "/authlogic/session/params"
-require File.dirname(__FILE__) + "/authlogic/session/password_reset"
+require File.dirname(__FILE__) + "/authlogic/session/perishability"
 require File.dirname(__FILE__) + "/authlogic/session/session"
 require File.dirname(__FILE__) + "/authlogic/session/scopes"
 require File.dirname(__FILE__) + "/authlogic/session/base"
@@ -40,7 +40,7 @@ class Base
       include Callbacks
       include Cookies
       include Params
-      include PasswordReset
+      include Perishability
       include Session
       include Scopes
     end

lib/authlogic/orm_adapters/active_record_adapter/acts_as_authentic/config.rb

@@ -77,17 +77,18 @@ module ActsAsAuthentic
         # * <tt>password_salt_field</tt> - default: :password_salt, :pw_salt, or :salt, depending on which column is present, defaults to :password_salt if none are present,
         #   This is the name of the field in your database that stores your password salt.
         #
-        # * <tt>password_reset_token_field</tt> - default: :password_reset_token, :pw_reset_token, :reset_password_token, or :reset_pw_token, depending on which column is present, if none are present defaults to nil
-        #   This is the name of the field in your database that stores your password reset token. The token you should use to verify your users before you allow a password reset. Authlogic takes care
-        #   of maintaining this for you and making sure it changes when needed.
+        # * <tt>perishable_token_field</tt> - default: :perishable_token, :password_reset_token, :pw_reset_token, :reset_password_token, or :reset_pw_token, depending on which column is present, if none are present defaults to nil
+        #   This is the name of the field in your database that stores your perishable token. The token you should use to confirm your users or allow a password reset. Authlogic takes care
+        #   of maintaining this for you and making sure it changes when needed. Use this token for whatever you want, but keep in mind it is temporary, hence the term "perishable".
         #
-        # * <tt>password_reset_token_valid_for</tt> - default: 10.minutes,
-        #   Authlogic gives you a sepcial method for finding records by the password reset token (see Authlogic::ORMAdapters::ActiveRecordAdapter::ActcsAsAuthentic::PasswordReset). In this method
-        #   it checks for the age of the token. If the token is old than whatever you specify here, a user will NOT be returned. This way the tokens are perishable, thus making this system much
+        # * <tt>perishable_token_valid_for</tt> - default: 10.minutes,
+        #   Authlogic gives you a sepcial method for finding records by the perishable token (see Authlogic::ORMAdapters::ActiveRecordAdapter::ActcsAsAuthentic::Perishability). In this method
+        #   it checks for the age of the token. If the token is older than whatever you specify here, a record will NOT be returned. This way the tokens are perishable, thus making this system much
         #   more secure.
         #   
-        # * <tt>remember_token_field</tt> - default: :remember_token, :remember_key, :cookie_tokien, or :cookie_key, depending on which column is present, defaults to :remember_token if none are present,
-        #   This is the name of the field your remember_token is stored. The remember token is a unique token that is stored in the users cookie and
+        # * <tt>persistence_field</tt> - default: :persistence_token, :remember_token, or :cookie_tokien, depending on which column is present,
+        #   defaults to :persistence_token if none are present,
+        #   This is the name of the field your persistence token is stored. The persistence token is a unique token that is stored in the users cookie and
         #   session. This way you have complete control of when sessions expire and you don't have to change passwords to expire sessions. This also
         #   ensures that stale sessions can not be persisted. By stale, I mean sessions that are logged in using an outdated password.
         #   
@@ -149,11 +150,11 @@ def acts_as_authentic_with_config(options = {})
             options[:confirm_password_did_not_match_message] ||= "did not match"
             options[:crypted_password_field] ||= first_column_to_exist(:crypted_password, :encrypted_password, :password_hash, :pw_hash)
             options[:password_salt_field] ||= first_column_to_exist(:password_salt, :pw_salt, :salt)
-            options[:remember_token_field] ||= first_column_to_exist(:remember_token, :remember_key, :cookie_token, :cookiey_key)
+            options[:persistence_token_field] ||= options[:remember_token_field] || first_column_to_exist(:persistence_token, :remember_token, :cookie_token)
             options[:single_access_token_field] ||= first_column_to_exist(nil, :single_access_token, :feed_token, :feeds_token)
-            options[:password_reset_token_field] ||= first_column_to_exist(nil, :password_reset_token, :pw_reset_token, :reset_password_token, :reset_pw_token)
-            options[:password_reset_token_valid_for] ||= 10.minutes
-            options[:password_reset_token_valid_for] = options[:password_reset_token_valid_for].to_i
+            options[:perishable_token_field] ||= options[:password_reset_token_field] || first_column_to_exist(nil, :perishable_token, :password_reset_token, :pw_reset_token, :reset_password_token, :reset_pw_token, :activation_token)
+            options[:perishable_token_valid_for] ||= 10.minutes
+            options[:perishable_token_valid_for] = options[:perishable_token_valid_for].to_i
             options[:logged_in_timeout] ||= 10.minutes
             options[:logged_in_timeout] = options[:logged_in_timeout].to_i
             options[:session_ids] ||= [nil]