rodauth-rails 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f1312dbd1bb4dc0d954c77a5ff350b5c9e1ff3fc4dd45b8834cd3e7d0280a22
-  data.tar.gz: 5dda5720126361589a428add9b8256b35aa53644166ca7a8a6d14c5baef53f02
+  metadata.gz: 4cc138f57505a1bbf92267e02b8d9b87f50c0dd9b6c114891f649c0b15878637
+  data.tar.gz: 28fc8264a8629dd186a446a4d067167d572f8ea58b65c742f12f81a5192221db
 SHA512:
-  metadata.gz: f70e5a44db25c016fe92169be342d1f489cd0e3307fe6c06dbe822c28c05f55dc696b26721836d315daabbbfb0889d18357cec3bb7aa52932649f5ecb08ceedb
-  data.tar.gz: 6af3cd43f9266729049d984c9da58beff019dd2f0148465d65c8f814602d9a9678308d752ef469f08ab381a1373b919d1e61b62b204751d95ca57d10ed05de2a
+  metadata.gz: 74645990b10677d44503f272a63300465881c6e596b514ce0e1d1607689d8ace60c5e70a79c952256ad73bf704a8d268e27af3da8cdb617c5b381f752b302c4b
+  data.tar.gz: 1525c4a51d4323e348ee2dc117e5ef320214f42f385549f5646af1d8e1792bfeac2be3f220b473873aed8fc72f4448aade9848b82fdd2c348874f8b4950e4631

data/CHANGELOG.md

@@ -1,3 +1,49 @@
+## 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)
+
+* Change account status column default to `unverified` in migration to match Rodauth's default (@basabin54)
+
+## 0.9.0 (2021-02-07)
+
+* Load Roda's JSON support by default, so that enabling `json`/`jwt` feature is all that's needed (@janko)
+
+* Bump Rodauth dependency to 2.9+ (@janko)
+
+* Add `--json` option for `rodauth:install` generator for configuring `json` feature (@janko)
+
+* Add `--jwt` option for `rodauth:install` generator for configuring `jwt` feature (@janko)
+
+* Remove the `--api` option from `rodauth:install` generator (@janko)
+
+## 0.8.2 (2021-01-10)
+
+* Reset Rails session on `#clear_session`, protecting from potential session fixation attacks (@janko)
+
+## 0.8.1 (2021-01-04)
+
+* Fix blank email body when `json: true` and `ActionController::API` descendant are used (@janko)
+
+* Make view and email rendering work when there are multiple configurations and one is `json: :only` (@janko)
+
+* Don't attempt to protect against forgery when `ActionController::API` descendant is used (@janko)
+
+* Mark content of rodauth built-in partials as HTML-safe (@janko)
+
 ## 0.8.0 (2021-01-03)
 
 * Add `--api` option to `rodauth:install` generator for choosing JSON-only configuration (@janko)

data/README.md

@@ -2,6 +2,35 @@
 
 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:
@@ -18,11 +47,11 @@ Articles:
 ## Why Rodauth?
 
 There are already several popular authentication solutions for Rails (Devise,
-Sorcery, Clearance, Authlogic), so why would you choose Rodauth? Well, because
-it has many advantages over the mentioned alternatives:
+Sorcery, Clearance, Authlogic), so why would you choose Rodauth? Here are some
+of the advantages that stand out for me:
 
 * multifactor authentication ([TOTP][otp], [SMS codes][sms_codes], [recovery codes][recovery_codes], [WebAuthn][webauthn])
-* standardized [JSON API support][jwt] (for every feature)
+* standardized [JSON API support][json] for every feature (including [JWT][jwt])
 * enterprise security features ([password complexity][password_complexity], [disallow password reuse][disallow_password_reuse], [password expiration][password_expiration], [session expiration][session_expiration], [single session][single_session], [account expiration][account_expiration])
 * [email authentication][email_auth] (aka "passwordless")
 * [audit logging][audit_logging] (for any action)
@@ -54,7 +83,7 @@ documentation][hmac] for instructions on how to safely transition, or just set
 Add the gem to your Gemfile:
 
 ```rb
-gem "rodauth-rails", "~> 0.6"
+gem "rodauth-rails", "~> 0.10"
 
 # gem "jwt",      require: false # for JWT feature
 # gem "rotp",     require: false # for OTP feature
@@ -73,7 +102,9 @@ $ rails generate rodauth:install
 Or if you want Rodauth endpoints to be exposed via JSON API:
 
 ```sh
-$ rails generate rodauth:install --api
+$ rails generate rodauth:install --json # regular authentication using the Rails session
+# or
+$ rails generate rodauth:install --jwt # token authentication via the "Authorization" header
 $ bundle add jwt
 ```
 
@@ -85,6 +116,7 @@ The generator will create the following files:
 * Rodauth app at `app/lib/rodauth_app.rb`
 * Rodauth controller at `app/controllers/rodauth_controller.rb`
 * Account model at `app/models/account.rb`
+* Rodauth mailer at `app/mailers/rodauth_mailer.rb` with views
 
 ### Migration
 
@@ -180,6 +212,23 @@ class Account < ApplicationRecord
 end
 ```
 
