🛡️ 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"

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.

🛡️ Security Dashboard

Users can manage their security settings, view active sessions, and enable MFA at /auth/security/sessions.

Linking to the Dashboard

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

⚙️ 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.