Binary Logic

Searchlogic 1.5.7 - Complex searching no longer a problem

2008-11-30T07:59:00Z

Searchlogic 1.5.7 is by far my favorite release because it takes Searchlogic to a whole new level. It solves a problem I thought it would never solve. Before I explain the new features, let me give you a quick run down on my perspective of Searchlogic:

Fillin' a brotha in

A lot of people think Searchlogic is a "console" searching utility. Meaning you can pop into your console and execute some simple searches quickly and easily, and it is, but by accident. My goal with Searchlogic has always been freeing your application of searching clutter. If you've ever done an app with searching you know there is a lot of "cruft" that goes along with it: nasty controller actions, excessive named_scopes, etc. Searchlogic rids you of this by representing an entire search's criteria with a hash: conditions, ordering, pagination, the whole package. Why is this nice? Because GET and POST parameters are a hash. What's nice about that? Because an HTML form's sole purpose is to send GET and POST parameters to a URI. This means you can build a form that represents your entire search. Adding a condition to your search is as easy as adding a field to your form. This ultimately makes your controller dead simple, frees it of any search clutter, and rids your models of excessive named_scopes. Here is what your controller action should look like with Searchlogic:

@search = User.new_search(params[:search])
@users = @search.all

Complex searching in tha house

This is great for simple searching, but how do you represent complex searches this way? Let's take this query:

select * from users where id > 5 AND
  (email LIKE 'ben%' or email LIKE '%binarylogic.com') AND
  first_name LIKE '%ben%'

Before, Searchlogic couldn't handle this. It did not support grouping (parenthesis) and it did not allow you to mix and match "AND" and "OR", you had to pick one or the other. Why? Because I never intended for Searchlogic to replace complex searching. If you need to perform a complex search there is nothing wrong with using Searchlogic in conjunction with some named_scopes. SQL is not bad, but what is bad is that all of that searching cruft starts seeping back into your project. All of a sudden your controller is not clean, your form has to stray away from using the form builder, and your model gets cluttered with named scopes that you are only using for one section in your application. Searchlogic fails to meet its goal of keeping your application free of "search clutter" and a tear runs down your cheek.

Slap a prefix on it!

Solving the problem of mixing "AND" and "OR" was easier than I thought. The only major change I had to make was making the conditions order relevant. The order you set your conditions is the same order they will appear in your SQL statement. Before, the conditions were stored in a hash, where order was not preserved. Now you can slap an "and_" or "or_" prefix in front of your conditions:

search = User.new_search
search.conditions.name_like = "Ben"
search.conditions.or_email_like = "a@a.com"
search.conditions.and_id_gt = 5
# => name LIKE '%Ben%' OR email like '%a@a.com%' AND id > 5

The last condition "and_id_gt" could also be written as "id_gt", because, by default, we are joining with "AND". Not specifying a prefix uses whatever you are joining your conditions with by default, specifying a prefix will always use that join. If you want your conditions to be joined by "OR" by default just do:

search.any = true

You best wrap it with some parenthesis

What about grouping conditions with parenthesis? No problem. Take the above query:

search = User.new_search
search.conditions.id_gt = 5
search.conditions.group do |group|
  group.email_begins_with = "ben"
  group.or_email_ends_with = "binarylogic.com"
end
search.conditions.first_name_contains = "ben"
search.all

What about a hash?

search = User.new_search(:conditions => [
  {:id_gt => 5},
  {:group => [
    {:email_begins_with => "ben"},
    {:or_email_ends_with => "binarylogic.com"}
  ]},
  {:first_name_contains => "ben"}
])

What about a form?

- form_for @search do |search|
  - search.fields_for "conditions" do |conditions_array|
    - conditions_array.fields_for "[]", search.object.conditions do |conditions|
      = conditions.text_field :id_gt
      - conditions.fields_for "group" do |group_array|
        - group_array.fields_for "[]" do |group|
          = group.text_field :email_begins_with
          = group.text_field :or_email_ends_with
      = conditions.text_field :first_name_contains

You will notice the hash and the form are implementing arrays, thats because hashes do not preserve the order. In our case above, order is important to us. What does preserve the order? An array. So if order is relevant to you, then you need to structure your conditions into an array. There is no other choice with this, because forms can either submit a hash or an array of parameters.