+### Rodauth mailer
+
+The default Rodauth app is configured to use `RodauthMailer` mailer
+for sending authentication emails.
+
+```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
+```
+
 ## Usage
 
 ### Routes
@@ -241,7 +290,7 @@ 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
 ```
 
@@ -299,15 +348,52 @@ class PostsController < ApplicationController
 end
 ```
 
-Or at the Rails router level:
+#### Routing constraints
+
+You can also require authentication at the Rails router level by
+using a 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
 ```
@@ -375,54 +461,33 @@ 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
@@ -456,10 +521,17 @@ 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.
+The above configuration uses `#deliver_later`, which assumes Active Job is
+configured. It's generally recommended to send emails in a background job,
+for better throughput and ability to retry. However, if you want to send emails
+synchronously, you can modify the code to call `#deliver` instead.
+
+The `#send_email` method will receive whatever object is returned by the
+`#create_*_email` methods. But if that doesn't suit you, you can override
+`#send_*_email` methods instead, which are expected to send the email
+immediately. This might work better in scenarios such as using a 3rd-party
+service for transactional emails, where emails are sent via HTTP instead of
+SMTP.
 
 ### Migrations
 
@@ -481,6 +553,142 @@ class CreateRodauthOtpSmsCodesRecoveryCodes < ActiveRecord::Migration
 end
 ```
 
+### Multiple configurations
+
+If you need to handle multiple types of accounts that require different
+authentication logic, you can create different configurations for them:
+
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  # primary configuration
+  configure do
+    # ...
+  end
+
+  # alternative configuration
+  configure(:admin) do
+    # ... enable features ...
+    prefix "/admin"
+    session_key_prefix "admin_"
+    remember_cookie_key "_admin_remember" # if using remember feature
+
+    # if you want separate tables
+    accounts_table :admin_accounts
+    password_hash_table :admin_account_password_hashes
+    # ...
+  end
+
+  route do |r|
+    r.rodauth
+
+    r.on "admin" do
+      r.rodauth(:admin)
+      r.pass # allow the Rails app to handle other "/admin/*" requests
+    end
+    # ...
+  end
+end
+```
+
+Then in your application you can reference the secondary Rodauth instance:
+
+```rb
+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`:
+
+```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::App
+  # 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 is that you can define custom methods directly on the class
+instead of through `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).any? { |role| role.name == "superadmin" }
+  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
@@ -514,7 +722,7 @@ Rodauth operations outside of the request context. rodauth-rails gives you the
 ability to retrieve the Rodauth instance:
 
 ```rb
-rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:secondary)
+rodauth = Rodauth::Rails.rodauth # or Rodauth::Rails.rodauth(:admin)
 
 rodauth.login_url #=> "https://example.com/login"
 rodauth.account_from_login("user@example.com") # loads user by email
@@ -545,8 +753,8 @@ The Rodauth app stores the `Rodauth::Auth` instance in the Rack env hash, which
 is then available in your Rails app:
 
 ```rb
-request.env["rodauth"]           #=> #<Rodauth::Auth>
-request.env["rodauth.secondary"] #=> #<Rodauth::Auth> (if using multiple configurations)
+request.env["rodauth"]       #=> #<Rodauth::Auth>
+request.env["rodauth.admin"] #=> #<Rodauth::Auth> (if using multiple configurations)
 ```
 
 For convenience, this object can be accessed via the `#rodauth` method in views
@@ -555,14 +763,14 @@ and controllers:
 ```rb
 class MyController < ApplicationController
   def my_action
-    rodauth             #=> #<Rodauth::Auth>
-    rodauth(:secondary) #=> #<Rodauth::Auth> (if using multiple configurations)
+    rodauth         #=> #<Rodauth::Auth>
+    rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations)
   end
 end
 ```
 ```erb
-<% rodauth             #=> #<Rodauth::Auth> %>
-<% rodauth(:secondary) #=> #<Rodauth::Auth> (if using multiple configurations) %>
+<% rodauth         #=> #<Rodauth::Auth> %>
+<% rodauth(:admin) #=> #<Rodauth::Auth> (if using multiple configurations) %>
 ```
 
 ### App
@@ -584,7 +792,7 @@ any additional [plugin options].
 class RodauthApp < Rodauth::Rails::App
   configure { ... }             # defining default Rodauth configuration
   configure(json: true) { ... } # passing options to the Rodauth plugin
