Sessions & sign-out

Use hardened sessions with the Rails account models you already have, then give users a way to review and end their sessions.

Adopt sessions

Version 0.5.0 supports integer and PostgreSQL UUID session IDs. Existing schemas keep their IDs. See UUID and integer primary keys and the upgrade procedure for older packages.

After installing the gem and generating Rails’ authentication files, run these commands in your Rails app:

bin/rails generate add_auth:session_upgrade
bin/rails db:migrate
bin/rails add_auth:doctor

The email-link generator already performs this step. Session adoption wires the shared password flow and adds session-management routes. It preserves the host controller file, while handling its sign-in new/create actions through AddAuth. Verify custom sign-in hooks before adoption.

Set session expiry

The default absolute lifetime is 12 hours; the idle timeout is 30 minutes. The session ends when either limit is reached. In the initializer, for example:

config.session.lifetime = 24.hours
config.session.idle_timeout = 1.hour

Choose values that fit your app’s risk and usage. A recent session timestamp alone is not stronger authentication.

flowchart TD
    accTitle: A session is checked on every request
    accDescr: After sign-in, the app checks the session on each request. A valid session continues. An expired or revoked session is rejected, and the user must sign in again.
    A[Sign in] --> B[Create a session]
    B --> C[Make a request]
    C --> D{Session still valid?}
    D -->|Yes| E[Continue in the app]
    E --> C
    D -->|Expired or revoked| F[Ask the user to sign in again]

List and revoke

A signed-in user can visit /sessions to see their active sessions and revoke one. A revoked browser is rejected on its next request. Signing in again in one browser retires that browser’s previous session; other browsers remain signed in until expiry or revocation.

“Sign out everywhere” requires fresh proof: the current password or, with reauthentication enabled, another method allowed for this action. It revokes every session, including the initiating browser. It also revokes outstanding email and account proofs, such as a pending address change, and any passkey ceremonies, provider ceremonies and mobile handoffs in progress. Ordinary sign-out does not require that extra password check.

Transition existing sessions

Without a legacy bridge, users with Rails’ previous signed-ID cookies must sign in again. If your rollout needs a grace period, set config.session.legacy_bridge_until to an explicit, bounded cutoff after reviewing the transition in a test host.

Do not roll back to the previous authentication path after adoption. Keep schema changes additive and plan a recovery that preserves hardened session handling.

Verify account changes

Using test accounts, confirm that password and address changes through Rails invalidate the applicable sessions and pending links. Check a second browser’s next request. Do not bypass host callbacks with direct SQL for account-security changes.

Unexpected expiry is covered in session troubleshooting.

Navigate a long session list

The current browser appears first on the newest page. Other sessions use newest-created order, with up to 50 candidates per page. Follow Older sessions to reach remaining sessions, or Newest sessions to return. Activity timestamps do not change the page order. See session pages and history retention.