Configuration

Set these values inside AddAuth.configure in config/initializers/add_auth.rb. This reference covers the documented 0.5.1 behavior.

Create and edit the configuration file

After installing the gem and preparing Rails authentication, run this primary setup command from your Rails app’s root:

bin/rails generate add_auth:install

It creates config/initializers/add_auth.rb if absent and runs doctor. Open that file and edit settings inside its existing AddAuth.configure do |config| block. Omitted settings retain their defaults. Install enables no optional features and never replaces an existing initializer.

Defaults are active; alternatives are commented

The generated file covers every settings group. Edit the existing assignment when choosing an alternative, and install the feature prerequisites before enabling it. Follow configuration setup for examples and existing-app upgrades.

Captcha, provider and mobile generators also write integration examples in config/initializers/add_auth_challenge.rb, add_auth_providers.rb and add_auth_mobile.rb. Keep each setting in one active location: a later initializer can override an earlier assignment. Provider middleware and Rails mail/job configuration still need their own setup.

Enable the features you need

Run the feature generator, review the file and migration diff, apply migrations with bin/rails db:migrate, configure required values, restart the app and run bin/rails add_auth:doctor. A boolean alone cannot create the database tables, routes or host wiring. Follow each linked guide to verify the actual user flow.

Feature and generator after `bin/rails generate`	Enablement and required setup
Password sign-in and sessions `add_auth:session_upgrade`	Sets `session.enabled = true`. Keep `passwords_enabled = true`; choose session limits, account eligibility and an atomic counter store. Verify `/sign-in` and `/sessions`.
Email-link sign-in `add_auth:email_link`	Enables sessions and `email_link.enabled`. Set `base_url`, `mail_from`, Action Mailer, jobs and the delivery sweep. Request and consume a real delivered link.
Reauthentication `add_auth:step_up`	Enables sessions, email links and `step_up.enabled`. Configure named purposes and enforce fresh proof in each protected write. Use `--no-email-link` for password-only dependency setup.
Passkeys and recovery `add_auth:passkeys`	Enables sessions, email links, reauthentication, notifications and `passkeys.enabled`. Set RP ID, exact origins, mail and counters. Configure trusted recovery and a support path before strict policy. Enroll and sign in with a passkey.
Security emails `add_auth:notifications`	Enables sessions and `notifications.enabled`. Configure sender, delivery, jobs and maintenance. Trigger a supported account change and inspect its delivered notice.
Registration and account management `add_auth:accounts`	Prepares account tables/routes and enables notification and step-up dependencies. Review host callbacks and account states, then set `lifecycle.enabled = true`. Email confirmation is required by default; optional password signup is an explicit host choice. Test signup, confirmation, reset and account changes.
Captcha `add_auth:challenge turnstile` or `add_auth:challenge recaptcha --version=v2`	Configure the generated provider initializer, keys and allowed hostnames. Select `challenge_on` actions and outage policy. Test accepted, rejected and unavailable checks.
Provider sign-in `add_auth:external_identities`	Prepare sessions and reauthentication first. Configure maintained provider libraries, middleware, verified mappings and explicit registrations, then set `external_identities.enabled = true`. Enrollment also needs lifecycle. Verify callbacks and existing provider routes.
Native sessions `add_auth:mobile_sessions`	Prepare hardened sessions first. Set finite `mobile.lifetime`, `idle_timeout`, registered `clients` and `mobile.enabled = true`. Provider handoffs require provider setup and exact callbacks. Test with your actual clients.

App-owned registration, roles and onboarding remain available without AddAuth lifecycle. Presentation can be changed through stylesheet, css_classes or view ejection; it does not require enabling another sign-in method.

Host settings

Database primary-key selection is separate from this initializer. The UUID and integer key guide explains the Rails generator setting for all authentication tables, including UUID sessions in 0.5.0 and existing mixed schemas.

Setting	Default / requirement	Purpose
`base_url`	Host must configure	Public origin used for sign-in links; HTTPS outside a local trial.
`mail_from`	Host must configure	Sender address for sign-in mail.
`rate_limit_store`	`Rails.cache` fallback	Shared atomic counters with expiry; Solid Cache is unsuitable.
`eligible`	Permits matching accounts	Callback for your confirmed/locked/disabled account policy.

For a host whose account model implements these predicates, eligibility could be:

config.eligible = ->(user) { user.confirmed? && !user.disabled? }

Adapt this to your model; AddAuth does not define those methods. The callback must reflect the policy you use for sign-in.

Passwordless operation

passwords_enabled defaults to true, preserving Rails password authentication. To use only email links and passkeys, enable the methods your app needs, then set:

config.passwords_enabled = false

