{"id":13463334,"url":"https://github.com/binarylogic/authlogic","last_synced_at":"2025-05-13T15:03:00.818Z","repository":{"id":444984,"uuid":"67451","full_name":"binarylogic/authlogic","owner":"binarylogic","description":"A simple ruby authentication solution.","archived":false,"fork":false,"pushed_at":"2025-04-11T19:49:01.000Z","size":2451,"stargazers_count":4345,"open_issues_count":8,"forks_count":641,"subscribers_count":57,"default_branch":"master","last_synced_at":"2025-05-05T22:23:47.041Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://rdoc.info/projects/binarylogic/authlogic","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/binarylogic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2008-10-24T21:13:34.000Z","updated_at":"2025-05-05T11:13:07.000Z","dependencies_parsed_at":"2025-04-23T06:37:52.212Z","dependency_job_id":null,"html_url":"https://github.com/binarylogic/authlogic","commit_stats":{"total_commits":899,"total_committers":143,"mean_commits":6.286713286713287,"dds":0.6318131256952169,"last_synced_commit":"a48558507129b812474586d9f69e826011fc9cf6"},"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarylogic%2Fauthlogic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarylogic%2Fauthlogic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarylogic%2Fauthlogic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/binarylogic%2Fauthlogic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/binarylogic","download_url":"https://codeload.github.com/binarylogic/authlogic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253968246,"owners_count":21992253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:51.237Z","updated_at":"2025-05-13T15:03:00.758Z","avatar_url":"https://github.com/binarylogic.png","language":"Ruby","readme":"# Authlogic\n\nAn unobtrusive ruby authentication library based on ActiveRecord.\n\n[![Gem Version][5]][6] [![Build Status][1]][2] [![Code Climate][7]][8] [![Dependency Status][3]][4]\n\n[![Coverage Status](https://coveralls.io/repos/github/binarylogic/authlogic/badge.svg?branch=master)](https://coveralls.io/github/binarylogic/authlogic?branch=master)\n\n## Documentation\n\n| Version    | Documentation                                                     |\n| ---------- | ----------------------------------------------------------------- |\n| Unreleased | https://github.com/binarylogic/authlogic/blob/master/README.md    |\n| 6.5.0      | https://github.com/binarylogic/authlogic/blob/v6.5.0/README.md    |\n| 6.4.3      | https://github.com/binarylogic/authlogic/blob/v6.4.3/README.md    |\n| 5.2.0      | https://github.com/binarylogic/authlogic/blob/v5.2.0/README.md    |\n| 4.5.0      | https://github.com/binarylogic/authlogic/blob/v4.5.0/README.md    |\n| 3.7.0      | https://github.com/binarylogic/authlogic/blob/v3.7.0/README.md    |\n| 2.1.11     | https://github.com/binarylogic/authlogic/blob/v2.1.11/README.rdoc |\n| 1.4.3      | https://github.com/binarylogic/authlogic/blob/v1.4.3/README.rdoc  |\n\n## Table of Contents\n\n- [1. Introduction](#1-introduction)\n  - [1.a. Overview](#1a-overview)\n  - [1.b. Reference Documentation](#1b-reference-documentation)\n  - [1.c. Installation](#1c-installation)\n- [2. Rails](#2-rails)\n  - [2.a. The users table](#2a-the-users-table)\n  - [2.b. Controller](#2b-controller)\n    - [2.b.1. Helper Methods](#2b1-helper-methods)\n    - [2.b.2. Routes](#2b2-routes)\n    - [2.b.3. ActionController::API](#2b3-actioncontroller-api)\n  - [2.c. View](#2c-view)\n  - [2.d. CSRF Protection](#2d-csrf-protection)\n- [3. Testing](#3-testing)\n- [4. Helpful links](#4-helpful-links)\n- [5. Add-ons](#5-add-ons)\n- [6. Internals](#6-internals)\n- [7. Extending](#7-extending)\n- [90. Compatibility](#90-compatibility)\n\n## 1. Introduction\n\n### 1.a. Overview\n\nAuthlogic introduces a new type of model. You can have as many as you want, and\nname them whatever you want, just like your other models. In this example, we\nwant to authenticate with our `User` model, which is inferred from the name:\n\n```ruby\nclass UserSession \u003c Authlogic::Session::Base\n  # specify configuration here, such as:\n  # logout_on_timeout true\n  # ...many more options in the documentation\nend\n```\n\nIn a `UserSessionsController`, login the user by using it just like your other models:\n\n```ruby\nUserSession.create(:login =\u003e \"bjohnson\", :password =\u003e \"my password\", :remember_me =\u003e true)\n\nsession = UserSession.new(:login =\u003e \"bjohnson\", :password =\u003e \"my password\", :remember_me =\u003e true)\nsession.save\n\n# requires the authlogic-oid \"add on\" gem\nUserSession.create(:openid_identifier =\u003e \"identifier\", :remember_me =\u003e true)\n\n# skip authentication and log the user in directly, the true means \"remember me\"\nUserSession.create(my_user_object, true)\n```\n\nThe above handles the entire authentication process for you by:\n\n1. authenticating (i.e. **validating** the record)\n2. sets up the proper session values and cookies to persist the session (i.e. **saving** the record).\n\nYou can also log out (i.e. **destroying** the session):\n\n```ruby\nsession.destroy\n```\n\nAfter a session has been created, you can persist it (i.e. **finding** the\nrecord) across requests. Thus keeping the user logged in:\n\n```ruby\nsession = UserSession.find\n```\n\nTo get all of the nice authentication functionality in your model just do this:\n\n```ruby\nclass User \u003c ApplicationRecord\n  acts_as_authentic do |c|\n    c.my_config_option = my_value\n  end # the configuration block is optional\nend\n```\n\nIt is also \"smart\" in the sense that if a login or username field\nis present it will use that to authenticate, if not it will look for\nan email field. This is all configurable, but for 99% of cases the above\nis all you will need to do.\n\nYou may specify how passwords are cryptographically hashed (or encrypted) by\nsetting the Authlogic::CryptoProvider option:\n\n```ruby\nc.crypto_provider = Authlogic::CryptoProviders::BCrypt\n```\n\nAlso, sessions are automatically maintained. You can switch this on and off with\nconfiguration, but the following will automatically log a user in after a\nsuccessful registration:\n\n```ruby\nUser.create(params[:user])\n```\n\nYou can switch this on and off with the following configuration:\n\n```ruby\nclass User \u003c ApplicationRecord\n  acts_as_authentic do |c|\n    c.log_in_after_create = false\n  end # the configuration block is optional\nend\n```\n\nAuthlogic also updates the session when the user changes his/her password. You can also switch this on and off with the following configuration:\n\n```ruby\nclass User \u003c ApplicationRecord\n  acts_as_authentic do |c|\n    c.log_in_after_password_change = false\n  end # the configuration block is optional\nend\n```\n\nAuthlogic is very flexible, it has a strong public API and a plethora of hooks\nto allow you to modify behavior and extend it. Check out the helpful links below\nto dig deeper.\n\n### 1.b. Reference Documentation\n\nThis README is just an introduction, but we also have [reference\ndocumentation](http://www.rubydoc.info/github/binarylogic/authlogic).\n\n**To use the reference documentation, you must understand how Authlogic's\ncode is organized.** There are 2 models, your Authlogic model and your\nActiveRecord model:\n\n1. **Authlogic::Session**, your session models that\n   extend `Authlogic::Session::Base`.\n2. **Authlogic::ActsAsAuthentic**, which adds in functionality to your\n   ActiveRecord model when you call `acts_as_authentic`.\n\n### 1.c. Installation\n\nTo install Authlogic, add this to your Gemfile:\n\n`gem 'authlogic'`\n\nAnd run `bundle install`.\n\n## 2. Rails\n\nLet's walk through a typical rails setup. ([Compatibility](#90-compatibility))\n\n### 2.a.1 The users table\n\nIf you want to enable all the features of Authlogic, a migration to create a\n`User` model might look like this:\n\n```ruby\nclass CreateUser \u003c ActiveRecord::Migration\n  def change\n    create_table :users do |t|\n      # Authlogic::ActsAsAuthentic::Email\n      t.string    :email\n      t.index     :email, unique: true\n\n      # Authlogic::ActsAsAuthentic::Login\n      t.string    :login\n\n      # Authlogic::ActsAsAuthentic::Password\n      t.string    :crypted_password\n      t.string    :password_salt\n\n      # Authlogic::ActsAsAuthentic::PersistenceToken\n      t.string    :persistence_token\n      t.index     :persistence_token, unique: true\n\n      # Authlogic::ActsAsAuthentic::SingleAccessToken\n      t.string    :single_access_token\n      t.index     :single_access_token, unique: true\n\n      # Authlogic::ActsAsAuthentic::PerishableToken\n      t.string    :perishable_token\n      t.index     :perishable_token, unique: true\n\n      # See \"Magic Columns\" in Authlogic::Session::Base\n      t.integer   :login_count, default: 0, null: false\n      t.integer   :failed_login_count, default: 0, null: false\n      t.datetime  :last_request_at\n      t.datetime  :current_login_at\n      t.datetime  :last_login_at\n      t.string    :current_login_ip\n      t.string    :last_login_ip\n\n      # See \"Magic States\" in Authlogic::Session::Base\n      t.boolean   :active, default: false\n      t.boolean   :approved, default: false\n      t.boolean   :confirmed, default: false\n\n      t.timestamps\n    end\n  end\nend\n```\n\nIn the `User` model,\n\n```ruby\nclass User \u003c ApplicationRecord\n  acts_as_authentic\n\n  # Validate email, login, and password as you see fit.\n  #\n  # Authlogic \u003c 5 added these validation for you, making them a little awkward\n  # to change. In 4.4.0, those automatic validations were deprecated. See\n  # https://github.com/binarylogic/authlogic/blob/master/doc/use_normal_rails_validation.md\n  validates :email,\n    format: {\n      with: /@/,\n      message: \"should look like an email address.\"\n    },\n    length: { maximum: 100 },\n    uniqueness: {\n      case_sensitive: false,\n      if: :will_save_change_to_email?\n    }\n\n  validates :login,\n    format: {\n      with: /\\A[a-z0-9]+\\z/,\n      message: \"should use only letters and numbers.\"\n    },\n    length: { within: 3..100 },\n    uniqueness: {\n      case_sensitive: false,\n      if: :will_save_change_to_login?\n    }\n\n  validates :password,\n    confirmation: { if: :require_password? },\n    length: {\n      minimum: 8,\n      if: :require_password?\n    }\n  validates :password_confirmation,\n    length: {\n      minimum: 8,\n      if: :require_password?\n  }\nend\n```\n\n### 2.a.2. UserSession model\n\nAnd define a corresponding model in `app/models/user_session.rb`:\n\n```ruby\nclass UserSession \u003c Authlogic::Session::Base\nend\n```\n\n### 2.b. Controller\n\nYour sessions controller will look just like your other controllers.\n\n```ruby\nclass UserSessionsController \u003c ApplicationController\n  def new\n    @user_session = UserSession.new\n  end\n\n  def create\n    @user_session = UserSession.new(user_session_params.to_h)\n    if @user_session.save\n      redirect_to root_url\n    else\n      render :new, status: 422\n    end\n  end\n\n  def destroy\n    current_user_session.destroy\n    redirect_to new_user_session_url\n  end\n\n  private\n\n  def user_session_params\n    params.require(:user_session).permit(:login, :password, :remember_me)\n  end\nend\n```\n\nAs you can see, this fits nicely into the [conventional controller methods][9].\n\n#### 2.b.1. Helper Methods\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  helper_method :current_user_session, :current_user\n\n  private\n    def current_user_session\n      return @current_user_session if defined?(@current_user_session)\n      @current_user_session = UserSession.find\n    end\n\n    def current_user\n      return @current_user if defined?(@current_user)\n      @current_user = current_user_session \u0026\u0026 current_user_session.user\n    end\nend\n```\n\n#### 2.b.2. Routes\n\n```ruby\nRails.application.routes.draw do\n  # ...\n  resources :users\n  resource :user_session\nend\n```\n\n#### 2.b.3. ActionController::API\n\n\u003e Because ActionController::API does not include ActionController::Cookies\n\u003e metal and ActionDispatch::Cookies rack module, Therefore, our controller can\n\u003e not use the cookies method.\n\u003e\n\u003e - [#684](https://github.com/binarylogic/authlogic/pull/684).\n\n### 2.c. View\n\nFor example, in `app/views/user_sessions/new.html.erb`:\n\n```erb\n\u003c%= form_for @user_session, url: user_session_url do |f| %\u003e\n  \u003c% if @user_session.errors.any? %\u003e\n  \u003cdiv id=\"error_explanation\"\u003e\n    \u003ch2\u003e\u003c%= pluralize(@user_session.errors.count, \"error\") %\u003e prohibited:\u003c/h2\u003e\n    \u003cul\u003e\n      \u003c% @user_session.errors.full_messages.each do |msg| %\u003e\n        \u003cli\u003e\u003c%= msg %\u003e\u003c/li\u003e\n      \u003c% end %\u003e\n    \u003c/ul\u003e\n  \u003c/div\u003e\n  \u003c% end %\u003e\n  \u003c%= f.label :login %\u003e\u003cbr /\u003e\n  \u003c%= f.text_field :login %\u003e\u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003c%= f.label :password %\u003e\u003cbr /\u003e\n  \u003c%= f.password_field :password %\u003e\u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003c%= f.label :remember_me %\u003e\u003cbr /\u003e\n  \u003c%= f.check_box :remember_me %\u003e\u003cbr /\u003e\n  \u003cbr /\u003e\n  \u003c%= f.submit \"Login\" %\u003e\n\u003c% end %\u003e\n```\n\n### 2.d. CSRF Protection\n\nBecause Authlogic introduces its own methods for storing user sessions, the CSRF\n(Cross Site Request Forgery) protection that is built into Rails will not work\nout of the box.\n\nNo generally applicable mitigation by the authlogic library is possible, because\nthe instance variable you use to store a reference to the user session in `def\ncurrent_user_session` will not be known to authlogic.\n\nYou will need to override `ActionController::Base#handle_unverified_request` to\ndo something appropriate to how your app handles user sessions, e.g.:\n\n```ruby\nclass ApplicationController \u003c ActionController::Base\n  ...\n  protected\n\n  def handle_unverified_request\n    # raise an exception\n    fail ActionController::InvalidAuthenticityToken\n    # or destroy session, redirect\n    if current_user_session\n      current_user_session.destroy\n    end\n    redirect_to root_url\n  end\nend\n```\n\n### 2.e. SameSite Cookie Attribute\n\nThe 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.\n\nUp 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.\n\nAuthlogic 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).\n\nReference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#SameSite\n\n## 3. Testing\n\nSee [Authlogic::TestCase](https://github.com/binarylogic/authlogic/blob/master/lib/authlogic/test_case.rb)\n\n## 4. Helpful links\n\n- \u003cb\u003eAPI Reference:\u003c/b\u003e http://www.rubydoc.info/github/binarylogic/authlogic\n- \u003cb\u003eRepository:\u003c/b\u003e https://github.com/binarylogic/authlogic/tree/master\n- \u003cb\u003eRailscasts Screencast:\u003c/b\u003e http://railscasts.com/episodes/160-authlogic\n- \u003cb\u003eExample repository with tutorial in README:\u003c/b\u003e https://github.com/binarylogic/authlogic_example/tree/master\n- \u003cb\u003eTutorial\u003c/b\u003e: Rails Authentication with Authlogic https://www.sitepoint.com/rails-authentication-with-authlogic\n- \u003cb\u003eIssues:\u003c/b\u003e https://github.com/binarylogic/authlogic/issues\n- \u003cb\u003eChrome is not logging out on browser close\u003c/b\u003e https://productforums.google.com/forum/#!topic/chrome/9l-gKYIUg50/discussion\n\n## 5. Add-ons\n\n- \u003cb\u003eAuthlogic OpenID addon:\u003c/b\u003e https://github.com/binarylogic/authlogic_openid\n- \u003cb\u003eAuthlogic LDAP addon:\u003c/b\u003e https://github.com/binarylogic/authlogic_ldap\n- \u003cb\u003eAuthlogic Facebook Connect:\u003c/b\u003e https://github.com/kalasjocke/authlogic-facebook-connect\n- \u003cb\u003eAuthlogic Facebook Connect (New JS API):\u003c/b\u003e https://github.com/studybyte/authlogic_facebook_connect\n- \u003cb\u003eAuthlogic Facebook Shim\u003c/b\u003e https://github.com/james2m/authlogic_facebook_shim\n- \u003cb\u003eAuthlogic OAuth (Twitter):\u003c/b\u003e https://github.com/jrallison/authlogic_oauth\n- \u003cb\u003eAuthlogic Oauth and OpenID:\u003c/b\u003e https://github.com/lancejpollard/authlogic-connect\n- \u003cb\u003eAuthlogic PAM:\u003c/b\u003e https://github.com/nbudin/authlogic_pam\n- \u003cb\u003eAuthlogic x509:\u003c/b\u003e https://github.com/auth-scc/authlogic_x509\n\nIf you create one of your own, please let us know about it so we can add it to\nthis list. Or just fork the project, add your link, and send us a pull request.\n\n## 6. Internals\n\nInterested in how all of this all works? Think about an ActiveRecord model. A\ndatabase connection must be established before you can use it. In the case of\nAuthlogic, a controller connection must be established before you can use it. It\nuses that controller connection to modify cookies, the current session, login\nwith HTTP basic, etc. It connects to the controller through a before filter that\nis automatically set in your controller which lets Authlogic know about the\ncurrent controller object. Then Authlogic leverages that to do everything, it's\na pretty simple design. Nothing crazy going on, Authlogic is just leveraging the\ntools your framework provides in the controller object.\n\n## 7. Extending\n\n## 7.a. Extending UserSession\n\nYour `UserSession` is designed to be extended with callbacks.\n\nExample: Custom logging.\n\n```\n# user_session.rb\nclass UserSession \u003c Authlogic::Session::Base\n  after_persisting :my_custom_logging\n\n  private\n\n  def my_custom_logging\n    Rails.logger.info(\n      format(\n        'After authentication attempt, user id is %d',\n        record.send(record.class.primary_key)\n      )\n    )\n  end\nend\n```\n\nTo learn more about available callbacks, see the \"Callbacks\" documentation\nin `authlogic/session/base.rb`.\n\n## 90. Compatibility\n\n| Version | branch     | ruby     | activerecord  |\n| ------- | ---------- | -------- | ------------- |\n| 6.5.0   | 6-5-stable | \u003e= 2.4.0 | \u003e= 5.2, \u003c 8.0 |\n| 6.4.3   | 6-4-stable | \u003e= 2.4.0 | \u003e= 5.2, \u003c 7.1 |\n| 5.2     | 5-2-stable | \u003e= 2.3.0 | \u003e= 5.2, \u003c 6.1 |\n| 4.5     | 4-5-stable | \u003e= 2.3.0 | \u003e= 4.2, \u003c 5.3 |\n| 4.3     | 4-3-stable | \u003e= 2.3.0 | \u003e= 4.2, \u003c 5.3 |\n| 4.2     | 4-2-stable | \u003e= 2.2.0 | \u003e= 4.2, \u003c 5.3 |\n| 3       | 3-stable   | \u003e= 1.9.3 | \u003e= 3.2, \u003c 5.3 |\n| 2       | rails2     | \u003e= 1.9.3 | ~\u003e 2.3.0      |\n| 1       | ?          | ?        | ?             |\n\nUnder SemVer, [changes to dependencies][10] do not require a major release.\n\n## Intellectual Property\n\nCopyright (c) 2012 Ben Johnson of Binary Logic, released under the MIT license\n\n[1]: https://api.travis-ci.org/binarylogic/authlogic.svg?branch=master\n[2]: https://travis-ci.org/binarylogic/authlogic\n[3]: https://gemnasium.com/badges/github.com/binarylogic/authlogic.svg\n[4]: https://gemnasium.com/binarylogic/authlogic\n[5]: https://badge.fury.io/rb/authlogic.svg\n[6]: http://badge.fury.io/rb/authlogic\n[7]: https://codeclimate.com/github/binarylogic/authlogic.svg\n[8]: https://codeclimate.com/github/binarylogic/authlogic\n[9]: http://guides.rubyonrails.org/routing.html#resource-routing-the-rails-default\n[10]: https://semver.org/spec/v2.0.0.html#what-should-i-do-if-i-update-my-own-dependencies-without-changing-the-public-api\n","funding_links":[],"categories":["Authentication and OAuth","Security","Authentication","Ruby","Gems","`Authentication Development`"],"sub_categories":["Rails Authentication","\u003ca name=\"authN-ruby\"\u003e\u003c/a\u003eRuby","Authentication","Authentication and OAuth"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarylogic%2Fauthlogic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinarylogic%2Fauthlogic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinarylogic%2Fauthlogic/lists"}