Authlounge

Based on Authlogic is a clean, simple, and unobtrusive ruby authentication solution to use with couchdb.

Requirements

Rails >= 2.3.2

peterpunk-couchrest it has some improvements like uniqueness validator.

How different is from authlogic?

No autenticates_many No scopes Couchdb ready ;-)

User model example:

  class User < CouchRest::ExtendedDocument
    include CouchRest::Validation
    include CouchRest::Callbacks

    use_database SERVER.default_database

    property :login                   # optional, you can use email instead, or both
    property :email                   # optional, you can use login instead, or both
    property :crypted_password        # optional, see below
    property :password_salt           # optional, but highly recommended
    property :persistence_token       # required
    property :single_access_token     # optional, see Authlogic::Session::Params
    property :perishable_token        # optional, see Authlogic::Session::Perishability

    # Magic columns, just like ActiveRecord's created_at and updated_at. These are automatically maintained by Authlogic if they are present.
    property :login_count, :type => Integer           # optional, see Authlogic::Session::MagicColumns
    property :failed_login_count, :type => Integer    # optional, see Authlogic::Session::MagicColumns
    property :last_request_at, :cast_as => 'Time'       # optional, see Authlogic::Session::MagicColumns
    property :current_login_at, :cast_as => 'Time'      # optional, see Authlogic::Session::MagicColumns
    property :last_login_at, :cast_as => 'Time'         # optional, see Authlogic::Session::MagicColumns
    property :current_login_ip       # optional, see Authlogic::Session::MagicColumns
    property :last_login_ip        # optional, see Authlogic::Session::MagicColumns

    timestamps!

    def self.default_timezone
      :utc
    end

    acts_as_authentic

  end

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 => "peterpunk", :password => "my password", :remember_me => true)
  session = UserSession.new(:login => "peterpunk", :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

• Documentation: authlogic.rubyforge.org
• Repository: github.com/binarylogic/authlogic/tree/master
• Railscasts Screencast: railscasts.com/episodes/160-authlogic
• Live example with OpenID "add on": authlogicexample.binarylogic.com
• Live example repository with tutorial in README: 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 directly, 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. Thank you.

Authlogic "add ons"

• Authlogic OpenID addon: github.com/binarylogic/authlogic_openid
• Authlogic LDAP addon: github.com/binarylogic/authlogic_ldap
• Authlogic Facebook Connect: github.com/kalasjocke/authlogic_facebook_connect

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, all that you need to do is understand the basic design behind it, but remember, there’s no active record here!.

1. Authlogic::Session, your session models that extend Authlogic::Session::Base.
2. Authlogic::ActsAsAuthentic, which adds in functionality to your Couchdb::ExtendedDocument 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 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 ActiveRecord side of things, the models that call acts_as_authentic.

• 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, last_request_at, 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 automatic session maintenance. EX: a new user registers, automatically log them in. Or a user changes their password, update their session.
• Authlogic::ActsAsAuthentic::SingleAccessToken - Handles maintaining the single access token.
• Authlogic::ActsAsAuthentic::ValidationsScope - 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.

• 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 directly.
• Authlogic::Session::Validation - Validation / errors.

Miscellaneous modules

Miscellaneous modules that shared across the authentication process and are more "utility" modules and classes.

• 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::Regex - Contains regular expressions used in Authlogic. Such as those to validate the format of the log or email.
• 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)

  Not released as gem yet
  You have to install as plugin for now

  script/plugin install git://github.com/peterpunk/authlounge.git

Install couchrest

Now add the gem dependency in your config:

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

Detailed Setup Tutorial

To do

Testing

I think one of the best aspects of Authlogic is testing. For one, it cuts out a lot 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.

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. It should answer any questions you have in regards to testing Authlogic.

Copyright © 2009 Pedro Visintin, released under the MIT license Based on

Copyright © 2009 Ben Johnson of Binary Logic, released under the MIT license