A clean, simple, and unobtrusive ruby authentication solution.
Tail Authlogic users in your logs!
| Version | branches | tag | ruby | activerecord |
|---|---|---|---|---|
| Unreleased | master, 4-stable | >= 2.2.0 | >= 4.2, < 5.3 | |
| 3 | 3-stable | v3.6.0 | >= 1.9.3 | >= 3.2, < 5.2 |
| 2 | rails2 | v2.1.11 | >= 1.9.3 | ~> 2.3.0 |
| 1 | ? | v1.4.3 | ? | ? |
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 our User model, which is inferred from the name:
class UserSession < Authlogic::Session::Base
# specify configuration here, such as:
# logout_on_timeout true
# ...many more options in the documentation
endIn a UserSessionsController, login the user by using it just like your other models:
UserSession.create(:login => "bjohnson", :password => "my password", :remember_me => true)
session = UserSession.new(:login => "bjohnson", :password => "my password", :remember_me => true)
session.save
# requires the authlogic-oid "add on" gem
UserSession.create(:openid_identifier => "identifier", :remember_me => true)
# skip authentication and log the user in directly, the true means "remember me"
UserSession.create(my_user_object, true)The above handles the entire authentication process for you by:
- authenticating (i.e. validating the record)
- sets up the proper session values and cookies to persist the session (i.e. saving the record).
You can also log out (i.e. destroying the session):
session.destroyAfter a session has been created, you can persist it (i.e. finding the record) across requests. Thus keeping the user logged in:
session = UserSession.findTo 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
endThis 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.
You may specify how passwords are cryptographically hashed (or encrypted) by setting the Authlogic::CryptoProvider option:
c.crypto_provider = Authlogic::CryptoProviders::BCryptYou may validate international email addresses by enabling the provided alternate regex:
c.validates_format_of_email_field_options = {:with => Authlogic::Regex.email_nonascii}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])You can switch this on and off with the following configuration:
class User < ActiveRecord::Base
acts_as_authentic do |c|
c.log_in_after_create = false
end # the configuration block is optional
endAuthlogic also updates the session when the user changes his/her password. You can also switch this on and off with the following configuration:
class User < ActiveRecord::Base
acts_as_authentic do |c|
c.log_in_after_password_change = false
end # the configuration block is optional
endAuthlogic 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.
This README is just an introduction, but we also have reference documentation.
To use the reference documentation, you must understand how Authlogic's code is organized. There are 2 models, your Authlogic model and your ActiveRecord model:
- Authlogic::Session, your session models that
extend
Authlogic::Session::Base. - Authlogic::ActsAsAuthentic, which adds in functionality to your
ActiveRecord model when you call
acts_as_authentic.
Each of the above has various modules that are organized by topic: passwords,
cookies, etc. For example, if you want to timeout users after a certain period
of inactivity, you would look in Authlogic::Session::Timeout.
Let's walk through a typical rails setup.
If you want to enable all the features of Authlogic, a migration to create a
User model might look like this:
class CreateUser < ActiveRecord::Migration
def change
create_table :users do |t|
# Authlogic::ActsAsAuthentic::Email
t.string :email
# Authlogic::ActsAsAuthentic::Password
t.string :crypted_password
t.string :password_salt
# Authlogic::ActsAsAuthentic::PersistenceToken
t.string :persistence_token
t.index :persistence_token, unique: true
# Authlogic::ActsAsAuthentic::SingleAccessToken
t.string :single_access_token
t.index :single_access_token, unique: true
# Authlogic::ActsAsAuthentic::PerishableToken
t.string :perishable_token
t.index :perishable_token, unique: true
# Authlogic::Session::MagicColumns
t.integer :login_count, default: 0, null: false
t.integer :failed_login_count, default: 0, null: false
t.datetime :last_request_at
t.datetime :current_login_at
t.datetime :last_login_at
t.string :current_login_ip
t.string :last_login_ip
# Authlogic::Session::MagicStates
t.boolean :active, default: false
t.boolean :approved, default: false
t.boolean :confirmed, default: false
t.timestamps
end
end
endYour sessions controller will look just like your other controllers.
class UserSessionsController < ApplicationController
def new
@user_session = UserSession.new
end
def create
@user_session = UserSession.new(user_session_params)
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
private
def user_session_params
params.require(:user_session).permit(:email, :password, :remember_me)
end
endAs you can see, this fits nicely into the conventional controller methods.
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<%= form_for @user_session do |f| %>
<% if @user_session.errors.any? %>
<div id="error_explanation">
<h2><%= pluralize(@user_session.errors.count, "error") %> prohibited:</h2>
<ul>
<% @user_session.errors.full_messages.each do |msg| %>
<li><%= msg %></li>
<% end %>
</ul>
</div>
<% end %>
<%= f.label :login %><br />
<%= f.text_field :login %><br />
<br />
<%= f.label :password %><br />
<%= f.password_field :password %><br />
<br />
<%= f.submit "Login" %>
<% end %>Because Authlogic introduces its own methods for storing user sessions, the CSRF (Cross Site Request Forgery) protection that is built into Rails will not work out of the box.
No generally applicable mitigation by the authlogic library is possible, because
the instance variable you use to store a reference to the user session in def current_user_session will not be known to authlogic.
You will need to override ActionController::Base#handle_unverified_request to
do something appropriate to how your app handles user sessions, e.g.:
class ApplicationController < ActionController::Base
...
protected
def handle_unverified_request
# raise an exception
fail ActionController::InvalidAuthenticityToken
# or destroy session, redirect
if current_user_session
current_user_session.destroy
end
redirect_to root_url
end
end- API Reference: http://www.rubydoc.info/github/binarylogic/authlogic
- Repository: https://github.com/binarylogic/authlogic/tree/master
- Railscasts Screencast: http://railscasts.com/episodes/160-authlogic
- Example repository with tutorial in README: https://github.com/binarylogic/authlogic_example/tree/master
- Tutorial: Rails Authentication with Authlogic https://www.sitepoint.com/rails-authentication-with-authlogic
- Issues: https://github.com/binarylogic/authlogic/issues
- Chrome is not logging out on browser close https://productforums.google.com/forum/#!topic/chrome/9l-gKYIUg50/discussion
- Authlogic OpenID addon: https://github.com/binarylogic/authlogic_openid
- Authlogic LDAP addon: https://github.com/binarylogic/authlogic_ldap
- Authlogic Facebook Connect: https://github.com/kalasjocke/authlogic-facebook-connect
- Authlogic Facebook Connect (New JS API): https://github.com/studybyte/authlogic_facebook_connect
- Authlogic Facebook Shim https://github.com/james2m/authlogic_facebook_shim
- Authlogic OAuth (Twitter): https://github.com/jrallison/authlogic_oauth
- Authlogic Oauth and OpenID: https://github.com/lancejpollard/authlogic-connect
- Authlogic PAM: https://github.com/nbudin/authlogic_pam
- Authlogic x509: https://github.com/auth-scc/authlogic_x509
If you create one of your own, please let us know about it so we can add it to this list. Or just fork the project, add your link, and send us a pull request.
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. Nothing crazy going on, Authlogic is just leveraging the tools your framework provides in the controller object.
Copyright (c) 2012 Ben Johnson of Binary Logic, released under the MIT license