rodauth-rails 0.18.0 → 1.2.0

data/README.md

@@ -8,12 +8,15 @@ Useful links:
 
 * [Rodauth documentation](http://rodauth.jeremyevans.net/documentation.html)
 * [Rails demo](https://github.com/janko/rodauth-demo-rails)
+* [JSON API guide](https://github.com/janko/rodauth-rails/wiki/JSON-API)
+* [OmniAuth guide](https://github.com/janko/rodauth-rails/wiki/OmniAuth)
+* [Testing guide](https://github.com/janko/rodauth-rails/wiki/Testing)
 
 Articles:
 
 * [Rodauth: A Refreshing Authentication Solution for Ruby](https://janko.io/rodauth-a-refreshing-authentication-solution-for-ruby/)
-* [Adding Authentication in Rails with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
-* [Adding Multifactor Authentication in Rails with Rodauth](https://janko.io/adding-multifactor-authentication-in-rails-with-rodauth/)
+* [Rails Authentication with Rodauth](https://janko.io/adding-authentication-in-rails-with-rodauth/)
+* [Multifactor Authentication in Rails with Rodauth](https://janko.io/adding-multifactor-authentication-in-rails-with-rodauth/)
 * [How to build an OIDC provider using rodauth-oauth on Rails](https://honeyryderchuck.gitlab.io/httpx/2021/03/15/oidc-provider-on-rails-using-rodauth-oauth.html)
 
 ## Why Rodauth?
@@ -39,17 +42,12 @@ Active Record. There are good reasons for this, and to make Rodauth work
 smoothly alongside Active Record, rodauth-rails configures Sequel to [reuse
 Active Record's database connection][sequel-activerecord_connection].
 
-## Upgrading
-
-For instructions on upgrading from previous rodauth-rails versions, see
-[UPGRADING.md](/UPGRADING.md).
-
 ## Installation
 
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.18"
+gem "rodauth-rails", "~> 1.0"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -74,9 +72,9 @@ $ rails generate rodauth:install --jwt # token authentication via the "Authoriza
 $ bundle add jwt
 ```
 
-This generator will create a Rodauth app with common authentication features
-enabled, a database migration with tables required by those features, a mailer
-with default templates, and a few other files.
+This generator will create a Rodauth app and configuration with common
+authentication features enabled, a database migration with tables required by
+those features, a mailer with default templates, and a few other files.
 
 Feel free to remove any features you don't need, along with their corresponding
 tables. Afterwards, run the migration:
@@ -85,11 +83,23 @@ tables. Afterwards, run the migration:
 $ rails db:migrate
 ```
 
+For your mailer to be able to generate email links, you'll need to set up
+default URL options in each environment. Here is a possible configuration for
+`config/environments/development.rb`:
+
+```rb
+config.action_mailer.default_url_options = { host: 'localhost', port: 3000 }
+```
+
 ## Usage
 
 ### Routes
 
-You can see the list of routes our Rodauth middleware handles:
+Because requests to Rodauth endpoints are handled by a Rack middleware (and not
+a Rails controller), Rodauth routes will not show in `rails routes`.
+
+Use the `rodauth:routes` rake task to view the list of endpoints based on
+currently loaded features:
 
 ```sh
 $ rails rodauth:routes
@@ -127,32 +137,17 @@ These routes are fully functional, feel free to visit them and interact with the
 pages. The templates that ship with Rodauth aim to provide a complete
 authentication experience, and the forms use [Bootstrap] markup.
 
-Inside Rodauth configuration and the `route` block you can access Rails route
-helpers through `#rails_routes`:
-
-```rb
-class RodauthApp < Rodauth::Rails::App
-  configure do
-    # ...
-    login_redirect { rails_routes.activity_path }
-    # ...
-  end
-end
-```
-
 ### Current account
 
 The `#current_account` method is defined in controllers and views, which
-returns the model instance of the currently logged in account.
+returns the model instance of the currently logged in account. If the account
+doesn't exist in the database, the session will be cleared.
 
 ```rb
 current_account #=> #<Account id=123 email="user@example.com">
 current_account.email #=> "user@example.com"
 ```
 
-If the account doesn't exist in the database, the session will be cleared and
-login required.
-
 Pass the configuration name to retrieve accounts belonging to other Rodauth
 configurations:
 
@@ -160,13 +155,17 @@ configurations:
 current_account(:admin)
 ```
 
+This just delegates to the `#rails_account` method on the Rodauth object.
+
+#### Custom account model
+
 The `#current_account` method will try to infer the account model class from
 the configured table name. If that fails, you can set the account model
 manually:
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
     # ...
     rails_account_model Authentication::Account # custom model name
@@ -182,7 +181,7 @@ in your Rodauth app's routing block, which helps keep the authentication logic
 encapsulated:
 
 ```rb
-# app/lib/rodauth_app.rb
+# app/misc/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
   # ...
   route do |r|
@@ -249,6 +248,18 @@ Rails.application.routes.draw do
 end
 ```
 
+The current account can be retrieved via the `#rails_account` method:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  # require user to be admin
+  constraints Rodauth::Rails.authenticated { |rodauth| rodauth.rails_account.admin? } do
+    # ...
+  end
+end
+```
+
 You can specify the Rodauth configuration by passing the configuration name:
 
 ```rb
@@ -305,12 +316,33 @@ Use `--name` to generate views for a different Rodauth configuration:
 $ rails generate rodauth:views webauthn --name admin
 ```
 
+#### Page titles
+
+The generated view templates use `content_for(:title)` to store Rodauth's page
+titles, which you can then retrieve in your layout template to set the page
+title:
+
+```erb
+<!-- app/views/layouts/application.html.erb -->
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) %></title>
+    <!-- ... -->
+  </head>
+  <body>
+    <!-- ... -->
+  </body>
+</html>
+```
+
 #### Layout
 
 To use different layouts for different Rodauth views, you can compare the
 request path in the layout method:
 
 ```rb
+# app/controllers/rodauth_controller.rb
 class RodauthController < ApplicationController
   layout :rodauth_layout
 
@@ -331,6 +363,15 @@ class RodauthController < ApplicationController
 end
 ```
 
+#### Turbo
+
+[Turbo] has been disabled by default on all built-in and generated view
+templates, because some Rodauth actions (multi-phase login, adding recovery
+codes) aren't Turbo-compatible, as they return 200 responses on POST requests.
+
+That being said, most of Rodauth *is* Turbo-compatible, so feel free to enable
+Turbo for actions where you want to use it.
+
 ### Mailer
 
 The install generator will create `RodauthMailer` with default email templates,
@@ -340,48 +381,48 @@ flow to use it.
 ```rb
 # app/mailers/rodauth_mailer.rb
 class RodauthMailer < ApplicationMailer
-  def verify_account(recipient, email_link)
+  def verify_account(account_id, key)
     # ...
   end
-  def reset_password(recipient, email_link)
+  def reset_password(account_id, key)
     # ...
   end
-  def verify_login_change(recipient, old_login, new_login, email_link)
+  def verify_login_change(account_id, old_login, new_login, key)
     # ...
   end
-  def password_changed(recipient)
+  def password_changed(account_id)
     # ...
   end
-  # def email_auth(recipient, email_link)
+  # def email_auth(account_id, key)
   # ...
   # end
-  # def unlock_account(recipient, email_link)
+  # def unlock_account(account_id, key)
   # ...
   # end
 end
 ```
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
     # ...
     create_reset_password_email do
-      RodauthMailer.reset_password(email_to, reset_password_email_link)
+      RodauthMailer.reset_password(account_id, reset_password_key_value)
     end
     create_verify_account_email do
-      RodauthMailer.verify_account(email_to, verify_account_email_link)
+      RodauthMailer.verify_account(account_id, verify_account_key_value)
     end
-    create_verify_login_change_email do |login|
-      RodauthMailer.verify_login_change(login, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_email_link)
+    create_verify_login_change_email do |_login|
+      RodauthMailer.verify_login_change(account_id, verify_login_change_old_login, verify_login_change_new_login, verify_login_change_key_value)
     end
     create_password_changed_email do
-      RodauthMailer.password_changed(email_to)
+      RodauthMailer.password_changed(account_id)
     end
     # create_email_auth_email do
-    #   RodauthMailer.email_auth(email_to, email_auth_email_link)
+    #   RodauthMailer.email_auth(account_id, email_auth_key_value)
     # end
     # create_unlock_account_email do
-    #   RodauthMailer.unlock_account(email_to, unlock_account_email_link)
+    #   RodauthMailer.unlock_account(account_id, unlock_account_key_value)
     # end
     send_email do |email|
       # queue email delivery on the mailer after the transaction commits
@@ -399,44 +440,8 @@ deliveries. However, if you want to send emails synchronously, you can modify
 the configuration to call `#deliver_now` instead.
 
 If you're using a background processing library without an Active Job adapter,
-or a 3rd-party service for sending transactional emails, this two-phase API
-might not be suitable. In this case, instead of overriding `#create_*_email`
-and `#send_email`, override the `#send_*_email` methods instead, which are
-required to send the email immediately. For example:
-
-```rb
-# app/workers/rodauth_mailer_worker.rb
-class RodauthMailerWorker
-  include Sidekiq::Worker
-
-  def perform(name, *args)
-    email = RodauthMailer.public_send(name, *args)
-    email.deliver_now
-  end
-end
-```
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure do
-    # ...
-    # use `#send_*_email` method to be able to immediately enqueue email delivery
-    send_reset_password_email do
-      enqueue_email(:reset_password, email_to, reset_password_email_link)
-    end
-    # ...
-    auth_class_eval do
-      # custom method for enqueuing email delivery using our worker
-      def enqueue_email(name, *args)
-        db.after_commit do
-          RodauthMailerWorker.perform_async(name, *args)
-        end
-      end
-    end
-    # ...
-  end
-end
-```
+or a 3rd-party service for sending transactional emails, see [this wiki
+page][custom mailer worker] on how to set it up.
 
 ### Migrations
 
@@ -458,7 +463,23 @@ class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
 end
 ```
 
-### Model
+#### Custom migration name
+
+You can change the default migration name:
+
+```sh
+$ rails generate rodauth:migration email_auth --name create_account_email_auth_keys
+```
+```rb
+# db/migration/*_create_account_email_auth_keys
+class CreateAccountEmailAuthKeys < ActiveRecord::Migration
+  def change
+    create_table :account_email_auth_keys do |t| ... end
+  end
+end
+```
+
+## Model
 
 The `Rodauth::Rails::Model` mixin can be included into the account model, which
 defines a password attribute and associations for tables used by enabled
@@ -470,7 +491,7 @@ class Account < ApplicationRecord
 end
 ```
 
-#### Password attribute
+### Password attribute
 
 Regardless of whether you're storing the password hash in a column in the
 accounts table, or in a separate table, the `#password` attribute can be used
@@ -494,7 +515,7 @@ Note that the password attribute doesn't come with validations, making it
 unsuitable for forms. It was primarily intended to allow easily creating
 accounts in development console and in tests.
 
-#### Associations
+### Associations
 
 The `Rodauth::Rails::Model` mixin defines associations for Rodauth tables
 associated to the accounts table:
@@ -544,6 +565,8 @@ class Account < ApplicationRecord
 end
 ```
 
+#### Association reference
+
 Below is a list of all associations defined depending on the features loaded:
 
 | Feature                 | Association                  | Type       | Model                    | Table (default)                     |
@@ -568,6 +591,12 @@ Below is a list of all associations defined depending on the features loaded:
 | webauthn                | `:webauthn_keys`             | `has_many` | `WebauthnKey`            | `account_webauthn_keys`             |
 | webauthn                | `:webauthn_user_id`          | `has_one`  | `WebauthnUserId`         | `account_webauthn_user_ids`         |
 
+Note that some Rodauth tables use composite primary keys, which Active Record
+doesn't support out of the box. For associations to work properly, you might
+need to add the [composite_primary_keys] gem to your Gemfile.
+
+#### Association options
+
 By default, all associations except for audit logs have `dependent: :destroy`
 set, to allow for easy deletion of account records in the console. You can use
 `:association_options` to modify global or per-association options:
@@ -582,138 +611,64 @@ Rodauth::Rails.model(association_options: -> (name) {
 })
 ```
 
-Note that some Rodauth tables use composite primary keys, which Active Record
-doesn't support out of the box. For associations to work properly, you might
-need to add the [composite_primary_keys] gem to your Gemfile.
-
-### Multiple configurations
+## Multiple configurations
 
 If you need to handle multiple types of accounts that require different
-authentication logic, you can create additional configurations for them:
+authentication logic, you can create new configurations for them. This
+is done by creating new `Rodauth::Rails::Auth` subclasses, and registering
+them under a name.
 
 ```rb
-# app/lib/rodauth_app.rb
+# app/misc/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  # primary configuration
-  configure do
-    # ...
-  end
+  configure RodauthMain          # primary configuration
+  configure RodauthAdmin, :admin # secondary configuration
 
-  # alternative configuration
-  configure(:admin) do
+  route do |r|
+    r.rodauth         # route primary rodauth requests
+    r.rodauth(:admin) # route secondary rodauth requests
+  end
+end
+```
+```rb
+# app/misc/rodauth_admin.rb
+class RodauthAdmin < Rodauth::Rails::Auth
+  configure do
     # ... enable features ...
     prefix "/admin"
     session_key_prefix "admin_"
     remember_cookie_key "_admin_remember" # if using remember feature
-    # ...
-  end
 
-  route do |r|
-    r.rodauth
-
-    r.on "admin" do
-      r.rodauth(:admin)
-      break # allow routing of other /admin/* requests to continue to Rails
-    end
-
-    # ...
+    # search views in `app/views/admin/rodauth` directory
+    rails_controller { Admin::RodauthController }
   end
 end
 ```
-
-Then in your application you can reference the secondary Rodauth instance:
-
 ```rb
-rodauth(:admin).login_path #=> "/admin/login"
-```
-
-You'll likely want to save the information of which account belongs to which
-configuration to the database. One way would be to have a separate table that
-stores account types:
-
-```sh
-$ rails generate migration create_account_types
-```
-```rb
-# db/migrate/*_create_account_types.rb
-class CreateAccountTypes < ActiveRecord::Migration
-  def change
-    create_table :account_types do |t|
-      t.references :account, foreign_key: { on_delete: :cascade }, null: false
-      t.string :type, null: false
-    end
-  end
+# app/controllers/admin/rodauth_controller.rb
+class Admin::RodauthController < ApplicationController
 end
 ```
-```sh
-$ rails db:migrate
-```
 
-Then an entry would be inserted after account creation, and optionally whenever
-Rodauth retrieves accounts you could filter only those belonging to the current
-configuration:
+Then in your application you can reference the secondary Rodauth instance:
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure(:admin) do
-    # ...
-    after_create_account do
-      db[:account_types].insert(account_id: account_id, type: "admin")
-    end
-    auth_class_eval do
-      def account_ds(*)
-        super.join(:account_types, account_id: :id).where(type: "admin")
-      end
-    end
-    # ...
-  end
-end
+rodauth(:admin).login_path #=> "/admin/login"
 ```
 
-#### Named auth classes
-
-A `configure` block inside `Rodauth::Rails::App` will internally create an
-anonymous `Rodauth::Auth` subclass, and register it under the given name.
-However, you can also define the auth classes explicitly, by creating
-subclasses of `Rodauth::Rails::Auth`:
+You'll likely want to save the information of which account belongs to which
+configuration to the database. See [this guide][account types] on how you can do
+that.
 
-```rb
-# app/lib/rodauth_main.rb
-class RodauthMain < Rodauth::Rails::Auth
-  configure do
-    # ... main configuration ...
-  end
-end
-```
-```rb
-# app/lib/rodauth_admin.rb
-class RodauthAdmin < Rodauth::Rails::Auth
-  configure do
-    # ...
-    prefix "/admin"
-    session_key_prefix "admin_"
-    # ...
-  end
-end
-```
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure RodauthMain
-  configure RodauthAdmin, :admin
-  # ...
-end
-```
+### Sharing configuration
 
-This allows having each configuration in a dedicated file, and named constants
-improve introspection and error messages. You can also use inheritance to share
-common settings:
+If there are common settings that you want to share between Rodauth
+configurations, you can do so via inheritance:
 
 ```rb
-# app/lib/rodauth_base.rb
+# app/misc/rodauth_base.rb
 class RodauthBase < Rodauth::Rails::Auth
-  # common settings that can be shared between multiple configurations
+  # common settings that are shared between multiple configurations
   configure do
     enable :login, :logout
     login_return_to_requested_location? true
@@ -723,7 +678,7 @@ class RodauthBase < Rodauth::Rails::Auth
 end
 ```
 ```rb
-# app/lib/rodauth_main.rb
+# app/misc/rodauth_main.rb
 class RodauthMain < RodauthBase # inherit common settings
   configure do
     # ... customize main ...
@@ -731,7 +686,7 @@ class RodauthMain < RodauthBase # inherit common settings
 end
 ```
 ```rb
-# app/lib/rodauth_admin.rb
+# app/misc/rodauth_admin.rb
 class RodauthAdmin < RodauthBase # inherit common settings
   configure do
     # ... customize admin ...
@@ -739,112 +694,63 @@ class RodauthAdmin < RodauthBase # inherit common settings
 end
 ```
 
-Another benefit of explicit classes is that you can define custom methods
-directly at the class level instead of inside an `auth_class_eval`:
-
-```rb
-# app/lib/rodauth_admin.rb
-class RodauthAdmin < Rodauth::Rails::Auth
-  configure do
-    # ...
-  end
-
-  def superadmin?
-    Role.where(account_id: session_id, type: "superadmin").any?
-  end
-end
-```
-```rb
-# config/routes.rb
-Rails.application.routes.draw do
-  constraints Rodauth::Rails.authenticated(:admin) { |rodauth| rodauth.superadmin? } do
-    mount Sidekiq::Web => "sidekiq"
-  end
-end
-```
-
-### Calling controller methods
-
-When using Rodauth before/after hooks or generally overriding your Rodauth
-configuration, in some cases you might want to call methods defined on your
-controllers. You can do so with `rails_controller_eval`, for example:
-
-```rb
-# app/controllers/application_controller.rb
-class ApplicationController < ActionController::Base
-  private
-  def setup_tracking(account_id)
-    # ... some implementation ...
-  end
-end
-```
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure do
-    after_create_account do
-      rails_controller_eval { setup_tracking(account_id) }
-    end
-  end
-end
-```
+## Outside of a request
 
-### Outside of a request
+### Calling actions
 
 In some cases you might need to use Rodauth more programmatically. If you want
 to perform authentication operations outside of request context, Rodauth ships
 with the [internal_request] feature just for that.
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
     enable :internal_request
   end
 end
 ```
 ```rb
-# main configuration
+# primary configuration
 RodauthApp.rodauth.create_account(login: "user@example.com", password: "secret")
 RodauthApp.rodauth.verify_account(account_login: "user@example.com")
 
 # secondary configuration
-RodauthApp.rodauth(:admin).close_account(account_login: "admin@example.com")
+RodauthApp.rodauth(:admin).close_account(account_login: "user@example.com")
 ```
 
-The rodauth-rails gem additionally updates the internal rack env hash with your
-`config.action_mailer.default_url_options`, which is used for generating email
-links.
+### Generating URLs
 
 For generating authentication URLs outside of a request use the
 [path_class_methods] plugin:
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
     enable :path_class_methods
+    create_account_route "register"
   end
 end
 ```
 ```rb
-# main configuration
-RodauthApp.rodauth.create_account_path
-RodauthApp.rodauth.verify_account_url(key: "abc123")
+# primary configuration
+RodauthApp.rodauth.create_account_path # => "/register"
+RodauthApp.rodauth.verify_account_url(key: "abc123") #=> "https://example.com/verify-account?key=abc123"
 
 # secondary configuration
-RodauthApp.rodauth(:admin).close_account_path
+RodauthApp.rodauth(:admin).close_account_path(foo: "bar") #=> "/admin/close-account?foo=bar"
 ```
 
-#### Calling instance methods
+### Calling instance methods
 
 If you need to access Rodauth methods not exposed as internal requests, you can
 use `Rodauth::Rails.rodauth` to retrieve the Rodauth instance used by the
 internal_request feature:
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
     enable :internal_request # this is required
   end
@@ -852,7 +758,7 @@ end
 ```
 ```rb
 account = Account.find_by!(email: "user@example.com")
-rodauth = Rodauth::Rails.rodauth(account: account)
+rodauth = Rodauth::Rails.rodauth(account: account) #=> #<RodauthMain::InternalRequest ...>
 
 rodauth.compute_hmac("token") #=> "TpEJTKfKwqYvIDKWsuZhkhKlhaBXtR1aodskBAflD8U"
 rodauth.open_account? #=> true
@@ -873,480 +779,290 @@ Rodauth::Rails.rodauth(session: { two_factor_auth_setup: true })
 Rodauth::Rails.rodauth(:admin, params: { "param" => "value" })
 ```
 
-## How it works
+## Configuring
 
-### Middleware
+### Configuration methods
 
-rodauth-rails inserts a `Rodauth::Rails::Middleware` into your middleware
-stack, which calls your Rodauth app for each request, before the request
-reaches the Rails router.
+The `rails` feature rodauth-rails loads provides the following configuration
+methods:
 
-```sh
-$ rails middleware
-...
-use Rodauth::Rails::Middleware
-run MyApp::Application.routes
-```
+| Name                        | Description                                                        |
+| :----                       | :----------                                                        |
+| `rails_render(**options)`   | Renders the template with given render options.                    |
+| `rails_csrf_tag`            | Hidden field added to Rodauth templates containing the CSRF token. |
+| `rails_csrf_param`          | Value of the `name` attribute for the CSRF tag.                    |
+| `rails_csrf_token`          | Value of the `value` attribute for the CSRF tag.                   |
+| `rails_check_csrf!`         | Verifies the authenticity token for the current request.           |
+| `rails_controller_instance` | Instance of the controller with the request env context.           |
+| `rails_controller`          | Controller class to use for rendering and CSRF protection.         |
+| `rails_account_model`       | Model class connected with the accounts table.                     |
 
-The Rodauth app stores the `Rodauth::Auth` instance in the Rack env hash, which
-is then available in your Rails app:
+For the list of configuration methods provided by Rodauth, see the [feature
+documentation].
 
-```rb
-request.env["rodauth"]       #=> #<Rodauth::Auth>
-request.env["rodauth.admin"] #=> #<Rodauth::Auth> (if using multiple configurations)
-```
+### Defining custom methods
 
-For convenience, this object can be accessed via the `#rodauth` method in views
-and controllers:
+All Rodauth configuration methods are just syntax sugar for defining instance
+methods on the auth class. You can also define your own custom methods on the
+auth class:
 
 ```rb
-class MyController < ApplicationController
-  def my_action
-    rodauth         #=> #<Rodauth::Auth>
-    rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations)
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    # ...
+    password_match? { |password| ldap_valid?(password) }
+    # ...
   end
-end
-```
-```erb
-<% rodauth         #=> #<Rodauth::Auth> %>
-<% rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations) %>
-```
-
-### App
-
-The `Rodauth::Rails::App` class is a [Roda] subclass that provides Rails
-integration for Rodauth:
 
-* uses Action Dispatch flash instead of Roda's
-* uses Action Dispatch CSRF protection instead of Roda's
-* sets [HMAC] secret to Rails' secret key base
-* uses Action Controller for rendering templates
-* runs Action Controller callbacks & rescue handlers around Rodauth actions
-* uses Action Mailer for sending emails
+  # Example external identities table
+  def identities
+    db[:account_identities].where(account_id: account_id).all
+  end
 
-The `configure` method wraps configuring the Rodauth plugin, forwarding
-any additional [plugin options].
+  private
 
-```rb
-class RodauthApp < Rodauth::Rails::App
-  configure { ... }             # defining default Rodauth configuration
-  configure(json: true) { ... } # passing options to the Rodauth plugin
-  configure(:admin) { ... }     # defining multiple Rodauth configurations
+  # Example LDAP authentication
+  def ldap_valid?(password)
+    SimpleLdapAuthenticator.valid?(account[:email], password)
+  end
 end
 ```
+```rb
+rodauth.identities #=> [{ provider: "facebook", uid: "abc123", ... }, ...]
+```
 
-The `route` block is provided by Roda, and it's called on each request before
-it reaches the Rails router.
+### Rails URL helpers
+
+Inside Rodauth configuration and the `route` block you can access Rails route
+helpers through `#rails_routes`:
 
 ```rb
-class RodauthApp < Rodauth::Rails::App
-  route do |r|
-    # ... called before each request ...
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    login_redirect { rails_routes.activity_path }
   end
 end
 ```
 
-Since `Rodauth::Rails::App` is just a Roda subclass, you can do anything you
-would with a Roda app, such as loading additional Roda plugins:
+### Calling controller methods
+
+When using Rodauth before/after hooks or generally overriding your Rodauth
+configuration, in some cases you might want to call methods defined on your
+controllers. You can do so with `rails_controller_eval`, for example:
 
 ```rb
-class RodauthApp < Rodauth::Rails::App
-  plugin :request_headers # easier access to request headers
-  plugin :typecast_params # methods for conversion of request params
-  plugin :default_headers, { "Foo" => "Bar" }
-  # ...
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  private
+  def setup_tracking(account_id)
+    # ... some implementation ...
+  end
 end
 ```
-
-### Sequel
-
-Rodauth uses the [Sequel] library for database queries, due to more advanced
-database usage (SQL expressions, database-agnostic date arithmetic, SQL
-function calls).
-
-If ActiveRecord is used in the application, the `rodauth:install` generator
-will have automatically configured Sequel to reuse ActiveRecord's database
-connection, using the [sequel-activerecord_connection] gem.
-
-This means that, from the usage perspective, Sequel can be considered just
-as an implementation detail of Rodauth.
-
-## JSON API
-
-To make Rodauth endpoints accessible via JSON API, enable the [`json`][json]
-feature:
-
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
   configure do
-    # ...
-    enable :json
-    only_json? true # accept only JSON requests (optional)
-    # ...
+    after_create_account do
+      rails_controller_eval { setup_tracking(account_id) }
+    end
   end
 end
 ```
 
-This will store account session data into the Rails session. If you rather want
-stateless token-based authentication via the `Authorization` header, enable the
-[`jwt`][jwt] feature (which builds on top of the `json` feature) and add the
-[JWT gem] to the Gemfile:
+### Single-file configuration
+
+If you would prefer to have all Rodauth logic contained inside a single file,
+you call `Rodauth::Rails::App.configure` with a block, which will create an
+anonymous auth class.
 
-```sh
-$ bundle add jwt
-```
 ```rb
-# app/lib/rodauth_app.rb
+# app/misc/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
+  # primary configuration
   configure do
-    # ...
-    enable :jwt
-    jwt_secret "<YOUR_SECRET_KEY>" # store the JWT secret in a safe place
-    only_json? true # accept only JSON requests (optional)
+    enable :login, :logout, :create_account, :verify_account
     # ...
   end
-end
-```
 
-The JWT token will be returned after each request to Rodauth routes. To also
-return the JWT token on requests to your app's routes, you can add the
-following code to your base controller:
-
-```rb
-class ApplicationController < ActionController::Base
-  # ...
-  after_action :set_jwt_token
-
-  private
+  # secondary configuration
+  configure(:admin) do
+    enable :email_auth, :single_session
+    # ...
+  end
 
-  def set_jwt_token
-    if rodauth.use_jwt? && rodauth.valid_jwt?
-      response.headers["Authorization"] = rodauth.session_jwt
-    end
+  route do |r|
+    # ...
   end
-  # ...
 end
 ```
 
-## OmniAuth
-
-While Rodauth doesn't yet come with [OmniAuth] integration, we can build one
-ourselves using the existing Rodauth API.
-
-Let's assume we're building Facebook login. We'll start by installing the
-necessary gems, and loading the Facebook OmniAuth strategy:
+## How it works
 
-```rb
-# Gemfile
-gem "omniauth", "~> 2.0"
-gem "omniauth-rails_csrf_protection" # https://github.com/omniauth/omniauth/wiki/Resolving-CVE-2015-9284
-gem "omniauth-facebook"
-```
-```rb
-# config/initializers/omniauth.rb
-Rails.application.config.middleware.use OmniAuth::Builder do
-  provider :facebook, ENV["FACEBOOK_APP_ID"], ENV["FACEBOOK_APP_SECRET"],
-    scope: "email", callback_path: "/auth/facebook/callback"
-end
-```
+### Rack middleware
 
-Since users might potentially want to login with multiple external providers, let's
-create an `account_identities` table that will have a many-to-one relationship
-with the `accounts` table:
+The railtie inserts [`Rodauth::Rails::Middleware`](/lib/rodauth/rails/middleware.rb)
+at the end of the middleware stack, which calls your Rodauth app around each request.
 
 ```sh
-$ rails generate model AccountIdentity
+$ rails middleware
+# ...
+# use Rodauth::Rails::Middleware
+# run MyApp::Application.routes
 ```
-```rb
-# db/migrate/*_create_account_identities.rb
-class CreateAccountIdentities < ActiveRecord::Migration
-  def change
-    create_table :account_identities do |t|
-      t.references :account, null: false, foreign_key: { on_delete: :cascade }
-      t.string :provider, null: false
-      t.string :uid, null: false
-      t.jsonb :info, null: false, default: {} # adjust JSON column type for your database
 
-      t.timestamps
+It can be inserted at any point in the middleware stack:
 
-      t.index [:provider, :uid], unique: true
-    end
-  end
-end
-```
 ```rb
-# app/models/account_identity.rb
-class AcccountIdentity < ApplicationRecord
-  belongs_to :account
-end
-```
-```rb
-# app/models/account.rb
-class Account < ApplicationRecord
-  has_many :identities, class_name: "AccountIdentity"
+Rodauth::Rails.configure do |config|
+  config.middleware = false # disable auto-insertion
 end
-```
-
-Next, let's add a POST button pointing to the request URL to our login form:
 
-```erb
-<%= button_to "Login via Facebook", "/auth/facebook",
-  method: :post, data: { turbo: false }, class: "btn btn-link p-0" %>
+Rails.application.config.middleware.insert_before AnotherMiddleware, Rodauth::Rails::Middleware
 ```
 
-Finally, let's implement the OmniAuth callback endpoint on our Rodauth
-controller:
+The middleware retrieves the Rodauth app via `Rodauth::Rails.app`, which is
+specified as a string to keep the class autoloadable and reloadable in
+development.
 
 ```rb
-# config/routes.rb
-Rails.application.routes.draw do
-  # ...
-  get "/auth/:provider/callback", to: "rodauth#omniauth"
+Rodauth::Rails.configure do |config|
+  config.app = "RodauthApp"
 end
 ```
-```rb
-# app/controllres/rodauth_controller.rb
-class RodauthController < ApplicationController
-  def omniauth
-    auth = request.env["omniauth.auth"]
 
-    # attempt to find existing identity directly
-    identity = AccountIdentity.find_by(provider: auth["provider"], uid: auth["uid"])
+In addition to Zeitwerk compatibility, this extra layer catches Rodauth redirects
+that happen on the controller level (e.g. when calling
+`rodauth.require_authentication` in a `before_action` filter).
 
-    if identity
-      # update any external info changes
-      identity.update!(info: auth["info"])
-      # set account from identity
-      account = identity.account
-    end
+### Roda app
 
-    # attempt to find an existing account by email
-    account ||= Account.find_by(email: auth["info"]["email"])
+The [`Rodauth::Rails::App`](/lib/rodauth/rails/app.rb) class is a [Roda]
+subclass that provides a convenience layer for Rodauth:
 
-    # disallow login if account is not verified
-    if account && account.status != rodauth.account_open_status_value
-      redirect_to rodauth.login_path, alert: rodauth.unverified_account_message
-      return
-    end
+* uses Action Dispatch flash messages
+* provides syntax sugar for loading the rodauth plugin
+* saves Rodauth object(s) to Rack env hash
+* propagates edited headers to Rails responses
 
-    # create new account if it doesn't exist
-    unless account
-      account = Account.create!(email: auth["info"]["email"], status: rodauth.account_open_status_value)
-    end
+#### Configure block
 
-    # create new identity if it doesn't exist
-    unless identity
-      account.identities.create!(provider: auth["provider"], uid: auth["uid"], info: auth["info"])
-    end
-
-    # load the account into the rodauth instance
-    rodauth.account_from_login(account.email)
-
-    rodauth_response do # ensures any `after_action` callbacks get called
-      # sign in the loaded account
-      rodauth.login("omniauth")
-    end
-  end
-end
-```
-
-## Configuring
-
-The `rails` feature rodauth-rails loads provides the following configuration
-methods:
-
-| Name                        | Description                                                        |
-| :----                       | :----------                                                        |
-| `rails_render(**options)`   | Renders the template with given render options.                    |
-| `rails_csrf_tag`            | Hidden field added to Rodauth templates containing the CSRF token. |
-| `rails_csrf_param`          | Value of the `name` attribute for the CSRF tag.                    |
-| `rails_csrf_token`          | Value of the `value` attribute for the CSRF tag.                   |
-| `rails_check_csrf!`         | Verifies the authenticity token for the current request.           |
-| `rails_controller_instance` | Instance of the controller with the request env context.           |
-| `rails_controller`          | Controller class to use for rendering and CSRF protection.         |
-| `rails_account_model`       | Model class connected with the accounts table.                     |
+The `configure` call loads the rodauth plugin. By convention, it receives an
+auth class and configuration name as positional arguments (forwarded as
+`:auth_class` and `:name` plugin options), a block for anonymous auth classes,
+and also accepts any additional plugin options.
 
-The `Rodauth::Rails` module has a few config settings available as well:
+```rb
+class RodauthApp < Rodauth::Rails::App
+  # named auth class
+  configure(RodauthMain)
+  configure(RodauthAdmin, :admin)
 
-| Name         | Description                                                                                         |
-| :-----       | :----------                                                                                         |
-| `app`        | Constant name of your Rodauth app, which is called by the middleware.                               |
-| `middleware` | Whether to insert the middleware into the Rails application's middleware stack. Defaults to `true`. |
+  # anonymous auth class
+  configure { ... }
+  configure(:admin) { ... }
 
-```rb
-# config/initializers/rodauth.rb
-Rodauth::Rails.configure do |config|
-  config.app = "RodauthApp"
-  config.middleware = true
+  # plugin options
+  configure(RodauthMain, json: :only)
 end
 ```
 
-For the list of configuration methods provided by Rodauth, see the [feature
-documentation].
-
-## Custom extensions
+#### Route block
 
-When developing custom extensions for Rodauth inside your Rails project, it's
-probably better to use plain modules, at least in the beginning, as Rodauth
-feature design doesn't yet work well with Zeitwerk reloading.
-
-Here is an example of an LDAP authentication extension that uses the
-[simple_ldap_authenticator] gem.
+The `route` block is called for each request, before it reaches the Rails
+router, and it's yielded the request object.
 
 ```rb
-# app/lib/rodauth_ldap.rb
-module RodauthLdap
-  def require_bcrypt?
-    false
-  end
-
-  def password_match?(password)
-    SimpleLdapAuthenticator.valid?(account[:email], password)
-  end
-end
-```
-```rb
-# app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  configure do
-    # ...
-    auth_class_eval do
-      include RodauthLdap
-    end
-    # ...
+  route do |r|
+    # called before each request
   end
 end
 ```
 
-## Testing
+#### Routing prefix
 
-System (browser) tests for Rodauth actions could look something like this:
+If you use a routing prefix, you don't need to add a call to `r.on` like with
+vanilla Rodauth, as `r.rodauth` has been modified to automatically route the
+prefix.
 
 ```rb
-# test/system/authentication_test.rb
-require "test_helper"
-
-class AuthenticationTest < ActionDispatch::SystemTestCase
-  include ActiveJob::TestHelper
-  driven_by :rack_test
-
-  test "creating and verifying an account" do
-    create_account
-    assert_match "An email has been sent to you with a link to verify your account", page.text
-
-    verify_account
-    assert_match "Your account has been verified", page.text
-  end
-
-  test "logging in and logging out" do
-    create_account(verify: true)
-
-    logout
-    assert_match "You have been logged out", page.text
-
-    login
-    assert_match "You have been logged in", page.text
-  end
-
-  private
-
-  def create_account(email: "user@example.com", password: "secret", verify: false)
-    visit "/create-account"
-    fill_in "Login", with: email
-    fill_in "Password", with: password
-    fill_in "Confirm Password", with: password
-    click_on "Create Account"
-    verify_account if verify
-  end
-
-  def verify_account
-    perform_enqueued_jobs # run enqueued email deliveries
-    email = ActionMailer::Base.deliveries.last
-    verify_account_link = email.body.to_s[/\S+verify-account\S+/]
-    visit verify_account_link
-    click_on "Verify Account"
-  end
-
-  def login(email: "user@example.com", password: "secret")
-    visit "/login"
-    fill_in "Login", with: email
-    fill_in "Password", with: password
-    click_on "Login"
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    prefix "/user"
   end
 
-  def logout
-    visit "/logout"
-    click_on "Logout"
+  route do |r|
+    r.rodauth # no need to wrap with `r.on("user") { ... }`
   end
 end
 ```
 
-While request tests in JSON API mode with JWT tokens could look something like
-this:
+### Auth class
+
+The [`Rodauth::Rails::Auth`](/lib/rodauth/rails/auth.rb) class is a subclass of
+`Rodauth::Auth`, which preloads the `rails` rodauth feature, sets [HMAC] secret to
+Rails' secret key base, and modifies some [configuration defaults](#rodauth-defaults).
 
 ```rb
-# test/integration/authentication_test.rb
-require "test_helper"
-
-class AuthenticationTest < ActionDispatch::IntegrationTest
-  test "creating and verifying an account" do
-    create_account
-    assert_response :success
-    assert_match "An email has been sent to you with a link to verify your account", JSON.parse(body)["success"]
-
-    verify_account
-    assert_response :success
-    assert_match "Your account has been verified", JSON.parse(body)["success"]
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    # authentication configuration
   end
+end
+```
 
-  test "logging in and logging out" do
-    create_account(verify: true)
+### Rodauth feature
 
-    logout
-    assert_response :success
-    assert_match "You have been logged out", JSON.parse(body)["success"]
+The [`rails`](/lib/rodauth/rails/feature.rb) Rodauth feature loaded by
+`Rodauth::Rails::Auth` provides the main part of the Rails integration for Rodauth:
 
-    login
-    assert_response :success
-    assert_match "You have been logged in", JSON.parse(body)["success"]
-  end
+* uses Action View for template rendering
+* uses Action Dispatch for CSRF protection
+* runs Action Controller callbacks and rescue from blocks around Rodauth requests
+* uses Action Mailer to create and deliver emails
+* uses Action Controller instrumentation around Rodauth requests
+* uses Action Mailer's default URL options when calling Rodauth outside of a request
 
-  private
+### Controller
 
-  def create_account(email: "user@example.com", password: "secret", verify: false)
-    post "/create-account", as: :json, params: { login: email, password: password, "password-confirm": password }
-    verify_account if verify
-  end
+The Rodauth app stores the `Rodauth::Rails::Auth` instances in the Rack env
+hash, which is then available in your Rails app:
 
-  def verify_account
-    perform_enqueued_jobs # run enqueued email deliveries
-    email = ActionMailer::Base.deliveries.last
-    verify_account_key = email.body.to_s[/verify-account\?key=(\S+)/, 1]
-    post "/verify-account", as: :json, params: { key: verify_account_key }
-  end
+```rb
+request.env["rodauth"]       #=> #<RodauthMain>
+request.env["rodauth.admin"] #=> #<RodauthAdmin> (if using multiple configurations)
+```
 
-  def login(email: "user@example.com", password: "secret")
-    post "/login", as: :json, params: { login: email, password: password }
-  end
+For convenience, this object can be accessed via the `#rodauth` method in views
+and controllers:
 
-  def logout
-    post "/logout", as: :json, headers: { "Authorization" => headers["Authorization"] }
+```rb
+class MyController < ApplicationController
+  def my_action
+    rodauth         #=> #<RodauthMain>
+    rodauth(:admin) #=> #<RodauthAdmin> (if using multiple configurations)
   end
 end
 ```
+```erb
+<% rodauth         #=> #<RodauthMain> %>
+<% rodauth(:admin) #=> #<RodauthAdmin> (if using multiple configurations) %>
+```
 
-If you're delivering emails in the background, make sure to set Active Job
-queue adapter to `:test` or `:inline`:
+### Sequel
 
-```rb
-# config/environments/test.rb
-Rails.application.configure do |config|
-  # ...
-  config.active_job.queue_adapter = :test # or :inline
-  # ...
-end
-```
+Rodauth uses the [Sequel] library for database interaction, which offers
+powerful APIs for building advanced queries (it supports SQL expressions,
+database-agnostic date arithmetic, SQL function calls).
+
+If you're using Active Record in your application, the `rodauth:install`
+generator automatically configures Sequel to reuse ActiveRecord's database
+connection, using the [sequel-activerecord_connection] gem.
+
+This means that, from the usage perspective, Sequel can be considered just
+as an implementation detail of Rodauth.
 
 ## Rodauth defaults
 
@@ -1393,16 +1109,15 @@ end
 
 The recommended [Rodauth migration] stores possible account status values in a
 separate table, and creates a foreign key on the accounts table, which ensures
-only a valid status value will be persisted.
+only a valid status value will be persisted. Unfortunately, this doesn't work
+when the database is restored from the schema file, in which case the account
+statuses table will be empty. This happens in tests by default, but it's also
+not unusual to do it in development.
 
-Unfortunately, this doesn't work when the database is restored from the schema
-file, in which case the account statuses table will be empty. This happens in
-tests by default, but it's also commonly done in development.
-
-To address this, rodauth-rails modifies the setup to store account status text
-directly in the accounts table. If you're worried about invalid status values
-creeping in, you may use enums instead. Alternatively, you can always go back
-to the setup recommended by Rodauth.
+To address this, rodauth-rails uses a `status` column without a separate table.
+If you're worried about invalid status values creeping in, you may use enums
+instead. Alternatively, you can always go back to the setup recommended by
+Rodauth.
 
 ```rb
 # in the migration:
@@ -1418,14 +1133,13 @@ create_table :accounts do |t|
 end
 ```
 ```diff
-configure do
-  # ...
-- account_status_column :status
-- account_unverified_status_value "unverified"
-- account_open_status_value "verified"
-- account_closed_status_value "closed"
-  # ...
-end
+  class RodauthMain < Rodauth::Rails::Auth
+    configure do
+      # ...
+-     account_status_column :status
+      # ...
+    end
+  end
 ```
 
 ### Deadline values
@@ -1454,7 +1168,6 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [Rodauth]: https://github.com/jeremyevans/rodauth
 [Sequel]: https://github.com/jeremyevans/sequel
 [feature documentation]: http://rodauth.jeremyevans.net/documentation.html
-[JWT gem]: https://github.com/jwt/ruby-jwt
 [Bootstrap]: https://getbootstrap.com/
 [Roda]: http://roda.jeremyevans.net/
 [HMAC]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-HMAC
@@ -1463,7 +1176,6 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [sequel-activerecord_connection]: https://github.com/janko/sequel-activerecord_connection
 [plugin options]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-Plugin+Options
 [hmac]: http://rodauth.jeremyevans.net/rdoc/files/README_rdoc.html#label-HMAC
-[OmniAuth]: https://github.com/omniauth/omniauth
 [otp]: http://rodauth.jeremyevans.net/rdoc/files/doc/otp_rdoc.html
 [sms_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/sms_codes_rdoc.html
 [recovery_codes]: http://rodauth.jeremyevans.net/rdoc/files/doc/recovery_codes_rdoc.html
@@ -1484,3 +1196,6 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [internal_request]: http://rodauth.jeremyevans.net/rdoc/files/doc/internal_request_rdoc.html
 [composite_primary_keys]: https://github.com/composite-primary-keys/composite_primary_keys
 [path_class_methods]: https://rodauth.jeremyevans.net/rdoc/files/doc/path_class_methods_rdoc.html
+[account types]: https://github.com/janko/rodauth-rails/wiki/Account-Types
+[custom mailer worker]: https://github.com/janko/rodauth-rails/wiki/Custom-Mailer-Worker
+[Turbo]: https://turbo.hotwired.dev/