I know what you are thinking: "the above looks a little confusing and messy". I agree with you, to a point. The word "messy" is a relative term. In our case, we have no other choice, this is the 100% correct way to do this. That being said, this is clean, because there is no other cleaner option. Sorry to be a debbie downer here, but this is how forms work, there is nothing I can do about that. Regardless, the above is still cleaner than having a nasty controller action or adding a bunch of named_scopes into you model. Your search logic is nice and DRY, in one spot: the view.

99 problems, but complex searching aint one

I think this is pretty nifty, now you have the tools to construct any type of search in your form. I've been getting a lot of emails asking me about this, and I had to be a debbie downer and tell them to use named scopes. Now you can ditch the named scopes and keep your search logic nice and DRY in your form, where it probably belongs.

The last thing I want to say is that there is a time and a place for a named scope, by no means am I discouraging them, because they are by far one of the nicest features in ActiveRecord. But something about creating a complex named scope or a bunch of small named scopes for a single action in one of my controllers felt dirty. It felt like clutter. I knew I would never use those named scopes anywhere else, and they were solely for that search form. After a while all of these named scopes start overlapping and start sharing search logic. If you're extremely picky like me, your don't feel like your code is DRY. So how far do you go to break down a named scope? Breaking them down too much defeats their purpose, but not breaking them down enough seems to create redundant search logic. Searchlogic solved my problem with this, now all of my view specific search logic is where it should be, in my view.

Tutorial: Easily migrate from restful_authentication to Authlogic

2008-11-23T22:46:00Z

I've been getting a lot of emails asking the best way to migrate from restful_authentication. Where it gets complicated is in the password encryption methods. Authlogic and restful_authentication use different methods. You don't want to change this method because it will break backwards compatibility with your current passwords, meaning no one will be able to log into their account. Fear not, because I did all of the hard work for you...

Use the same password algorithm as restful_authentication

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :act_like_restful_authentication => true
end

Transition to one of Authlogic password algorithms

The first thing you need to do is make sure your database field "crypted_password" and "salt" allow for the storage of at least 128 characters (assuming you are migrating to Sha512). restful_authentication uses Sha1 which is 40 characters. If you are limiting the size, you need to create a migration that looks similar to:

change_column :users, :crypted_password, :string, :limit => 128,
  :null => false, :default => ""

change_column :users, :salt, :string, :limit => 128,
  :null => false, :default => ""

Now just tell acts_as_authentic what you are doing:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :transition_from_restful_authentication => true
end

You could pass an optional argument to transition to any password algorithm you want. By default Authlogic uses the Sha512 algorithm, but let's say you wanted to transition to the BCrypt algorithm. No problem:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :transition_from_restful_authentication => true,
    :crypto_provider => Authlogic::CryptoProviders::BCrypt
end

For more information on BCrypt checkout my blog post about it.

What's the difference?

:act_like_restful_authentication will not change a thing, your users passwords will remain in the same format. From your database's perspective, it will be as if you are using restful_authentication.

:transition_from_restful_authentication starts changing your users passwords using the Authlogic passwords system that you specify with the :crypto_provider option. How does it do this? It's simple, every time a user successfully logs in and their password is encrypted with the restful_authentication algorithm it will update their password with the Authlogic algorithm. When a new account is created it will use the Authlogic algorithm. This allows your user base to slowly transition and allowing them to still be able to log in.

That's it. I'm not going to go into the Authlogic set up because I already have a tutorial on this.

Let me know what you think or if you have any questions.

Tutorial: Upgrade passwords easily with Authlogic

2008-11-23T22:02:00Z

I released Authlogic 1.3.3 which has some handy options for migrating passwords to a new and improved algorithm. Without Authlogic this is somewhat of a pain in the ass, because there has to be a transition period in which your users can upgrade their passwords. You can't just upgrade the algorithm because then no one will be able to log in. Authlogic solves this problem and makes it dead simple:

Migrating to another password algorithm within Authlogic

I recently released BCrypt as an optional crypto provider for Authlogic, let's say you are using the default crypto provider Sha512 and want to start using BCrypt. No problem:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :transition_from_crypto_provider => Authlogic::CryptoProviders::Sha512,
    :cypto_provider => Authlogic::CryptoProviders::BCrypt
end

All of your users will be migrated to the new BCrypt method when they log in next or when a user creates a new account.

Let's pretend a new algorithm came out called "CCrypt", and its better than BCrypt, and you want to use it. You're users are in the middle of transitioning from Sha512 to BCrypt. Oh no!

