What does this example app contain?

A my account area where the user can view / change details about their
account, including their password.

Automatically update the users session when they change their password.

Logout functionality.

Login functionality with a “remember me” option.

Secure password / token system, based on proven principals used in ruby /
rails for years.

Automatically store information on the users and their session in the
databases. Such as login count, IP address, when they logged in last, and
when their last activity occurred.

Count how many users are logged in / out in your system.

Tutorial on how to create this app and easily setup Authlogic

1. Install

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

2. Create your UserSession model

Authlogic introduces a new flavor of models that extends
Authlogic::Session::Base. The point of this model is to handle all of the
session details for you. Just like ActiveRecord handles all of the database
details. You can create, update, and delete sessions just like an
ActiveRecord model. It basically sits in between you and the cookies in the
same manner ActiveRecord sits in between you and the database. The best
part is that you use it the same way too.

So lets assume you are setting up a session for your User model. You can
call this anything you want, but I recommend naming it after the model you
are authenticating with, this way if you want to add multiple session
models down the road you can easily do this without have name clashes.

3. Ensure proper database fields

If you don't already have a User model, go ahead and create one:

script/generate model user

Since you are authenticating with your User model, it can have the
following columns. The names of these columns can be changed with
configuration. Better yet, Authlogic tries to guess these names by checking
for the existence of common names. If you checkout the
Authlogic::ActsAsAuthentic submodules in the documentation], it will show you
the various names checked, chances are you won't have to specify any
configuration for your field names, even if they aren't the same names
as below.

Credential fields are optional: Notice the login, email, and
crypted_password fields are optional. That's because Authlogic
doesn't care how you authenticate, you don't have to use your own
authentication method. If you prefer, you could use OpenID, LDAP, or
whatever you want and not even provide your own authentication system.
These authentication methods can EASILY be added by using an authlogic add
on (see Authlogic Addons above). I recommend providing your own as an
option though. Your interface, such as the registration form, can dictate
which method is the default.

What are all of the token fields? Instead of giving you a token for
each task (reset passwords, etc.), authlogic gives you the different kinds
of tokens that tasks need. They are your “keys” to do the following:

Persistence token: Used by Authlogic internally, it is stored in your
cookies and sessions to persist the user. This is much more secure than
plainly storing the user's id.

One thing to note here is that this tries to take care of all the
authentication grunt work, including validating your login, email,
password, and token fields. You can easily disable this with
configuration. Ex: c.validate_email_field = false. See the
Authlogic::ActsAsAuthentic sub modules in the documentation for more details.

5. Create a UserSessionsController

This is where users will log in and out. It is responsible for managing
their session. You create this controller JUST LIKE you do for any other
model. The actions are exactly the same as well:

That's it! You can name these methods anything you want. That's
what's great about Authlogic, it doesn't assume things for you, you
are in control of the application specific parts of authentication.

7. Restrict Access

This is application specific. You can do this however you wish. For an
example see
the ApplicationController in the authlogic example app. Notice the
require_user and require_no_user methods. They are enforced via
before_filters in the other controllers. Restricting access is as simple as
that. There are a million ways to do this, but this seems to be the most
common and the simplest.

8. Register users

Registering users is very simple. Since this is rails 101 I will make this
short and sweet.

Pretty straightforward. One thing to note here is that there is nothing
going on with the sessions.

So how does Authlogic log users in after registration? How does authlogic
know to update a user's session after they reset their password? This
is one of the great things about Authlogic, because the session logic is
tucked away down in the model level we can interact with other models. So
Authlogic automatically hooks into the related model (User) and does all of
this for you. As with all features in Authlogic, if you do not want to use
this, you can easily disable it. See
Authlogic::ActsAsAuthentic::SessionMaintenance in the documentation]
for more info.

9. Next Steps

Here are some common next steps. They might or might not apply to you. For
a complete list of everything Authlogic can do please read the documentation or see the sub
module list above.

Want to use another encryption algorithm, such as BCrypt? See
Authlogic::ActsAsAuthentic::Password::Config

Migrating from restful_authentication? See
Authlogic::ActsAsAuthentic::RestfulAuthentication::Config

Want to timeout sessions after a period if inactivity? See
Authlogic::Session::Timeout

Need to scope your sessions to an account or parent model? See
Authlogic::AuthenticatesMany

Need to reset passwords or activate accounts? Use the perishable token. See
Authlogic::ActsAsAuthentic::PerishableToken

Need to give API access or access to a private feed? Use basic HTTP auth or
authentication by params. See Authlogic::Session::HttpAuth or
Authlogic::Session::Params

Need to internationalize your app? See Authlogic::I18n

Need help testing? See the Authlogic::TestCase

I've yet to encounter a case that authlogic does not handle. If you
have a unique situation glance at the {documentation}(authlogic.rubyforge.org). I was
very thorough with it, and you can discover all kinds of cool things
Authlogic can do for you.

Improving this tutorial

If you find something confusing or encounter a problem with this tutorial
please fork this project, make the changes, and send me a pull request. I
would really appreciate this and so would successive Authlogic users.