Restart the app. AddAuth rejects password verification and password proof and hides password controls. An installed Rails SessionsController continues to use the shared guarded entry; a host that removes it owns its replacement routes. Rails password reset and account provisioning remain your app’s responsibility. Keep the conventional User and Session models, Rails email normalization and a shared authentication database connection pool.

Verify that email or passkey sign-in works, that password submissions are rejected, and that anonymous visitors cannot access sessions, passkey management or reauthentication pages. This setting never relaxes strict account policy.

Account lifecycle

These defaults apply after preparing the account feature. Callback examples assume your app implements the methods used. General eligible and lifecycle eligibility both apply alongside AddAuth account policy.

Setting	Default	Meaning
`lifecycle.enabled`	`false`	Enable manually after schema, delivery and policy review.
`lifecycle.confirmation_required`	`true`	Explicit `false` permits eligible password signup and sign-in before confirmation. Requires the additive provisioning receipt migration; the address stays unverified.
`lifecycle.reset_unconfirmed`	`false`	Separate opt-in to current-mailbox password reset for an unconfirmed password account. Requires optional confirmation. Reset never confirms or signs in the user.
`lifecycle.password_policy`	At least 12 characters, at most 72 bytes	Callable receiving a password and returning whether it is acceptable.
`lifecycle.eligible`	`->(_user) { true }`	Additional host account eligibility.
`lifecycle.profile_attributes`	`->(_profile) { {} }`	Allowlisted profile mapping. Also allowlist inputs in your controller; never accept roles or authentication fields.
`lifecycle.provision`	`->(_user) {}`	Local onboarding writes in the account transaction: after required confirmation, or during optional-confirmation password signup. Raise on failure; use the same database pool. Put remote work behind a host transactional outbox.
`lifecycle.maximum_attempts`	`20`	Failed-password threshold for the automatic lock, which blocks only password sign-in; integer 1–100.
`lifecycle.unlock_in`	`3600` seconds	Timed lock duration; 60–86,400 seconds. A successful password reset also clears a timed lock. Does not clear manual locks.
`lifecycle.proof_lifetime`	`3600` seconds	Account proof lifetime; 60–86,400 seconds.
`lifecycle.remember_lifetime`	`1_209_600` seconds	Remembered browser session absolute limit: 14 days.
`lifecycle.remember_idle_timeout`	`604_800` seconds	Remembered session inactivity limit: 7 days; must not exceed its absolute limit.
`lifecycle.deletion_allowed`	`->(_user) { true }`	Host authorization and retention policy for deletion.
`lifecycle.delete_account`	`->(user) { user.destroy! }`	Local deletion in the shared transaction. Raise on failure.

Follow optional-confirmation setup before changing confirmation or unconfirmed-reset policy. These options were introduced in 0.4.0; older packages do not support them.

Sessions

Setting	Default	Meaning
`session.enabled`	`false`	Enabled by the session adoption generator.
`session.lifetime`	`43_200` seconds	Absolute lifetime: 12 hours.
`session.idle_timeout`	`1_800` seconds	Idle lifetime: 30 minutes.
`session.legacy_bridge_until`	Unset	Explicit cutoff for migration of old signed-ID sessions.

Email links

Setting	Default	Meaning
`email_link.enabled`	`false`	Enabled by the email-link generator.
`email_link.token_lifetime`	`1_200` seconds	Link validity: 20 minutes.
`email_link.same_browser`	`false`	Require the requesting browser when enabled.

Rails duration helpers work here: config.email_link.token_lifetime = 10.minutes.

Passkeys and recovery

Setting	Default	Meaning
`passkeys.enabled`	`false`	Enabled by the passkey generator, which installs its prerequisites.
`passkeys.rp_id`	Unset	Stable relying-party domain. Required for passkeys.
`passkeys.origins`	`[]`	Exact allowed origins within the RP ID. Use HTTPS except for loopback development.
`passkeys.name`	`"Your account"`	Display name used in the browser's passkey prompt.
`passkeys.anonymous_limit`	`1000`	Positive integer limiting anonymous passkey ceremonies per IPv4 address or IPv6 /64 every five minutes. Before 0.5.1 it was one shared budget. Review against your traffic and cleanup capacity.
`trusted_recovery_address`	Callback returning `nil`	Return the verified current account email address or `nil`. Your app owns address verification.
`support_url`	Unset	Safe local path to your real support process. Required when strict accounts exist.

Follow passkey setup and recovery and strict policy before changing these values. Recovery email lifetime is fixed at 20 minutes; its replacement grant uses step_up.fresh_for.

Reauthentication

