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.
• Start in your app’s development environment, then configure its deployed services before enabling sign-in for users.

1. Install from RubyGems

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

gem "add_auth", "0.2.0.dev"

The explicit version selects the documented prerelease. Bundler downloads the gem from RubyGems and records it in Gemfile.lock.

bundle install

2. Enable sign-in

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

bin/rails generate authentication

Then install AddAuth’s configuration and enable email links:

bin/rails generate add_auth:install
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.

3. 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.

4. 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.