Passkeys

Let people sign in with a passkey and manage their saved devices or security keys from /passkeys.

Before enabling passkeys

Follow the RubyGems installation steps first. Run the commands below from your Rails app. You need working mail delivery, a scheduled delivery sweep, a stable public HTTPS hostname, and a browser with WebAuthn support. Check release status for package availability.

The generator also installs hardened sessions, email links, reauthentication and security notifications. All authentication models must share one database connection pool. Your app still creates accounts and verifies their email addresses.

Install the feature

bin/rails generate add_auth:passkeys
bin/rails db:migrate

Review the generated migrations before applying them. Set your deployment identity in the generated initializer:

AddAuth.configure do |config|
  config.passkeys.rp_id = "example.com"
  config.passkeys.origins = ["https://accounts.example.com"]
  config.passkeys.name = "Your app"
  config.base_url = "https://accounts.example.com"
  config.mail_from = "Your app <sign-in@example.com>"
end

Replace both example hosts. The RP ID identifies the site that owns the passkeys; keep it stable across deployments. Origins are exact allowed origins, including a port when present, within that RP ID. AddAuth permits HTTP only for local loopback development. Configure recovery and your support path before inviting users.

bin/rails add_auth:deliver_pending
bin/rails add_auth:doctor

Restart the app and schedule the delivery task every minute in deployed environments. Resolve doctor findings before continuing.

Add your first passkey

1. Sign in to an existing account and open /passkeys.
2. Complete the requested reauthentication. Adding a credential requires fresh proof for passkey management.
3. Choose to add a passkey and complete the browser’s device or security-key prompt.
4. Give it a recognizable name. Check that it appears in the passkey list.
5. Sign out, choose passkey sign-in, and complete the browser prompt again.

flowchart TD
    accTitle: Passkey sign-in
    accDescr: A user selects a passkey and completes the browser prompt. AddAuth verifies the response and account policy before starting a session. Cancellation or rejection returns to an allowed sign-in choice.
    A[Choose passkey sign-in] --> B[Complete browser prompt]
    B --> C{Response and account policy valid?}
    C -->|Yes| D[Start session]
    C -->|No| E[Show failure and allowed alternatives]
    B -->|Cancelled| E

The browser handles the device prompt. AddAuth verifies the response, user verification and current account policy before creating the session. Cancelling or failing the prompt creates no signed-in session.

Manage saved passkeys

Users can rename a passkey or remove one they no longer use. Removal requires fresh proof and cannot remove the last usable method under the account’s policy. Encourage a second usable passkey before enabling strict policy.

If the prompt is unavailable

Device choices and cross-device prompts depend on the browser and authenticator. Local release tests use Chrome virtual authenticators. Check your supported physical devices and cross-device flows before deploying; see verification coverage.

Protect sensitive actions

Use reauthentication when an action requires a recent proof, then review security emails so people can recognize account changes.