Quickstart

Install AddAuth from RubyGems, enable password and email-link sign-in, and sign in to your Rails app.

Before you start

• Use Ruby 3.3+ and a Rails 8.0+ app with Active Record. Run every command below from your Rails app’s root directory.
• Have an account in your app that can sign in. AddAuth uses Rails’ User and Session models; your app supplies account creation or enables optional account lifecycle.
• Start in your app’s development environment, then configure its deployed services before enabling sign-in for users.

For an existing Devise app, start with Migrating from Devise. Do not run the Rails authentication generator over its populated models and custom controllers.

1. Install from RubyGems

Keep source "https://rubygems.org" in your app’s Gemfile and add:

gem "add_auth", "~> 0.5.1"

This selects the published 0.5.1 release line. Bundler downloads the gem from RubyGems and records it in Gemfile.lock.

bundle install

2. Create your configuration file

If your app does not already have Rails’ authentication files, generate them first:

bin/rails generate authentication

Run AddAuth’s setup command:

bin/rails generate add_auth:install

Open config/initializers/add_auth.rb. This is where you configure AddAuth in your Rails app. The command checks the Rails authentication files, creates the initializer if absent and runs doctor. It adds no migrations or routes and enables no optional features. Running it again preserves your existing initializer.

3. Enable sign-in

For this quickstart, enable password and email-link sign-in:

bin/rails generate add_auth:email_link
bin/rails db:migrate

The email-link generator adds password and email sign-in at /sign-in and session management at /sessions. Review generated migrations before applying them. See what each generator changes.

For password sign-in and sessions only, use bin/rails generate add_auth:session_upgrade instead, then migrate and follow session setup. Add other capabilities from the feature-enablement guide. Changing an enabled setting alone does not install its schema or routes.

4. Configure your app

Add these values inside AddAuth.configure in config/initializers/add_auth.rb:

config.base_url = "http://localhost:3000"
config.mail_from = "AddAuth <sign-in@example.test>"
config.rate_limit_store = ActiveSupport::Cache::MemoryStore.new

For development, write emails to a file so you can open the first sign-in link without setting up a mail provider. Add these settings inside the existing block in config/environments/development.rb:

config.active_job.queue_adapter = :inline
config.action_mailer.delivery_method = :file
config.action_mailer.file_settings = {location: Rails.root.join("tmp/mail")}
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true

The in-memory cache, inline jobs and file delivery are development settings. For deployment, configure a shared cache, durable jobs and your mail provider using the deployment checklist.

Save the initializer, restart any running Rails server and run:

bin/rails add_auth:doctor

Resolve the reported configuration findings. Use the configuration reference for defaults, required values and optional features.

5. Sign in

1. Start bin/rails server and open http://localhost:3000/sign-in.
2. Sign in with an existing account’s password, or request an email link for that account.
3. For email sign-in, open the message in tmp/mail, follow its link, and submit the confirmation form.

If you do not have an account yet, create one through your app’s account flow or Rails console. Rails’ generated User accepts email_address, password and password_confirmation.

Your first session

Open /sessions. Your browser now has an active session, and the page lets you review and end sign-ins. A used email link cannot sign you in again; request a new link after signing out.

If no message appears, follow the missing-email checks. Development mail files contain sign-in links; delete them when you finish.

Next, configure email-link behavior, style the sign-in pages, or prepare your deployment.