rodauth-rails 0.18.1 → 1.0.0

data/README.md

@@ -8,6 +8,9 @@ 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:
 
@@ -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 the Rodauth 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,19 +137,6 @@ 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
@@ -160,13 +157,15 @@ configurations:
 current_account(:admin)
 ```
 
+#### 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|
@@ -305,12 +304,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 +351,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 +369,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 +428,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 +451,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 +479,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 +503,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 +553,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 +579,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,31 +599,21 @@ 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
 
-  # alternative configuration
-  configure(:admin) do
-    # ... enable features ...
-    prefix "/admin"
-    session_key_prefix "admin_"
-    remember_cookie_key "_admin_remember" # if using remember feature
-    # ...
-  end
+  # secondary configuration
+  configure RodauthAdmin, :admin
 
   route do |r|
     r.rodauth
@@ -620,100 +627,46 @@ class RodauthApp < Rodauth::Rails::App
   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
-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:
-
-```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
-```
-
-#### 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`:
-
-```rb
-# app/lib/rodauth_main.rb
-class RodauthMain < Rodauth::Rails::Auth
-  configure do
-    # ... main configuration ...
-  end
-end
-```
-```rb
-# app/lib/rodauth_admin.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
     # ...
+
+    # search views in `app/views/admin/rodauth` directory
+    rails_controller { Admin::RodauthController }
   end
 end
 ```
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure RodauthMain
-  configure RodauthAdmin, :admin
-  # ...
+# app/controllers/admin/rodauth_controller.rb
+class Admin::RodauthController < ApplicationController
 end
 ```
 
-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:
+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. See [this guide][account types] on how you can do
+that.
+
+### Sharing configuration
+
+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 +676,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 +684,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 +692,67 @@ 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
+## Outside of a request
 
-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
+### 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 +760,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
@@ -971,188 +879,10 @@ 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
-  configure do
-    # ...
-    enable :json
-    only_json? true # accept only JSON requests (optional)
-    # ...
-  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:
-
-```sh
-$ bundle add jwt
-```
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  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)
-    # ...
-  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
-
-  def set_jwt_token
-    if rodauth.use_jwt? && rodauth.valid_jwt?
-      response.headers["Authorization"] = rodauth.session_jwt
-    end
-  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:
-
-```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
-```
-
-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:
-
-```sh
-$ rails generate model AccountIdentity
-```
-```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
-
-      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"
-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" %>
-```
-
-Finally, let's implement the OmniAuth callback endpoint on our Rodauth
-controller:
-
-```rb
-# config/routes.rb
-Rails.application.routes.draw do
-  # ...
-  get "/auth/:provider/callback", to: "rodauth#omniauth"
-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"])
-
-    if identity
-      # update any external info changes
-      identity.update!(info: auth["info"])
-      # set account from identity
-      account = identity.account
-    end
-
-    # attempt to find an existing account by email
-    account ||= Account.find_by(email: auth["info"]["email"])
-
-    # 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
-
-    # create new account if it doesn't exist
-    unless account
-      account = Account.create!(email: auth["info"]["email"], status: rodauth.account_open_status_value)
-    end
-
-    # 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
 
+### Configuration methods
+
 The `rails` feature rodauth-rails loads provides the following configuration
 methods:
 
@@ -1167,6 +897,8 @@ methods:
 | `rails_controller`          | Controller class to use for rendering and CSRF protection.         |
 | `rails_account_model`       | Model class connected with the accounts table.                     |
 
+### General configuration
+
 The `Rodauth::Rails` module has a few config settings available as well:
 
 | Name         | Description                                                                                         |
@@ -1185,169 +917,102 @@ end
 For the list of configuration methods provided by Rodauth, see the [feature
 documentation].
 
-## Custom extensions
-
-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.
+### Defining custom methods
 
-Here is an example of an LDAP authentication extension that uses the
-[simple_ldap_authenticator] gem.
+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
-# app/lib/rodauth_ldap.rb
-module RodauthLdap
-  def require_bcrypt?
-    false
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    password_match? { |password| ldap_valid?(password) }
   end
 
-  def password_match?(password)
+  # Example external identities table
+  def identities
+    db[:account_identities].where(account_id: account_id).all
+  end
+
+  private
+
+  # Example LDAP authentication
+  def ldap_valid?(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
-    # ...
-  end
-end
+rodauth.identities #=> [{ provider: "facebook", uid: "abc123", ... }, ...]
 ```
 
-## Testing
+### Rails URL helpers
 
-System (browser) tests for Rodauth actions could look something like this:
+Inside Rodauth configuration and the `route` block you can access Rails route
+helpers through `#rails_routes`:
 
 ```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
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    login_redirect { rails_routes.activity_path }
   end
+end
+```
 
-  test "logging in and logging out" do
-    create_account(verify: true)
-
-    logout
-    assert_match "You have been logged out", page.text
+### Calling controller methods
 
-    login
-    assert_match "You have been logged in", page.text
-  end
+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 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"
-  end
-
-  def logout
-    visit "/logout"
-    click_on "Logout"
+  def setup_tracking(account_id)
+    # ... some implementation ...
   end
 end
 ```
-
-While request tests in JSON API mode with JWT tokens could look something like
-this:
-
 ```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"]
-  end
-
-  test "logging in and logging out" do
-    create_account(verify: true)
-
-    logout
-    assert_response :success
-    assert_match "You have been logged out", JSON.parse(body)["success"]
-
-    login
-    assert_response :success
-    assert_match "You have been logged in", JSON.parse(body)["success"]
+# app/misc/rodauth_main.rb
+class RodauthMain < Rodauth::Rails::Auth
+  configure do
+    after_create_account do
+      rails_controller_eval { setup_tracking(account_id) }
+    end
   end
+end
+```
 
-  private
+### Single-file configuration
 
-  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
+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.
 
-  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 }
+```rb
+# app/misc/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  # primary configuration
+  configure do
+    enable :login, :logout, :create_account, :verify_account
+    # ...
   end
 
-  def login(email: "user@example.com", password: "secret")
-    post "/login", as: :json, params: { login: email, password: password }
+  # secondary configuration
+  configure(:admin) do
+    enable :email_auth, :single_session
+    # ...
   end
 
-  def logout
-    post "/logout", as: :json, headers: { "Authorization" => headers["Authorization"] }
+  route do |r|
+    # ...
   end
 end
 ```
 
-If you're delivering emails in the background, make sure to set Active Job
-queue adapter to `:test` or `:inline`:
-
-```rb
-# config/environments/test.rb
-Rails.application.configure do |config|
-  # ...
-  config.active_job.queue_adapter = :test # or :inline
-  # ...
-end
-```
-
 ## Rodauth defaults
 
 rodauth-rails changes some of the default Rodauth settings for easier setup:
@@ -1454,7 +1119,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 +1127,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 +1147,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/