-  configure(:secondary) { ... } # defining multiple Rodauth configurations
+  configure(:admin) { ... }     # defining multiple Rodauth configurations
 end
 ```
 
@@ -619,15 +827,32 @@ 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).
+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
 
-JSON API support in Rodauth is provided by the [JWT feature][jwt]. You'll need
-to install the [JWT gem], enable JSON support and enable the JWT feature:
+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
+    # ...
+  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
@@ -635,23 +860,33 @@ $ bundle add jwt
 ```rb
 # app/lib/rodauth_app.rb
 class RodauthApp < Rodauth::Rails::App
-  configure(json: :only) do
+  configure do
     # ...
     enable :jwt
-    # make sure to store the JWT secret below in a safe place
-    jwt_secret "...your secret key..."
+    jwt_secret "<YOUR_SECRET_KEY>" # store the JWT secret in a safe place
+    only_json? true # accept only JSON requests
     # ...
   end
 end
 ```
 
-With the above configuration, Rodauth routes will only be accessible via JSON
-requests. If you still want to allow HTML access alongside JSON, change `json:
-:only` to `json: true`.
+If you need Cross-Origin Resource Sharing and/or JWT refresh tokens, enable the
+corresponding Rodauth features and create the necessary tables:
 
-Emails will automatically work in JSON-only mode, because `Rodauth::Rails::App`
-comes with Roda's `render` plugin loaded. They are customized the same as in
-the non-JSON case.
+```sh
+$ rails generate rodauth:migration jwt_refresh
+$ rails db:migrate
+```
+```rb
+# app/lib/rodauth_app.rb
+class RodauthApp < Rodauth::Rails::App
+  configure do
+    # ...
+    enable :jwt, :jwt_cors, :jwt_refresh
+    # ...
+  end
+end
+```
 
 ## OmniAuth
 
@@ -745,7 +980,7 @@ class RodauthController < ApplicationController
 
     # create new account if it doesn't exist
     unless account
-      account = Account.create!(email: auth["info"]["email"])
+      account = Account.create!(email: auth["info"]["email"], status: rodauth.account_open_status_value)
     end
 
     # create new identity if it doesn't exist
@@ -797,17 +1032,19 @@ end
 
 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 API doesn't yet support Zeitwerk reloading well.
+feature design doesn't yet support Zeitwerk reloading well. Here is
+an example of an LDAP authentication extension that uses the
+[simple_ldap_authenticator] gem.
 
 ```rb
-# app/lib/rodauth_argon2.rb
-module RodauthArgon2
-  def password_hash(password)
-    Argon2::Password.create(password, t_cost: password_hash_cost, m_cost: password_hash_cost)
+# app/lib/rodauth_ldap.rb
+module RodauthLdap
+  def require_bcrypt?
+    false
   end
 
-  def password_hash_match?(hash, password)
-    Argon2::Password.verify_password(password, hash)
+  def password_match?(password)
+    SimpleLdapAuthenticator.valid?(account[:email], password)
   end
 end
 ```
@@ -817,7 +1054,7 @@ class RodauthApp < Rodauth::Rails::App
   configure do
     # ...
     auth_class_eval do
-      include RodauthArgon2
+      include RodauthLdap
     end
     # ...
   end
@@ -826,48 +1063,147 @@ 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,
-    }
+  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
 
-    post "/login", params: {
-      "login"    => login,
-      "password" => password,
-    }
+  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`:
+
+```rb
+# config/environments/test.rb
+Rails.application.configure do |config|
+  # ...
+  config.active_job.queue_adapter = :test
+  # ...
+end
+```
+
+If you need to create the account manually, you can do it as follows:
+
+```rb
+account_id = DB[:accounts].insert(
+  email: "user@example.com",
+  status: "verified",
+)
+
+DB[:account_password_hashes].insert(
+  account_id: account_id,
+  password_hash: BCrypt::Password.create("secret", cost: BCrpyt::Engine::MIN_COST),
+)
+```
+
 ## Rodauth defaults
 
 rodauth-rails changes some of the default Rodauth settings for easier setup:
@@ -976,6 +1312,7 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [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
 [webauthn]: http://rodauth.jeremyevans.net/rdoc/files/doc/webauthn_rdoc.html
+[json]: http://rodauth.jeremyevans.net/rdoc/files/doc/json_rdoc.html
 [jwt]: http://rodauth.jeremyevans.net/rdoc/files/doc/jwt_rdoc.html
 [email_auth]: http://rodauth.jeremyevans.net/rdoc/files/doc/email_auth_rdoc.html
 [audit_logging]: http://rodauth.jeremyevans.net/rdoc/files/doc/audit_logging_rdoc.html
@@ -987,3 +1324,4 @@ conduct](https://github.com/janko/rodauth-rails/blob/master/CODE_OF_CONDUCT.md).
 [session_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/session_expiration_rdoc.html
 [single_session]: http://rodauth.jeremyevans.net/rdoc/files/doc/single_session_rdoc.html
 [account_expiration]: http://rodauth.jeremyevans.net/rdoc/files/doc/account_expiration_rdoc.html
+[simple_ldap_authenticator]: https://github.com/jeremyevans/simple_ldap_authenticator