rodauth-rails 0.9.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8f8aec1dbdc745a530aabec0d63bc2681499dd36f8185faed9ea09e7184636e
-  data.tar.gz: fbc5a75976a922978a6e37fee3bef8e7f04bb0a9a324066afdf79172b33f00e9
+  metadata.gz: d447d09fef8c29feb6240523286b8906049e85965f20a6410d1a475f913d9051
+  data.tar.gz: bca9b6eadec6b32f2193291c6922467a554105d290ffd7b34bc2606d62121926
 SHA512:
-  metadata.gz: 89d2f6ad377ba8e3f18bc747c3bfdf53e97c1a29f2731036987e5f7c1fde14db89732cda2d09026a153d81eabe26e51e021a129f02517d4d5582fcaf392876ca
-  data.tar.gz: 648b1297a9569b436113b5921a9ae37944d808ed42a03ef57a75452a74143dcc493e7d9c34a12f31f780745db5d2b1365d5a7b602dfa303571961730566852f4
+  metadata.gz: 1f512f9fe9a3e22dcddf477d8906d1ea63a548241fd93b43bbcaf274ff39e0104e20f64c6a2836e5b243e812ffde654deae55a0beca69f4ba917cd5943da8a3c
+  data.tar.gz: dbbd99959dfd42134cd3374f1f9767cf3e8d49327c195d4c35c4ecf281d0c3dad52db76b7e2fbf030c9e3ea2131bfcb1b6a120cc4a310983d8db564e63b97cda

data/CHANGELOG.md

@@ -1,3 +1,57 @@
+## 0.14.0 (2021-07-10)
+
+* Speed up template rendering by only searching formats accepted by the request (@janko)
+
+* Add `--name` option to `rodauth:views` generator for specifying different rodauth configuration (@janko)
+
+* Infer correct template path from configured controller in `rodauth:views` generator (@janko)
+
+* Raise `ArgumentError` if undefined rodauth configuration is passed to `Rodauth::Rails.app` (@janko)
+
+* Make `#rails_controller` method on the rodauth instance public (@janko)
+
+* Remove `--directory` option from `rodauth:views` generator (@janko)
+
+* Remove `#features` and `#routes` writer and `#configuration` reader from `Rodauth::Rails::Auth` (@janko)
+
+## 0.13.0 (2021-06-10)
+
+* Add `:query`, `:form`, `:session`, `:account`, and `:env` options to `Rodauth::Rails.rodauth` (@janko)
+
+## 0.12.0 (2021-05-15)
+
+* Include total view render time in logs for Rodauth requests (@janko)
+
+* Instrument redirects (@janko)
+
+* Instrument Rodauth requests on `action_controller` namespace (@janko)
+
+* Update templates for Boostrap 5 compatibility (@janko)
+
+* Log request parameters for Rodauth requests (@janko)
+
+## 0.11.0 (2021-05-06)
+
+* Add controller-like logging for requests to Rodauth endpoints (@janko)
+
+* Add `#rails_routes` to Roda and Rodauth instance for accessing Rails route helpers (@janko)
+
+* Add `#rails_request` to Roda and Rodauth instance for retrieving an `ActionDispatch::Request` instance (@janko)
+
+## 0.10.0 (2021-03-23)
+
+* Add `Rodauth::Rails::Auth` superclass for moving configurations into separate files (@janko)
+
+* Load the `pass` Roda plugin and recommend calling `r.pass` on prefixed routes (@janko)
+
+* Improve Roda middleware inspect output (@janko)
+
+* Create `RodauthMailer` and email templates in `rodauth:install`, and remove `rodauth:mailer` (@janko)
+
+* Raise `KeyError` in `#rodauth` method when the Rodauth instance doesn't exist (@janko)
+
+* Add `Rodauth::Rails.authenticated` routing constraint for requiring authentication (@janko)
+
 ## 0.9.1 (2021-02-10)
 
 * Fix flash integration being loaded for API-only apps and causing an error (@dmitryzuev)

