rodauth-rails

The rails feature is the core integration layer that connects Rodauth to the Rails ecosystem. It provides the following capabilities:

• Template Rendering: Uses Action View for rendering templates.
• CSRF Protection: Uses Action Dispatch for authenticity token verification.
• Lifecycle Hooks: Runs Action Controller callbacks and rescue_from blocks around Rodauth requests.
• Emailing: Uses Action Mailer to create and deliver emails.
• Instrumentation: Provides Action Controller instrumentation around Rodauth requests.
• URL Generation: Uses Action Mailer's default URL options when calling Rodauth outside of a request context.

To modify default email templates and deliver them via background jobs, use the rodauth:mailer generator. This creates a RodauthMailer and provides the necessary configuration blocks to be added to your Rodauth auth class.

Important: For email links to work, ensure config.action_mailer.default_url_options is configured in your environment files.

By default, the generated configuration uses #deliver_later (Active Job). To deliver emails synchronously, change these calls to #deliver_now.

$ rails generate rodauth:mailer

The rodauth:install generator supports several flags to customize your initial setup:

• Custom table name: Specify a different table for accounts (defaults to accounts).
• JSON API: Enable endpoints for JSON-based authentication. Use --json for cookie-based authentication or --jwt for token-based authentication.
• Argon2: Use Argon2 for password hashing instead of the default bcrypt.

Example commands:

# Use 'users' table instead of 'accounts'
rails generate rodauth:install users

# Enable JWT-based JSON API
rails generate rodauth:install --jwt

# Use Argon2 hashing
rails generate rodauth:install --argon2

$ rails generate rodauth:install users
$ rails generate rodauth:install --json
$ rails generate rodauth:install --jwt
$ rails generate rodauth:install --argon2

By default, the rodauth-rails railtie inserts Rodauth::Rails::Middleware at the end of the middleware stack. If you need to insert it earlier (for example, to ensure certain middleware runs before Rodauth), you must disable auto-insertion and manually add it to the stack.

Note: If you use middleware like Rack::Attack to throttle signups, ensure it is placed above Rodauth in your Gemfile so its middleware is inserted first.

# config/initializers/rodauth.rb
Rodauth::Rails.configure do |config|
  config.middleware = false # disable auto-insertion
end

Rails.configuration.middleware.insert_before AnotherMiddleware, Rodauth::Rails::Middleware

Rodauth comes with built-in templates (using Bootstrap markup). To customize them, run the rodauth:views generator to copy them into app/views/rodauth.

Options for the generator:

• --css=tailwind: Generate views with Tailwind markup (requires @tailwindcss/forms).
• --all: Generate views for all enabled features.
• --name <name>: Specify a different Rodauth configuration name.
• Feature selection: Pass specific feature names to generate only those views.

Example commands:

# Generate all views
rails generate rodauth:views --all

# Generate specific features with Tailwind
rails generate rodauth:views login create_account --css=tailwind

# Generate views for a specific configuration named 'admin'
rails generate rodauth:views webauthn two_factor_base --name admin

$ rails generate rodauth:views --all

For system and integration tests, authentication is exercised via standard HTTP requests to Rodauth endpoints. You can implement helper methods in your ActionDispatch::IntegrationTest to simplify login and logout flows.

# test/controllers/articles_controller_test.rb
class ArticlesControllerTest < ActionDispatch::IntegrationTest
  def login(email, password)
    post "/login", params: { email: email, password: password }
    assert_redirected_to "/"
  end

  def logout
    post "/logout"
  end

  test "required authentication"
  do
    get :index
    assert_response 302
    assert_redirected_to "/login"

    account = Account.create!(email: "user@example.com", status: "verified")
    login(account.email, "secret123")

    get :index
    assert_response 200
  end
end

To install rodauth-rails, add the gem to your project and run the install generator. The generator creates a Rodauth app, configuration, and necessary database migrations.

1. Add the gem:

   bundle add rodauth-rails

2. Run the generator:

   rails generate rodauth:install

3. Run migrations:

   rails db:migrate

$ bundle add rodauth-rails
$ rails generate rodauth:install
$ rails db:migrate

If you want to use Rodauth as a library via internal_request without letting it handle routing via middleware, use Rodauth::Rails.lib.

Note: You should set require: false for the rodauth-rails gem in your Gemfile to prevent the middleware from being inserted automatically during boot.

# Gemfile
gem "rodauth-rails", require: false

# app/misc/rodauth_main.rb
require "rodauth/rails"
require "sequel/core"

RodauthMain = Rodauth::Rails.lib do
  enable :create_account, :login, :close_account
  db Sequel.postgres(extensions: :activerecord_connection, keep_reference: false)
end

# Usage
RodauthMain.create_account(login: "email@example.com", password: "secret123")

Rodauth uses the Tilt gem to render built-in view and email templates. If you have already imported all necessary templates into your application and want to remove Tilt as a dependency, you can disable it in the configuration.

# config/initializers/rodauth.rb
Rodauth::Rails.configure do |config|
  config.tilt = false # skip loading Tilt gem
end