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. In this case we are authenticating with a User model, which is inferred by the name:

  class UserSession < Authlogic::Session::Base
  end

Log in with any of the following. Use it just like your other models:

  UserSession.create(my_user_object)
  UserSession.create(:login => "bjohnson", :password => "my password")
  session = UserSession.new(:login => "bjohnson", :password => "my password"); session.save
  UserSession.create(:openid_identifier => "identifier") # requires the authlogic-oid "add on" gem

After a session has been created, you can persist it across requests:

  session = UserSession.find

You can also log out / destroy the session:

  session.destroy

Helpful links

• Documentation: authlogic.rubyforge.org
• Live example with OpenID "add on": authlogicexample.binarylogic.com
• Live example source with tutorial: github.com/binarylogic/authlogic_example/tree/master
• Tutorial: Reset passwords with Authlogic the RESTful way: www.binarylogic.com/2008/11/16/tutorial-reset-passwords-with-authlogic
• Bugs / feature suggestions: binarylogic.lighthouseapp.com/projects/18752-authlogic
• Google group: groups.google.com/group/authlogic

Before contacting me, please read:

If you find a bug or a problem please post it on lighthouse. 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. I will NOT respond to emails that should otherwise be in lighthouse or google groups.

Authlogic "add ons"

• Authlogic OpenID addon: github.com/binarylogic/authlogic_openid
• Authlogic LDAP addon: github.com/binarylogic/authlogic_ldap

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.

Documentation explanation

You can find anything you want about Authlogic in the documentation, 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. Authlogic::Session, which manages sessions.
2. Authlogic::ActsAsAuthentic, which adds in functionality to your ActiveRecord model.

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 Authlogic::Session::Timeout. 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.

Authlogic::ActsAsAuthentic sub modules

These modules are for the acts_as_authentic method you call in your model. It contains all code for the "model side" of the authentication.

• Authlogic::ActsAsAuthentic::Base - Provides the acts_as_authentic class method and includes all of the submodules.
• Authlogic::ActsAsAuthentic::Email - Handles everything related to the email field.
• Authlogic::ActsAsAuthentic::LoggedInStatus - Provides handy named scopes and methods for determining if the user is logged in or out.
• Authlogic::ActsAsAuthentic::Login - Handles everything related to the login field.
• Authlogic::ActsAsAuthentic::MagicColumns - Handles everything related to the "magic" fields: login_count, failed_login_count, etc.
• Authlogic::ActsAsAuthentic::Password - This one is important. It handles encrypting your password, salting it, etc. It also has support for transitioning password algorithms.
• Authlogic::ActsAsAuthentic::PerishableToken - Handles maintaining the perishable token field, also provides a class level method for finding record using the token.
• Authlogic::ActsAsAuthentic::PersistenceToken - Handles maintaining the persistence token. This is the token stored in cookies and sessions to persist the users session.
• Authlogic::ActsAsAuthentic::RestfulAuthentication - Provides configuration options to easily migrate from the restful_authentication plugin.
• Authlogic::ActsAsAuthentic::SessionMaintenance - Handles automatically logging the user in. EX: a new user registers, automatically log them in.
• Authlogic::ActsAsAuthentic::SingleAccessToken - Handles maintaining the single access token.
• Authlogic::ActsAsAuthentic::ValidationsScope - Allows you to scope validations, etc. Just like the :scope option for validates_uniqueness_of

Authlogic::Session sub modules

These modules are for the "session side" of authentication. They create a new domain for session logic, allowing you to create, destroy, and ultimately manage your sessions.

• Authlogic::Session::BruteForceProtection - Disables accounts after a certain number of consecutive failed logins attempted.
• Authlogic::Session::Callbacks - 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
• Authlogic::Session::Cookies - Authentication via cookies.
• Authlogic::Session::Existence - Creating, saving, and destroying objects.
• Authlogic::Session::HttpAuth - Authentication via basic HTTP authentication.
• Authlogic::Session::Id - Allows sessions to be separated by an id, letting you have multiple sessions for a single user.
• Authlogic::Session::MagicColumns - Maintains "magic" database columns, similar to created_at and updated_at for ActiveRecord.
• Authlogic::Session::MagicStates - Automatically validates based on the records states: active?, approved?, and confirmed?. If those methods exist for the record.
• Authlogic::Session::Params - Authentication via params, aka single access token.
• Authlogic::Session::Password - Authentication via a traditional username and password.
• Authlogic::Session::Persistence - Persisting sessions / finding sessions.
• Authlogic::Session::Session - Authentication via the session, the controller session that is.
• Authlogic::Session::Timeout - Automatically logging out after a certain period of inactivity.
• Authlogic::Session::UnauthorizedRecord - Handles authentication by passing an ActiveRecord object.
• Authlogic::Session::Validation - Validation / errors.

Miscellaneous modules

Miscellaneous modules that don’t really belong solely to either the session or model aspect.

• Authlogic::AuthenticatesMany - 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.
• Authlogic::CryptoProviders - Contains various encryption algorithms that Authlogic uses, allowing you to choose your encryption method.
• Authlogic::I18n - Acts JUST LIKE the rails I18n library, and provides internationalization to Authlogic.
• Authlogic::Random - A simple class to generate random tokens.
• Authlogic::TestCase - Various helper methods for testing frameworks to help you test your code.
• Authlogic::Version - 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)

  $ sudo gem install authlogic

Now add the gem dependency in your config:

  # config/environment.rb
  config.gem "authlogic"

Or you install this as a plugin (for older versions of rails)

  script/plugin install git://github.com/binarylogic/authlogic.git

Detailed Setup Tutorial

See the authlogic example 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.

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.

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. It’s cleaner. 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. Easier to stay up-to-date. To make my point, take a look at the commits to any other authentication solution, then look at the commits for authlogic. 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. It ties everything together on the domain level. 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. No redundant tests. 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. You are not restricted to a single session. 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. Easily extendable. One of the distinct advantages of using a library is the ability to use it’s 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 © 2009 Ben Johnson of Binary Logic, released under the MIT license