Need help with authlogic?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

binarylogic
4.2K Stars 618 Forks MIT License 1.1K Commits 4 Opened issues

Description

A simple ruby authentication solution.

Services available

!
?

Need anything else?

Contributors list

No Data

Authlogic

An unobtrusive ruby authentication library based on ActiveRecord.

Gem Version Build Status Code Climate Dependency Status

Coverage Status

Sponsors

Timber Logging

Tail Authlogic users in your logs!

Documentation

| Version | Documentation | | ----------- | ------------- | | Unreleased | https://github.com/binarylogic/authlogic/blob/master/README.md | | 6.2.0 | https://github.com/binarylogic/authlogic/blob/v6.2.0/README.md | | 5.2.0 | https://github.com/binarylogic/authlogic/blob/v5.2.0/README.md | | 4.5.0 | https://github.com/binarylogic/authlogic/blob/v4.5.0/README.md | | 3.7.0 | https://github.com/binarylogic/authlogic/blob/v3.7.0/README.md | | 2.1.11 | https://github.com/binarylogic/authlogic/blob/v2.1.11/README.rdoc | | 1.4.3 | https://github.com/binarylogic/authlogic/blob/v1.4.3/README.rdoc |

Table of Contents

1. Introduction

1.a. Overview

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
end

In 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:

  1. authenticating (i.e. validating the record)
  2. 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.destroy

After a session has been created, you can persist it (i.e. finding the record) 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 < ApplicationRecord
  acts_as_authentic do |c|
    c.my_config_option = my_value
  end # the configuration block is optional
end

It is also "smart" in the sense that if a login or username field is present it will use that to authenticate, if not it will look for an email field. This is all configurable, but for 99% of cases the 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::BCrypt

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 < ApplicationRecord
  acts_as_authentic do |c|
    c.log_in_after_create = false
  end # the configuration block is optional
end

Authlogic 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 < ApplicationRecord
  acts_as_authentic do |c|
    c.log_in_after_password_change = false
  end # the configuration block is optional
end

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.

1.b. Reference Documentation

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:

  1. Authlogic::Session, your session models that extend
    Authlogic::Session::Base
    .
  2. Authlogic::ActsAsAuthentic, which adds in functionality to your ActiveRecord model when you call
    acts_as_authentic
    .

1.c. Installation

To install Authlogic, add this to your Gemfile:

gem 'authlogic'

And run

bundle install
.

2. Rails

Let's walk through a typical rails setup. (Compatibility)

2.a.1 The users table

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
      t.index     :email, unique: true

  # Authlogic::ActsAsAuthentic::Login
  t.string    :login

  # 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

  # See "Magic Columns" in Authlogic::Session::Base
  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

  # See "Magic States" in Authlogic::Session::Base
  t.boolean   :active, default: false
  t.boolean   :approved, default: false
  t.boolean   :confirmed, default: false

  t.timestamps
end

end end

In the

User
model,
class User < ApplicationRecord
  acts_as_authentic

Validate email, login, and password as you see fit.

#

Authlogic < 5 added these validation for you, making them a little awkward

to change. In 4.4.0, those automatic validations were deprecated. See

https://github.com/binarylogic/authlogic/blob/master/doc/use_normal_rails_validation.md

validates :email, format: { with: /@/, message: "should look like an email address." }, length: { maximum: 100 }, uniqueness: { case_sensitive: false, if: :will_save_change_to_email? }

validates :login, format: { with: /\A[a-z0-9]+\z/, message: "should use only letters and numbers." }, length: { within: 3..100 }, uniqueness: { case_sensitive: false, if: :will_save_change_to_login? }

validates :password, confirmation: { if: :require_password? }, length: { minimum: 8, if: :require_password? } validates :password_confirmation, length: { minimum: 8, if: :require_password? } end

2.a.2. UserSession model

And define a corresponding model in

app/models/user_session.rb
:
class UserSession < Authlogic::Session::Base
end

2.b. Controller

Your 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.to_h) if @user_session.save redirect_to root_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(:login, :password, :remember_me) end end

As you can see, this fits nicely into the conventional controller methods.

2.b.1. Helper Methods

class ApplicationController < ActionController::Base
  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 &amp;&amp; current_user_session.user
end

end

2.b.2. Routes

Rails.application.routes.draw do
  # ...
  resources :users
  resource :user_session
end

2.b.3. ActionController::API

Because ActionController::API does not include ActionController::Cookies metal and ActionDispatch::Cookies rack module, Therefore, our controller can not use the cookies method. - #684.

2.c. View

For example, in

app/views/user_sessions/new.html.erb
:
  

prohibited:

        <li>
    
    </ul>









2.d. CSRF Protection

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

2.e. SameSite Cookie Attribute

The SameSite attribute tells browsers when and how to fire cookies in first- or third-party situations. SameSite is used by a variety of browsers to identify whether or not to allow a cookie to be accessed.

Up until recently, the standard default value when SameSite was not explicitly defined was to allow cookies in both first- and third-party contexts. However, starting with Chrome 80+, the SameSite attribute will not default to Lax behavior meaning cookies will only be permitted in first-party contexts.

Authlogic can allow you to explicitly set the value of SameSite to one of: Lax, Strict, or None. Note that when setting SameSite to None, the

secure
flag must also be set (secure is the default in Authlogic).

Reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#SameSite

3. Testing

See Authlogic::TestCase

4. Helpful links

  • 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

5. Add-ons

  • 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/authlogicfacebookconnect
  • Authlogic Facebook Shim https://github.com/james2m/authlogicfacebookshim
  • 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.

6. Internals

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.

7. Extending

7.a. Extending UserSession

Your

UserSession
is designed to be extended with callbacks.

Example: Custom logging.

# user_session.rb
class UserSession < Authlogic::Session::Base
  after_persisting :my_custom_logging

private

def my_custom_logging Rails.logger.info( format( 'After authentication attempt, user id is %d', record.send(record.class.primary_key) ) ) end end

To learn more about available callbacks, see the "Callbacks" documentation in

authlogic/session/base.rb
.

90. Compatibility

| Version | branch | ruby | activerecord | | ------- | ------------ | -------- | ------------- | | 6.2 | 6-2-stable | >= 2.4.0 | >= 5.2, < 6.1 | | 5.2 | 5-2-stable | >= 2.3.0 | >= 5.2, < 6.1 | | 4.5 | 4-5-stable | >= 2.3.0 | >= 4.2, < 5.3 | | 4.3 | 4-3-stable | >= 2.3.0 | >= 4.2, < 5.3 | | 4.2 | 4-2-stable | >= 2.2.0 | >= 4.2, < 5.3 | | 3 | 3-stable | >= 1.9.3 | >= 3.2, < 5.3 | | 2 | rails2 | >= 1.9.3 | ~> 2.3.0 | | 1 | ? | ? | ? |

Under SemVer, changes to dependencies do not require a major release.

Intellectual Property

Copyright (c) 2012 Ben Johnson of Binary Logic, released under the MIT license

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.