Not to worry, because Authlogic can transition your users from more than one algorithm. Just pass an array to :transition_from_crypto_provider

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :transition_from_crypto_provider => [Authlogic::CryptoProviders::Sha512,
    Authlogic::CryptoProviders::BCrypt], :cypto_provider => CCrypt
end

That's it. You can specify as many as you want. When your users login or create a new account their passwords will be encrypted with the CCrypt algorithm.

Migrating from any other password algorithm

All that you need to do is create a crypto provider that represents how your passwords are encrypted. Believe it or not, it's dead simple. Sometimes the easiest way to explain something is by using code example, so please checkout the Authlogic::CryptoProviders module and sub classes in the documentation. All that you need to do is create a class with a class level encrypt and matches? method:

# lib/my_awesome_crypto_provider.rb
class MyAwesomeCryptoProvider
  def self.encrypt(*tokens)
    # encrypt your password here
  end

  def self.matches?(crypted_password, *tokens)
    # return true if the tokens match the crypted_password
  end
end

Then just tell Authlogic about it:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :transition_from_crypto_provider => MyAwesomeCryptoProvider,
    :cypto_provider => Authlogic::CryptoProviders::BCrypt
end

Transition to a new algorithm doesn't get any easier than that.

Storing nuclear launch codes in your app? Enter BCrypt for Authlogic.

2008-11-22T18:43:00Z

Today is Saturday, which is "fun day", and there is nothing more fun that talking about encryption algorithms. So let's get started...

Part of Authlogic's responsibility to is to keep you on the cutting edge when it comes to security. Afterall, that is part of the reason you use Authlogic, so you don''t have to deal with it. Your app can use the latest and great security techniques just by updating the Authlogic gem.

That being said, today I released Authlogic 1.3.2. With this came a new optional crypto provider: BCrypt. According the to BCrypt website:

"There are two kinds of cryptography in this world: cryptography that will stop your kid sister from reading your files, and cryptography that will stop major governments from reading your files."

My personal opinion is that the default Sha512 encryption that Authlogic uses is plenty secure, emphasis on plenty. Authlogic uses salted Sha512 with multiple stretches. Hell, the majority of apps use Sha1, because that's what restful_authentication uses, and Sha1 is much less secure. I don't want to link to these resources directly, but there are a number of resources available to perform reverse lookups on Sha1. I don't want to paint the wrong picture here by saying Sha1 is insecure. It's all in how you use it. As long as you are salting it and doing a number of stretches, which restful_authenticaton is doing, you are fine. But if you are storing extremely sensitive information in your app, such as nuclear launch codes, then you might consider something a little more secure.

What makes BCrypt more secure?

For one, BCrypt provides it's own salting, then Authlogic provides salting as well. Double salting!

Secondly, when it comes to hashing algorithms, security mostly deals with the amount of time it takes to generate the hash. Take a dictionary attack on a Sha1 algorithm. A decent computer could fly through a list of every dictionary word in a relatively fast amount of time compared to BCrypt. Let me show you wish some benchmarks:

Benchmark.bm(18) do |x|
  x.report("BCrypt (cost = 10:") { 100.times { BCrypt::Password.create("mypass", :cost => 10) } }
  x.report("BCrypt (cost = 2:") { 100.times { BCrypt::Password.create("mypass", :cost => 2) } }
  x.report("Sha512:") { 100.times { Digest::SHA512.hexdigest("mypass") } }
  x.report("Sha1:") { 100.times { Digest::SHA1.hexdigest("mypass") } }
end

#                         user     system      total        real
# BCrypt (cost = 10): 10.780000   0.060000  10.840000 ( 11.100289)
# BCrypt (cost = 2):  0.180000   0.000000   0.180000 (  0.181914)
# Sha512:             0.000000   0.000000   0.000000 (  0.000829)
# Sha1:               0.000000   0.000000   0.000000 (  0.000395)

That my friend is a huge difference. There is a trade off between security and performance. If you are willing to take the performance hit then go for it. Play with the :cost option to get that perfect balance between performance and security. By default the BCrypt library uses a cost of 10.

Easily upgrade encryption and transition your users

As I mentioned above, the cost can be adjusted. So let's say 5 years from now a cost of 10 isn't as effective as it used to be, because computers are now faster, things have advanced, etc. No problem, just bump the cost up to whatever is now suitable. Your old passwords will continue to work, while the new passwords will be much stronger.