data/README.md

@@ -2,35 +2,6 @@
 
 Provides Rails integration for the [Rodauth] authentication framework.
 
-## Table of contents
-
-* [Resources](#resources)
-* [Why Rodauth?](#why-rodauth)
-* [Upgrading](#upgrading)
-* [Installation](#installation)
-* [Usage](#usage)
-  - [Routes](#routes)
-  - [Current account](#current-account)
-  - [Requiring authentication](#requiring-authentication)
-  - [Views](#views)
-  - [Mailer](#mailer)
-  - [Migrations](#migrations)
-  - [Multiple configurations](#multiple-configurations)
-  - [Calling controller methods](#calling-controller-methods)
-  - [Rodauth instance](#rodauth-instance)
-* [How it works](#how-it-works)
-  - [Middleware](#middleware)
-  - [App](#app)
-  - [Sequel](#sequel)
-* [JSON API](#json-api)
-* [OmniAuth](#omniauth)
-* [Configuring](#configuring)
-* [Custom extensions](#custom-extensions)
-* [Testing](#testing)
-* [Rodauth defaults](#rodauth-defaults)
-  - [Database functions](#database-functions)
-  - [Account statuses](#account-statuses)
-
 ## Resources
 
 Useful links:
@@ -43,6 +14,7 @@ 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/)
+* [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?
 
@@ -61,29 +33,23 @@ of the advantages that stand out for me:
 * consistent before/after hooks around everything
 * dedicated object encapsulating all authentication logic
 
-## Upgrading
-
-### Upgrading to 0.7.0
+One commmon concern is the fact that, unlike most other authentication
+frameworks for Rails, Rodauth uses [Sequel] for database interaction instead of
+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].
 
-Starting from version 0.7.0, rodauth-rails now correctly detects Rails
-application's `secret_key_base` when setting default `hmac_secret`, including
-when it's set via credentials or `$SECRET_KEY_BASE` environment variable. This
-means that your authentication will now be more secure by default, and Rodauth
-features that require `hmac_secret` should now work automatically as well.
+## Upgrading
 
-However, if you've already been using rodauth-rails in production, where the
-`secret_key_base` is set via credentials or environment variable and `hmac_secret`
-was not explicitly set, the fact that your authentication will now start using
-HMACs has backwards compatibility considerations. See the [Rodauth
-documentation][hmac] for instructions on how to safely transition, or just set
-`hmac_secret nil` in your Rodauth configuration.
+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.9"
+gem "rodauth-rails", "~> 0.14"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -108,114 +74,22 @@ $ rails generate rodauth:install --jwt # token authentication via the "Authoriza
 $ bundle add jwt
 ```
 
-The generator will create the following files:
-
-* Rodauth migration at `db/migrate/*_create_rodauth.rb`
-* Rodauth initializer at `config/initializers/rodauth.rb`
-* Sequel initializer at `config/initializers/sequel.rb` for ActiveRecord integration
-* Rodauth app at `app/lib/rodauth_app.rb`
-* Rodauth controller at `app/controllers/rodauth_controller.rb`
-* Account model at `app/models/account.rb`
-
-### Migration
-
-The migration file creates tables required by Rodauth. You're encouraged to
-review the migration, and modify it to only create tables for features you
-intend to use.
-
-```rb
-# db/migrate/*_create_rodauth.rb
-class CreateRodauth < ActiveRecord::Migration
-  def change
-    create_table :accounts do |t| ... end
-    create_table :account_password_hashes do |t| ... end
-    create_table :account_password_reset_keys do |t| ... end
-    create_table :account_verification_keys do |t| ... end
-    create_table :account_login_change_keys do |t| ... end
-    create_table :account_remember_keys do |t| ... end
-  end
-end
-```
+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.
 
-Once you're done, you can run the migration:
+Feel free to remove any features you don't need, along with their corresponding
+tables. Afterwards, run the migration:
 
-```
+```sh
 $ rails db:migrate
 ```
 
-### Rodauth initializer
-
-The Rodauth initializer assigns the constant for your Rodauth app, which will
-be called by the Rack middleware that's added in front of your Rails router.
-
-```rb
-# config/initializers/rodauth.rb
-Rodauth::Rails.configure do |config|
-  config.app = "RodauthApp"
-end
-```
-
-### Sequel initializer
-
-Rodauth uses [Sequel] for database interaction. If you're using ActiveRecord,
-an additional initializer will be created which configures Sequel to use the
-ActiveRecord connection.
-
-```rb
-# config/initializers/sequel.rb
-require "sequel/core"
-
-# initialize Sequel and have it reuse Active Record's database connection
-DB = Sequel.connect("postgresql://", extensions: :activerecord_connection)
-```
-
-### Rodauth app
-
-Your Rodauth app is created in the `app/lib/` directory, and comes with a
-default set of authentication features enabled, as well as extensive examples
-on ways you can configure authentication behaviour.
-
-```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  configure do
-    # authentication configuration
-  end
-
-  route do |r|
-    # request handling
-  end
-end
-```
-
-### Controller
-
-Your Rodauth app will by default use `RodauthController` for view rendering,
-CSRF protection, and running controller callbacks and rescue handlers around
-Rodauth actions.
-
-```rb
-# app/controllers/rodauth_controller.rb
-class RodauthController < ApplicationController
-end
-```
-
-### Account model
-
-Rodauth stores user accounts in the `accounts` table, so the generator will
-also create an `Account` model for custom use.
-
-```rb
-# app/models/account.rb
-class Account < ApplicationRecord
-end
-```
-
 ## Usage
 
 ### Routes
 
-We can see the list of routes our Rodauth middleware handles:
+You can see the list of routes our Rodauth middleware handles:
 
 ```sh
 $ rails rodauth:routes
@@ -237,7 +111,7 @@ Routes handled by RodauthApp:
   /close-account           rodauth.close_account_path
 ```
 
-Using this information, we could add some basic authentication links to our
+Using this information, you can add some basic authentication links to your
 navigation header:
 
 ```erb
@@ -253,9 +127,22 @@ 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
 
-To be able to fetch currently authenticated account, let's define a
+To be able to fetch currently authenticated account, you can define a
 `#current_account` method that fetches the account id from session and
 retrieves the corresponding account record:
 
@@ -272,11 +159,11 @@ class ApplicationController < ActionController::Base
     rodauth.logout
     rodauth.login_required
   end
-  helper_method :current_account
+  helper_method :current_account # skip if inheriting from ActionController::API
 end
 ```
 
-This allows us to access the current account in controllers and views:
+This allows you to access the current account in controllers and views:
 
 ```erb
 <p>Authenticated as: <%= current_account.email %></p>
@@ -284,9 +171,9 @@ This allows us to access the current account in controllers and views:
 
 ### Requiring authentication
 
-We'll likely want to require authentication for certain parts of our app,
-redirecting the user to the login page if they're not logged in. We can do this
-in our Rodauth app's routing block, which helps keep the authentication logic
+You'll likely want to require authentication for certain parts of your app,
+redirecting the user to the login page if they're not logged in. You can do this
+in your Rodauth app's routing block, which helps keep the authentication logic
 encapsulated:
 
 ```rb
@@ -305,7 +192,7 @@ class RodauthApp < Rodauth::Rails::App
 end
 ```
 
-We can also require authentication at the controller layer:
+You can also require authentication at the controller layer:
 
 ```rb
 # app/controllers/application_controller.rb
@@ -330,15 +217,52 @@ class PostsController < ApplicationController
 end
 ```
 
-Or at the Rails router level:
+#### Routing constraints
+
+In some cases it makes sense to require authentication at the Rails router
+level. You can do this via the built-in `authenticated` routing constraint:
 
 ```rb
 # config/routes.rb
 Rails.application.routes.draw do
-  constraints -> (r) { r.env["rodauth"].require_authentication } do
-    namespace :admin do
-      # ...
-    end
+  constraints Rodauth::Rails.authenticated do
+    # ... authenticated routes ...
+  end
+end
+```
+
+If you want additional conditions, you can pass in a block, which is
+called with the Rodauth instance:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  # require multifactor authentication to be setup
+  constraints Rodauth::Rails.authenticated { |rodauth| rodauth.uses_two_factor_authentication? } do
+    # ...
+  end
+end
+```
+
+You can specify the Rodauth configuration by passing the configuration name:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  constraints Rodauth::Rails.authenticated(:admin) do
+    # ...
+  end
+end
+```
+
+If you need something more custom, you can always create the routing constraint
+manually:
+
+```rb
+# config/routes.rb
+Rails.application.routes.draw do
+  constraints -> (r) { !r.env["rodauth"].logged_in? } do # or "rodauth.admin"
+    # routes when the user is not logged in
   end
 end
 ```
@@ -354,11 +278,11 @@ $ rails generate rodauth:views
 ```
 
 This will generate views for the default set of Rodauth features into the
-`app/views/rodauth` directory, which will be automatically picked up by the
-`RodauthController`.
+`app/views/rodauth` directory, provided that `RodauthController` is set for the
+main configuration.
 
 You can pass a list of Rodauth features to the generator to create views for
-these features (this will not remove any existing views):
+these features (this will not remove or overwrite any existing views):
 
 ```sh
 $ rails generate rodauth:views login create_account lockout otp
@@ -370,12 +294,10 @@ Or you can generate views for all features:
 $ rails generate rodauth:views --all
 ```
 
-You can also tell the generator to create views into another directory (in this
-case make sure to rename the Rodauth controller accordingly):
+Use `--name` to generate views for a different Rodauth configuration:
 
 ```sh
-# generates views into app/views/authentication
-$ rails generate rodauth:views --name authentication
+$ rails generate rodauth:views --name admin
 ```
 
 #### Layout
@@ -406,58 +328,36 @@ end
 
 ### Mailer
 
-Depending on the features you've enabled, Rodauth may send emails as part of
-the authentication flow. Most email settings can be customized:
+The install generator will create `RodauthMailer` with default email templates,
+and configure Rodauth features that send emails as part of the authentication
+flow to use it.
 
 ```rb
-# app/lib/rodauth_app.rb
-class RodauthApp < Rodauth::Rails::App
-  # ...
-  configure do
+# app/mailers/rodauth_mailer.rb
+class RodauthMailer < ApplicationMailer
+  def verify_account(recipient, email_link)
     # ...
-    # general settings
-    email_from "no-reply@myapp.com"
-    email_subject_prefix "[MyApp] "
-    send_email(&:deliver_later)
+  end
+  def reset_password(recipient, email_link)
     # ...
-    # feature settings
-    verify_account_email_subject "Verify your account"
-    verify_account_email_body { "Verify your account by visting this link: #{verify_account_email_link}" }
+  end
+  def verify_login_change(recipient, old_login, new_login, email_link)
     # ...
   end
+  def password_changed(recipient)
+    # ...
+  end
+  # def email_auth(recipient, email_link)
+  # ...
+  # end
+  # def unlock_account(recipient, email_link)
+  # ...
+  # end
 end
 ```
-
-This is convenient when starting out, but eventually you might want to use your
-own mailer. You can start by running the following command:
-
-```sh
-$ rails generate rodauth:mailer
-```
-
-This will create a `RodauthMailer` with the associated mailer views in
-`app/views/rodauth_mailer` directory:
-
-```rb
-# app/mailers/rodauth_mailer.rb
-class RodauthMailer < ApplicationMailer
-  def verify_account(recipient, email_link) ... end
-  def reset_password(recipient, email_link) ... end
-  def verify_login_change(recipient, old_login, new_login, email_link) ... end
-  def password_changed(recipient) ... end
-  # def email_auth(recipient, email_link) ... end
-  # def unlock_account(recipient, email_link) ... end
-end
-```
-
-You can then uncomment the lines in your Rodauth configuration to have it call
-your mailer. If you've enabled additional authentication features that send
-emails, make sure to override their `create_*_email` methods as well.
-
 ```rb
 # app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  # ...
   configure do
     # ...
     create_reset_password_email do
@@ -487,10 +387,51 @@ class RodauthApp < Rodauth::Rails::App
 end
 ```
 
-This approach can be used even if you're using a 3rd-party service for
-transactional emails, where emails are sent via HTTP instead of SMTP. Whatever
-the `create_*_email` block returns will be passed to `send_email`, so you can
-be creative.
+This configuration calls `#deliver_later`, which uses Active Job to deliver
+emails in a background job. It's generally recommended to send emails
+asynchronously for better request throughput and the ability to retry
+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
+```
 
 ### Migrations
 
@@ -515,7 +456,7 @@ end
 ### Multiple configurations
 
 If you need to handle multiple types of accounts that require different
-authentication logic, you can create different configurations for them:
+authentication logic, you can create additional configurations for them:
 
 ```rb
 # app/lib/rodauth_app.rb
@@ -536,7 +477,12 @@ class RodauthApp < Rodauth::Rails::App
 
   route do |r|
     r.rodauth
-    r.on("admin") { r.rodauth(:admin) }
+
+    r.on "admin" do
+      r.rodauth(:admin)
+      break # allow routing of other /admin/* requests to continue to Rails
+    end
+
     # ...
   end
 end
@@ -548,6 +494,142 @@ Then in your application you can reference the secondary Rodauth instance:
 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
+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
+```
+
+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:
+
+```rb
+# app/lib/rodauth_base.rb
+class RodauthBase < Rodauth::Rails::Auth
+  # common settings that can be shared between multiple configurations
+  configure do
+    enable :login, :logout
+    login_return_to_requested_location? true
+    logout_redirect "/"
+    # ...
+  end
+end
+```
+```rb
+# app/lib/rodauth_main.rb
+class RodauthMain < RodauthBase # inherit common settings
+  configure do
+    # ... customize main ...
+  end
+end
+```
+```rb
+# app/lib/rodauth_admin.rb
+class RodauthAdmin < RodauthBase # inherit common settings
+  configure do
+    # ... customize admin ...
+  end
+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
@@ -577,8 +659,8 @@ end
 ### Rodauth instance
 
 In some cases you might need to use Rodauth more programmatically, and perform
-Rodauth operations outside of the request context. rodauth-rails gives you the
-ability to retrieve the Rodauth instance:
+Rodauth operations outside of the request context. rodauth-rails gives you a
+helper method for building a Rodauth instance:
 
 ```rb
 rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:admin)
@@ -590,8 +672,22 @@ rodauth.setup_account_verification
 rodauth.close_account
 ```
 
-This Rodauth instance will be initialized with basic Rack env that allows is it
-to generate URLs, using `config.action_mailer.default_url_options` options.
+The base URL is taken from Action Mailer's `default_url_options` setting if
+configured. The `Rodauth::Rails.rodauth` method accepts additional keyword
+arguments:
+
+* `:account` – Active Record model instance from which to set `account` and `session[:account_id]`
+* `:query` & `:form` – set specific query/form parameters
+* `:session` – set any session values
+* `:env` – set any additional Rack env values
+
+```rb
+Rodauth::Rails.rodauth(account: Account.find(account_id))
+Rodauth::Rails.rodauth(query: { "param" => "value" })
+Rodauth::Rails.rodauth(form: { "param" => "value" })
+Rodauth::Rails.rodauth(session: { two_factor_auth_setup: true })
+Rodauth::Rails.rodauth(env: { "HTTP_USER_AGENT" => "programmatic" })
+```
 
 ## How it works
 
@@ -702,7 +798,7 @@ class RodauthApp < Rodauth::Rails::App
   configure do
     # ...
     enable :json
-    only_json? true # accept only JSON requests
+    only_json? true # accept only JSON requests (optional)
     # ...
   end
 end
@@ -723,7 +819,7 @@ class RodauthApp < Rodauth::Rails::App
     # ...
     enable :jwt
     jwt_secret "<YOUR_SECRET_KEY>" # store the JWT secret in a safe place
-    only_json? true # accept only JSON requests
+    only_json? true # accept only JSON requests (optional)
     # ...
   end
 end
@@ -803,7 +899,8 @@ end
 <%= link_to "Login via Facebook", "/auth/facebook" %>
 ```
 
-Let's implement the OmniAuth callback endpoint on our Rodauth controller:
+Finally, let's implement the OmniAuth callback endpoint on our Rodauth
+controller:
 
 ```rb
 # config/routes.rb
@@ -856,11 +953,8 @@ end
 
 ## Configuring
 
-For the list of configuration methods provided by Rodauth, see the [feature
-documentation].
-
-The `rails` feature rodauth-rails loads is customizable as well, here is the
-list of its configuration methods:
+The `rails` feature rodauth-rails loads provides the following configuration
+methods:
 
 | Name                        | Description                                                        |
 | :----                       | :----------                                                        |
@@ -887,12 +981,16 @@ Rodauth::Rails.configure do |config|
 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
-better to use plain modules (at least in the beginning), because Rodauth
-feature design doesn't yet support Zeitwerk reloading well. Here is
-an example of an LDAP authentication extension that uses the
+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.
 
 ```rb
@@ -922,48 +1020,156 @@ end
 
 ## Testing
 
-If you're writing system tests, it's generally better to go through the actual
-authentication flow with tools like Capybara, and to not use any stubbing.
-
-In functional and integration tests you can just make requests to Rodauth
-routes:
+System (browser) tests for Rodauth actions could look something like this:
 
 ```rb
-# test/controllers/posts_controller_test.rb
-class PostsControllerTest < ActionDispatch::IntegrationTest
-  test "should require authentication" do
-    get posts_url
-    assert_redirected_to "/login"
+# 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
-    get posts_url
+    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"
+  end
+
+  def logout
+    visit "/logout"
+    click_on "Logout"
+  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_redirected_to "/login"
+    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"]
   end
 
   private
 
-  def login(login: "user@example.com", password: "secret")
-    post "/create-account", params: {
-      "login"            => login,
-      "password"         => password,
-      "password-confirm" => password,
-    }
-
-    post "/login", params: {
-      "login"    => login,
-      "password" => password,
-    }
+  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
+
+  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
+
+  def login(email: "user@example.com", password: "secret")
+    post "/login", as: :json, params: { login: email, password: password }
   end
 
   def logout
-    post "/logout"
+    post "/logout", as: :json, headers: { "Authorization" => headers["Authorization"] }
   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
+```
+
+If you need to create an account record with a password directly, you can do it
+as follows:
+
+```rb
+# app/models/account.rb
+class Account < ApplicationRecord
+  has_one :password_hash, foreign_key: :id
+end
+```
+```rb
+# app/models/account/password_hash.rb
+class Account::PasswordHash < ApplicationRecord
+  belongs_to :account, foreign_key: :id
+end
+```
+```rb
+require "bcrypt"
+
+account = Account.create!(email: "user@example.com", status: "verified")
+password_hash = BCrypt::Password.create("secret", cost: BCrypt::Engine::MIN_COST)
+account.create_password_hash!(id: account.id, password_hash: password_hash)
+```
+
 ## Rodauth defaults
 
 rodauth-rails changes some of the default Rodauth settings for easier setup:
@@ -1044,6 +1250,18 @@ configure do
 end
 ```
 
+### Deadline values
+
+To simplify changes to the database schema, rodauth-rails configures Rodauth
+to set deadline values for various features in Ruby, instead of relying on
+the database to set default column values.
+
+You can easily change this back:
+
+```rb
+set_deadline_values? false
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT