🛡️ Rails::Auth

Rails::Auth is a high-performance, security-first authentication engine for Ruby on Rails. Designed as a modern, transparent alternative to Devise, it empowers users with deep visibility and control over their account security through database-backed sessions and enterprise-grade protection.

Gem Version License: MIT Rails Version

📖 Table of Contents

🚀 Key Features

🔐 Enterprise Security

  • JWT Authentication: Built-in support for stateless API authentication via Authorization: Bearer <token>.
  • Security Audit Logs: Comprehensive tracking of sensitive actions (login failures, MFA toggles, password changes).
  • Admin Impersonation: Securely log in as any user for customer support while tracking the original admin's actions.
  • Two-Factor Authentication (MFA): Modern TOTP support (Google Authenticator, Authy) with automated QR codes.
  • Account Locking (Lockable): Protection against brute-force attacks with email-based unlocking.
  • Email Confirmation (Confirmable): Ensure every user is verified before they can access your app.
  • Role-Based Access Control (RBAC): Built-in user, moderator, and admin roles with clean authorization helpers.

📱 Advanced Session Management

  • Database-Backed Sessions: Every device login is tracked, allowing for complete transparency.
  • Remote Device Revocation: Log out of lost or stolen devices remotely from the dashboard.
  • Global Sign-Out: Instant "Sign out of all devices" for emergency account security.
  • Device Intelligence: Automatically identifies Browser, OS, and IP Address for every session.

🛠️ Developer Experience

  • Active Storage Ready: Seamlessly integrated avatar/profile picture support.
  • Model Independent: Easily attach to User, Admin, Member, or any other model.
  • Minimalistic Core: Built on top of Rails' native has_secure_password.
  • Generator Driven: Scaffold everything you need in seconds.

📦 Installation

Add this line to your application's Gemfile:

gem "rails-auth-eassy"

Or install it directly via CLI:

$ gem install rails-auth-eassy

Then execute:

$ bundle install

🛠️ Getting Started

1. Run the Installer

Scaffold the configuration and engine routes:

$ rails g rails_auth:install

2. Generate Your Authentication Model

Create or update your user model (e.g., User):

$ rails g rails_auth:model User

This will generate:

  • The User & Session models.
  • Migrations for MFA, Lockable, Confirmable, and RBAC.

3. Run Migrations

$ rails db:migrate

📖 Usage

Base Controller Setup

Include the authentication concern in your ApplicationController:

class ApplicationController < ActionController::Base
  include Rails::Auth::AuthenticatableController
end

Controller Helpers

Helper Description
authenticate_user! Before action to ensure the user is logged in.
current_user Returns the currently authenticated user.
current_session Returns the database record for the current session.
user_signed_in? Check if a user is currently authenticated.
require_admin! Authorization helper to restrict access to admins.
authorize_role!(*roles) Restrict access to specific roles (e.g., :moderator, :admin).

Role-Based Access Control (RBAC)

class Admin::SettingsController < ApplicationController
  before_action :require_admin!

  def update
    # Only admins can reach here
  end
end

Avatar Support

Rails::Auth uses Active Storage for avatars. Once Active Storage is installed in your host app:

<% if current_user.avatar.attached? %>
  <%= image_tag current_user.avatar.variant(resize_to_limit: [50, 50]) %>
<% end %>

JWT API Authentication

Rails::Auth automatically supports JWTs for API endpoints.

  1. Send a POST to /auth/session.json with email/password.
  2. Receive a token: { "token": "eyJhb..." }.
  3. Use it in subsequent requests: Authorization: Bearer eyJhb...

Admin Impersonation

Admins can impersonate users for support purposes:

# Start Impersonation (Controller action)
sign_in(user, impersonated_by: current_user)

# Stop Impersonation
rails_auth.stop_impersonations_path, method: :delete

Note: Impersonation events are securely logged in the SecurityEvent table.

🔑 Core Authentication Flows

Once installed, the engine provides the following core routes for user authentication. You can link to these anywhere in your application layout (e.g., your navigation bar).

Sign Up (Registration)

To allow new users to create an account:

<%= link_to "Sign Up", rails_auth.new_registration_path %>

Note: If email confirmation is enabled, they will be sent a confirmation link before they can sign in.

Sign In (Login)

To allow existing users to log into their account:

<%= link_to "Sign In", rails_auth.new_session_path %>

Sign Out (Logout)

To securely log the user out and destroy their current session:

<%= button_to "Sign Out", rails_auth.session_path, method: :delete %>

(We use button_to with method: :delete for security best practices against CSRF).

Putting it together in a Navbar

<nav>
  <% if user_signed_in? %>
    <span>Welcome, <%= current_user.email %>!</span>
    <%= link_to "Security Settings", rails_auth.security_sessions_path %>
    <%= button_to "Sign Out", rails_auth.session_path, method: :delete %>
  <% else %>
    <%= link_to "Sign In", rails_auth.new_session_path %>
    <%= link_to "Sign Up", rails_auth.new_registration_path %>
  <% end %>
</nav>

🛡️ Security Dashboard

Users can manage their security settings, edit their profile/avatar, view active audit logs, and enable MFA at /auth/security/sessions.

Linking to the Dashboard

<%= link_to "Security Settings", rails_auth.security_sessions_path %>

📧 Mailer Setup

Rails::Auth sends emails for confirmation instructions, password resets, and account unlock instructions.

1. Set Default URL Options

In your environments (e.g., config/environments/development.rb), set the host for the mailer:

config.action_mailer.default_url_options = { host: "localhost", port: 3000 }

2. Configure the Sender & Tokens

In config/initializers/rails_auth.rb, you can customize the sender and confirmation tokens:

Rails::Auth.setup do |config|
  config.mailer_sender = "noreply@yourdomain.com"

  # Optional: Customize confirmation tokens
  # config.confirmation_token_format = :numeric # default is :hex
  # config.confirmation_token_length = 6        # default is 20
end

3. Development Tip

We recommend using letter_opener to preview emails in your browser instead of sending them.

# config/environments/development.rb
config.action_mailer.delivery_method = :letter_opener
config.action_mailer.perform_deliveries = true

⚙️ Configuration

Customize the gem behavior in config/initializers/rails_auth.rb:

Rails::Auth.setup do |config|
  config.user_class_name = "User"
  config.session_class_name = "Session"
end

🎨 Customization

Views

Override the default views by copying them to your application:

$ rails g rails_auth:views

Controllers

You can inherit from Rails::Auth::ApplicationController or include the AuthenticatableController in your own controllers for deep integration.

🧪 Testing

Rails::Auth is tested against modern Rails versions. Run the suite:

$ bundle exec rake test

👥 Authors & Maintainers

  • Shiboshree Roy - Lead Developer

📄 License

The gem is available as open source under the terms of the MIT License.

Built with ❤️ for the Rails Community by Shiboshree Roy.