Here's why using a library like Authlogic is so nice. As your users start to log in, Authlogic will handle upgrading their passwords to the new and improved cost.

Now your app can move with the times and constantly stay on the cutting edge of security, and you don't have to worry about breaking all of your users passwords.

This is a cool feature, but nothing to go crazy about. The average app will probably never need to upgrade their encryption algorithm. If your app is around long enough, maybe you will upgrade it once. Even then, it's probably not necessary because of the salting and stretches. Regardless, Authlogic will assist you in your upgrade if you choose to do so.

Lastly, you can get this feature with any encryption algorithm, including Sha. Checkout the "Upgrading encryption methods" in the Authlogic README. It's very simple.

How do I use this?

It's simple:

$ sudo gem install bcrypt-ruby

Starting a new app?:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :crypto_provider => Authlogic::CryptoProviders::BCrypt
end

Looking to switch to BCrypt?:

# app/models/user.rb
class User < ActiveRecord::Base
  acts_as_authentic :crypto_provider => Authlogic::CryptoProviders::BCrypt,
    :transition_from_crypto_provider => Authlogic::CryptoProviders::Sha512
end

The :transition_from_crypto_provider is whatever crypto provider you are currently using. Check out my blog posts about transitioning to another crypto provider:

What about [insert encryption method here]?

Check out the Authlogic::CryptoProviders module and the subclasses within. You can add you own method just by creating a simple class and letting acts_as_authentic know about. Authlogic bundles some common methods as a convenience to you, there is nothing wrong with adding your own if you feel its necessary.

Why isn't this the default encryption method for Authlogic?

I have heard of people having issues with the BCrypt library on windows. I have not used windows in years, so don't take my word for it, but approach it with some caution. I decided to go with Sha512 since that is part of the ruby core and works wherever ruby can be installed.

Then again, using a library like bcrypt on windows is somewhat ironic. If you are very concerned with security I doubt you will be putting your app on windows. To me using BCrypt on Windows is like putting a state of the art lock on a cardboard box.

Final thoughts

The level of security your app provides is really up to you. Unless you are writing apps for the pentagon, the default Sha512 is fine. Regardless, Authlogic shouldn't get in your way or make decisions for you, so if you feel BCrypt is necessary then go for it.

Tutorial: Using OpenID with Authlogic

2008-11-21T02:12:00Z

I know some of you have been waiting for OpenID support in Authlogic. I came up with a pretty slick solution this (check out a live example here), I think you will like it. That being said, let me show you:

My dream

My dream is that the following code, in your sessions controller, would be capable of handling any type of authentication method you throw at it:

# app/controllers/user_sessions_controller.rb
def create
  @user_session = UserSession.new(params[:user_session])
  @user_session.save do |result|
    if result
      flash[:notice] = "Login successful!"
      redirect_back_or_default account_url
    else
      render :action => :new
    end
  end
end

That could handle regular authentication, OpenID authentication, Facebook connection authentication, LDAP authentication, or whatever you want, the sky is the limit. There is no OpenID cruft in your controller, and it won't get cluttered as you add more methods. Your controller stays clean and focused.

Guess what? You're in luck, because the above code can do that. Here's how...

My approach

As I'm sure you know, OpenID is not the only single sign on method. Microsoft has their own, Facebook has their own, corporations have their own private method, a lot of universities use LDAP, etc. So it would be silly of me to build specific OpenID support directly into Authlogic. I want to keep Authlogic focused on the core authentication methods. I want to keep it clean, small, and focused. By writing an OpenID solution specific for Authlogic I am just recreating the wheel, bloating Authlogic, and adding more responsibility to the library. All of the current OpenID solutions for ruby are very good, there is very little room for improvement. Why not use them?

So I took a different approach. Instead of writing OpenID specific code, I am giving you all of the tools you need to implement any type of single sign on method easily and quickly. Now when you get that client that has to have the Facebook single sign on method, it will fit into your application nicely, and you don't have to wait for Authlogic to add support for it.

Let me walk you through implementing OpenID, and you can judge for yourself how easy this is:

What I'm assuming you know

What Authlogic is and how to set it up
What the Authlogic example app is. If you don't know what this is, it's an app I have been building with the tutorials I have been writing. What tutorials?
1. Authlogic basic setup
2. Resetting password with Authlogic
What OpenID is and how it works