Setting	Default	Meaning
`step_up.enabled`	`false`	Enabled by the step-up or passkey generator.
`step_up.purposes`	`{}`	Your named actions, allowed methods, labels and safe return pages. AddAuth also supplies purposes for its own account actions.
`step_up.fresh_for`	`600` seconds	General proof freshness window.
`step_up.strong_for`	`300` seconds	Verified passkey freshness window. Must not exceed `fresh_for`.

Both windows must be finite positive durations. Email reauthentication links have a separate fixed five-minute lifetime. A purpose accepts methods from :password, :email_link and :passkey; require_passkey: true restricts proof to verified passkeys. Use label for the user-facing action and return_to for a fixed local GET review page. See the complete purpose example.

Security notifications

notifications.enabled defaults to false. The notification or passkey generator enables it. Notifications use mail_from and your Action Mailer transport and Active Job backend. Unsent notification payloads expire after seven days; this expiry is fixed. See security email setup.

Maintenance

Setting	Default	Meaning
`maintenance.batch_size`	`100`	Rows per operation and model in one scheduled pass; integer 1–1000.
`maintenance.session_retention`	`nil`	Seconds after expiry or revocation before deleting session history.
`maintenance.email_retention`	`nil`	Seconds after token expiry before deleting email receipts.
`maintenance.notification_retention`	`nil`	Seconds after notice expiry before deleting notification receipts.
`maintenance.account_retention`	`nil`	Seconds after expiry before deleting account proof receipts, excluding active delivery leases.

Retention durations must be nonnegative and finite. nil preserves history; expired-secret erasure is independent. Choose a host retention policy before deployment and follow maintenance and monitoring.

Digest adapters

Rails supplies the default keyed digest configuration. Advanced hosts can supply session_token_digest and sign_in_token_digest adapters implementing digest(value) and matches?(digest, value). Outside Rails, configure digest_secret as a callable or inject adapters. Changing digest or encryption keys can invalidate sessions, outstanding proofs or unsent payloads; plan key changes with your deployment and queue lifecycle.

legacy_password_verifier defaults to nil. current_password_support defaults to AddAuth::Core::Passwords::BcryptSupport.new and declares usable current password digests through available?(digest:). A custom current verifier must supply matching support metadata. Follow password migration for legacy verifier setup; changing these adapters is not needed for ordinary installation.

Presentation and captcha

Setting	Default	Details
`stylesheet`	`"/add_auth.css"`	A same-origin stylesheet path, or `nil`.
`css_classes`	`{}`	Semantic class overrides; see styling.
`challenge_on`	`[]`	Actions protected by a configured challenge provider.
`challenge_when_unavailable`	`:closed`	Provider outage policy: `:closed` or `:open`.

Optional integration settings

Setting	Default	Meaning
`external_identities.enabled`	`false`	Enable manually after reviewed provider registration and host wiring.
`external_identities.register`	No providers	Register `id:`, `label:`, `middleware_name:` and a verified Core `configuration:`. `apple_form_post:` and `reauthentication:` default to `false`.
`external_identities.register_native`	No native providers	Register an explicit native Core `configuration:`. See provider integration and the generated provider initializer.
`mobile.enabled`	`false`	Enable manually after schema and client policy review.
`mobile.lifetime`	`nil`	Required integer seconds from 60 to 7,776,000 (90 days).
`mobile.idle_timeout`	`nil`	Required integer seconds from 60 to 7,776,000 (90 days), no greater than lifetime.
`mobile.clients`	`[]`	1–32 unique strings; start with a lowercase letter, followed by lowercase letters, digits, underscores or hyphens, up to 64 characters. An identifier is not proof of client identity.
`mobile.callbacks`	`{}`	Reviewed exact URLs indexed by registered client ID. Use HTTPS or a reviewed app scheme with a host and path; no credentials, query or fragment.
`mobile.apple_providers`	`{}`	Native Apple provider IDs indexed by client ID. Requires the reviewed native verifier setup.

Mobile durations are independent of browser durations. Follow mobile setup for secure token storage, handoffs and actual-client verification.

Check your changes

challenge defaults to AddAuth::Core::Challenge::Null.new. Configure a real provider before selecting actions. Supported actions are :sign_in, :email_link, :reauthenticate, :passkey_enrollment, :register, :account_request and :provider. Provider keys, hostname restrictions and reCAPTCHA version settings are described in captcha setup.

turbo_enabled defaults to true. Set it to false for AddAuth pages using ordinary JavaScript navigation with Turbo absent. Password/email forms support ordinary HTML; passkeys and configured captcha still need their permitted browser capabilities.

Restart the app after changing initializers. Run bin/rails add_auth:doctor, then exercise the affected browser flow. Check release status before installing or upgrading.

Configuration reference