Some helpful links for reference

1. Install the ruby-openid gem and open_id_authentication plugin

Install the openid gem:

$ gem install ruby-openid

Now install the open_id_authentication rails plugin:

$ script/plugin install git://github.com/rails/open_id_authentication.git

2. Add the proper database fields

$ script/generate migration add_users_openid_field

Your migration should look like:

class AddUsersOpenidField < ActiveRecord::Migration
  def self.up
    add_column :users, :openid_identifier, :string
    add_index :users, :openid_identifier

    change_column :users, :login, :string, :default => nil, :null => true
    change_column :users, :crypted_password, :string, :default => nil, :null => true
    change_column :users, :password_salt, :string, :default => nil, :null => true
  end

  def self.down
    remove_column :users, :openid_identifier
    [:login, :crypted_password, :password_salt].each do |field|
      User.all(:conditions => "#{field} is NULL").each { |user| user.update_attribute(field, "") if user.send(field).nil? }
      change_column :users, field, :string, :default => "", :null => false
    end
  end
end

We are changing the login, crypted_password, and password_salt field to be optional now that your users have the OpenID option. The down method is setting all nil fields to "" otherwise you will get a database error.

By default the open_id_authentication plugin uses database store to store all of the OpenID associations and nonces. It comes with a handy generator for those migrations:

$ script/generate open_id_authentication_tables create_openid_tables

Now let's migrate everything:

$ rake db:migrate

3. Update User validation

Now let's make some changes to our User model to accommodate for this:

# app/models/user.rb
acts_as_authentic :login_field_validation_options => {:if => :openid_identifier_blank?},
  :password_field_validation_options => {:if => :openid_identifier_blank?}

validate :normalize_openid_identifier
validates_uniqueness_of :openid_identifier, :allow_blank => true

# For acts_as_authentic configuration
def openid_identifier_blank?
  openid_identifier.blank?
end

private
  def normalize_openid_identifier
    begin
      self.openid_identifier = OpenIdAuthentication.normalize_url(openid_identifier) if !openid_identifier.blank?
    rescue OpenIdAuthentication::InvalidOpenId => e
      errors.add(:openid_identifier, e.message)
    end
  end

The above code just tells Authlogic to allow blank values for the login and password, it makes sure a login is supplied if no openid is given, it makes sure the openid is unique, and it also normalizes the openid that the user passes. Simple enough.

4. Update your UserSessionsController

Here is my favorite part, and why Authlogic is so nice for integrating with methods like this. Change your create method to look like this:

# app/controllers/user_sessions_controller.rb
def create
  @user_session = UserSession.new(params[:user_session])
  @user_session.save do |result|
    if result
      flash[:notice] = "Login successful!"
      redirect_back_or_default account_url
    else
      render :action => :new
    end
  end
end

Notice the small 1 line change? We are now passing a block to save. I think that's pretty slick because that block will do everything for you. It will redirect the user to their proper OpenID provider, thus keeping your UserSessionsController clean and focused and not full of OpenID clutter.

But wait, Authlogic is not magical, we need to tell our UserSession how to integrate in with the open_id_authentication plugin. No problem...

5. Update your UserSession

Let's just override the save method and implement our OpenID specific code:

# app/models/user_session.rb
class UserSession < Authlogic::Session::Base
  attr_accessor :openid_identifier

  def authenticating_with_openid?
    !openid_identifier.blank? || controller.params[:open_id_complete]
  end

  def save(&block)
    if authenticating_with_openid?
      raise ArgumentError.new("You must supply a block to authenticate with OpenID") unless block_given?

      controller.send(:authenticate_with_open_id, openid_identifier) do |result, openid_identifier|
        if !result.successful?
          errors.add_to_base(result.message)
          yield false
          return
        end

        record = klass.find_by_openid_identifier(openid_identifier)

        if !record
          errors.add(:openid_identifier, "did not match any users in our database, have you set up your account to use OpenID?")
          yield false
          return
        end

        self.unauthorized_record = record
        super
      end
    else
      super
    end
  end
end

Let me explain what is going on here:

The authenticating_with_openid? method is just letting us know if they are trying to login with OpenID or not, we use this in the save method.
The save method is just checking if the user is authenticating with OpenID, if so it uses the open_id_authentication plugin to do its magic. I won't get into the specifics of this plugin because it has its own README and documentation, but it's pretty simple and self explanatory.
You will notice once we find the record we set it to unauthorized_record. This is an authentication method that Authlogic supplies as an alternative to login / password authentication. Basically when you do this you are vouching for the user. You are saying "I can guarantee this user is who he says he is, lets create a session for him". Authlogic uses this itself when persisting the sessions via a cookie. It just finds the record with the matching cookie token and then vouches for the user by authenticating this way.

Final thoughts

As you can see, you can take the above method and do pretty much anything you want. There are no restrictions and there is no authentication method that can't be implemented this way. Authlogic doesn't choose how you implement the method either. You can use any plugin you want, or write your own code, the sky is the limit.

Let me know what you think, if you like it, hate it, etc. I am always looking to improve my tutorials / libraries.

Tutorial: Reset passwords with Authlogic the RESTful way

2008-11-16T15:19:00Z

I've been getting emails asking me how to reset passwords with Authlogic, or how to confirm accounts. In this tutorial I'll cover resetting passwords, since it is more complex, but after reading this tutorial there is no reason why you couldn't set up account confirmation as well. In fact, my next tutorial will cover just that.

What am I about to read?

You are going to read a tutorial on how to reset passwords the RESTful way. I am going to pick up where I left off on the Authlogic basic setup tutorial, so if you have not read that I highly recommend doing so.

Want to see it in action before you start? Check it out for yourself:

A live example of this tutorial

Before we begin, let me walk you through the basic process of resetting a password as I see it:

A user requests a password reset
An email is sent to them with a link to reset their password
The user verifies their identity be using the link we emailed them
They are presented with a basic form to change their password
After they change their password we log them in, redirect them to their account, and expire the URL we just sent them

That seems pretty simple, right? So let's get started...

Helpful links

Before we start I want give you some helpful / related links:

1. Add in the reset_password_token and email fields

I am going to pick up from the Authlogic basic setup tutorial, so I am assuming you are familiar with Authlogic and the basic setup.

With this tutorial I am introducing a new field in your database called perishable_token. Authlogic will take care of maintaining this for you. Here is how:

The token gets set to a unique value before validation, which constantly changes the token. The value is a "friendly" value, something like: 4LiXF7FiGUppIPubBPey, not as long or as hardcore as a Sha512 hash, so it doesn't cause problems when emailed or copying and pasting into a browser.
After a session is successfully saved (aka logged in) the the token will be reset. This makes the email we sent them before no longer usable.

Generate your migration:

$ script/generate migration add_users_password_reset_fields

Now update the migration:

class AddUsersPasswordResetFields < ActiveRecord::Migration
  def self.up
    add_column :users, :perishable_token, :string, :default => "", :null => false
    add_column :users, :email, :string, :default => "", :null => false

    add_index :users, :perishable_token
    add_index :users, :email
  end

  def self.down
    remove_column :users, :perishable_token
    remove_column :users, :email
  end
end

Migrate your database:

$ rake db:migrate

When adding the email field Authlogic will notice this and validate it for you, making sure the email is unique and a valid email address. If you wish to disable this just pass the :validate_email_field => false option to acts_as_authentic. You can also have it ignore the email field all together by passing the :email_field => nil option.

2. Let users request a password reset

We need to know if users lost their password, why not create another resource for this?

$ script/generate controller password_resets

Let's fill out this controller with some actions (I will explain them below):

# app/controllers/password_resets_controller.rb
class PasswordResetsController < ApplicationController
  def new
    render
  end

  def create
    @user = User.find_by_email(params[:email])
    if @user
      @user.deliver_password_reset_instructions!
      flash[:notice] = "Instructions to reset your password have been emailed to you. " +
        "Please check your email."
      redirect_to root_url
    else
      flash[:notice] = "No user was found with that email address"
      render :action => :new
    end
  end
end

Now update your routes:

# config/routes.rb
map.resources :password_resets

What did I just do?

The deliver_password_reset_instructions! is a method I added, you can call it whatever you want. All that it does is reset the password reset token and send an email.

Here is what I did in my own application:

# app/models/user.rb
class User < ActiveRecord::Base
  def deliver_password_reset_instructions!
    reset_perishable_token!
    Notifier.deliver_password_reset_instructions(self)
  end
end

The reset_perishable_token! is a handy method Authlogic gives you. It basically resets the field to a unique "friendly" token and then saves the record.

My Notifier action looks like this:

# app/models/notifier.rb
class Notifier < ActionMailer::Base
  default_url_options[:host] = "authlogic_example.binarylogic.com"

  def password_reset_instructions(user)
    subject       "Password Reset Instructions"
    from          "Binary Logic Notifier <noreply@binarylogic.com>"
    recipients    user.email
    sent_on       Time.now
    body          :edit_password_reset_url => edit_password_reset_url(user.perishable_token)
  end
end

Then the email looks like:

# app/views/notifier/password_reset_instructions.erb
A request to reset your password has been made.
If you did not make this request, simply ignore this email.
If you did make this request just click the link below:

<%= @edit_password_reset_url %>

If the above URL does not work try copying and pasting it into your browser.
If you continue to have problem please feel free to contact us.

You can do the above any way you want. I actually recommend creating a text and html version of this email, but for the sake of brevity I only included the text version.

3. Let users reset their password

Once they get that email and click the link in it, it needs to take them somewhere. So let's add some methods to our PasswordResetsController:

# app/controllers/password_resets_controller.rb
before_filter :load_user_using_perishable_token, :only => [:edit, :update]

def edit
  render
end

def update
  @user.password = params[:user][:password]
  @user.password_confirmation = params[:user][: password_confirmation]
  if @user.save
    flash[:notice] = "Password successfully updated"
    redirect_to account_url
  else
    render :action => :edit
  end
end

private
  def load_user_using_perishable_token
    @user = User.find_using_perishable_token(params[:id])
    unless @user
      flash[:notice] = "We're sorry, but we could not locate your account. " +
        "If you are having issues try copying and pasting the URL " +
        "from your email into your browser or restarting the " +
        "reset password process."
      redirect_to root_url
    end
  end

What did I just do?

You really don't need to add the edit method because its a blank method, the before_filter takes care of everything we need to do there. There is only a view for this method.
The update method is nice, because if the user is successfully saved, Authlogic will automatically log them in, keeping your PasswordResetsController focused on resetting passwords, not sessions.
The load_user_using_perishable_token has a unique method: find_using_perishable_token. This is a special method that Authlogic gives you. Here is what it does for extra security:
1. Ignores blank tokens
2. Only finds records that match the token and have an updated_at (if present) value that is not older than 10 minutes. This way, if someone gets the data in your database any valid perishable tokens will expire in 10 minutes. Chances are they will expire quicker because the token is changing during user activity as well.

4. Restrict access

Now we just need to make sure the user is logged out when accessing these methods. Modify your before filters in your PasswordResetsController to look like:

  before_filter :require_no_user

Where are the views?

Instead of cluttering up this tutorial with a bunch of basic views, I left them out. There is nothing crazy going on in the views, nor do I really need to explain anything. If you noticed in the helpful links section I have a live example of this tutorial.

Here is a direct link to the users views source code, you can copy the views over from here

Why not reset passwords this way...?

If you care, here are my thoughts behind this tutorial and ultimately why I recommend resetting passwords this way...

My goal with Authlogic was to stay away from generating code and give you the proper tools so that you could easily and effectively write the code yourself. If you noticed, in this tutorial, all that we really did was add a simple PasswordResetsController. Most of this tutorial was explaining what was going on, so you could understand what you were doing. I can't write that controller for you, because it is application specific. I want to keep the authentication logic in Authlogic and your application logic in your application. The tutorial above produces simpler and cleaner code than a generator. The most important part is that you understand what is going on and it works the way you want. I am basically laying out tools for you to use and explaining them. You get to use them how you wish. There is no "Surprise! Here are hundreds of lines of code, hope you like it". If you want to change passwords a different way, go for it, you now know how Authlogic can assist you in your journey to resetting passwords.

Lastly, I know there are a few other common ways to reset passwords, so I will address those and why I decided against them:

Changing / randomizing the password during the first step and then emailing them their new password
You should NEVER change anyone's password until they have proven they are that user. What if Billy 13 year old starts typing in random logins and resetting peoples passwords? Those people aren't going to be happy.
Using an already existing token that is not unique or perishable
A lot of people are tempted to use the remember_token, single_access_token, or even the crypted_password for authenticating the user for a password change. There is a reason we have all of these and none of these should be used for resetting password. What if Billy 13 year old gets ahold of any of these, he will have full access to resetting that user's password, and then have full access to their account. If for some reason he gets any of these things, your users should still be protected, which is why we need a unique and perishable token.