Passkeys

Externa supports passkeys (WebAuthn) via official Laravel Fortify + @laravel/passkeys. A passkey is passwordless sign-in and also counts as MFA when the project requires two-factor authentication.

What passkeys are in Externa

User model: implements PasskeyUser, uses PasskeyAuthenticatable (alongside TwoFactorAuthenticatable). Successful passkey login uses PasskeyLoginResponse, which redirects via the same HomePath resolver as password login.

Register a passkey (Security settings)

Steps

1. Sign in (email + password, or an existing passkey).
2. Open Settings → Security. With default Fortify options, password.confirm runs first — confirm your account password or use Confirm with passkey if you already have a passkey (details), then the security page loads.
3. In Passkeys, enter a device name (e.g. “MacBook Touch ID”, “Phone”).
4. Click Add passkey. The browser/platform authenticator prompt appears (Touch ID, Windows Hello, security key, etc.).
5. Complete the prompt. The list reloads with the new passkey (id, name, created_at, last_used_at).

List and delete

• Registered passkeys are listed on the same page.
• Delete calls the Fortify passkey destroy route (passkey.destroy). Users can delete only their own passkeys.
• If the project has two_factor_required on and this was the user’s only MFA factor (no confirmed TOTP and no remaining passkeys), EnsureTwoFactorIsEnabled will send them back to Security until they enroll again.

Sign in

Passkey (passwordless)

1. Open the login page (resources/js/pages/auth/login.tsx).
2. If passkeys are enabled and supported, a Sign in with passkey button appears (data-test="passkey-login-button"). Sign-in is click-only (no WebAuthn autofill on mount — avoids hung isLoading on some browsers).
3. Click the button. Complete the authenticator prompt.
4. On success, the client follows PasskeyLoginResponse’s redirect (JSON redirect URL or Inertia visit) — same home as password login.

There is no Fortify TOTP challenge after a successful passkey assertion. The credential is the second factor.

Email + password (+ TOTP when required)

1. Submit email and password as usual.
2. If the user has confirmed Fortify TOTP enabled, Fortify’s two-factor challenge runs next (unless this session already satisfied 2FA).
3. If the user has only passkeys (no TOTP) and signs in with password, password login does not automatically use the passkey — they still need a password (and TOTP if TOTP is enabled). Passkey is an alternate login path, not a replacement for the password field on that form.

Confirm password with a passkey

Fortify’s password.confirm middleware sends the user to /user/confirm-password before sensitive actions that opt into recent re-auth — notably Settings → Security when confirmPassword is on for 2FA and/or passkeys (SecurityController + config/fortify.php). UI: resources/js/pages/auth/confirm-password.tsx; props from FortifyServiceProvider (canManagePasskeys, hasPasskeys).

Ceremony details (passkey path):

1. Click-only — usePasskeyVerify({ autofill: false }) against GET /passkeys/confirm/options + POST /passkeys/confirm. No WebAuthn autofill on mount (same hung-isLoading lesson as login).
2. Success marks the session password-confirmed (passwordConfirmed()) and follows the same intended redirect as typing the password (JSON redirect, else /).
3. Abort (dismiss authenticator) → cancelled message (UserCancelledError); other errors surface as-is. The password form stays usable while a ceremony runs and after cancel.

Account-settings summary: Password, 2FA & passkeys.

Relationship with 2FA / two_factor_required

Project setting two_factor_required is enforced by EnsureTwoFactorIsEnabled on the web stack. A user is “MFA complete” when either:

• hasEnabledTwoFactorAuthentication() (confirmed Fortify TOTP), or
• passkeys feature on and hasPasskeysEnabled() (≥1 registered passkey).

Decision table

Allowlisted routes while enforced (so enrollment works): security / password / profile / locale settings, Fortify 2FA + passkey registration/store/destroy, password-confirm, and logout. See Project settings.

Requirements

Secure context (passkeys only)

WebAuthn / PublicKeyCredential is available only in a secure context:

Do not expect HTTP passkeys on custom Herd/Valet .test hosts — browsers treat those as insecure. Use password + TOTP on HTTP, or enable local HTTPS below.

Production: passkeys require HTTPS. The app can run on HTTP for non-passkey features, but HTTPS is recommended in general (sessions, cookies, proxies).

Config checklist

// config/fortify.php (excerpt)
'passkeys' => [
    'relying_party_id' => parse_url(config('app.url'), PHP_URL_HOST),
    'allowed_origins' => [config('app.url')],
    'user_handle_secret' => config('app.key'),
    'timeout' => 60000,
],

Features::passkeys([
    'confirmPassword' => true,
]),

After changing APP_URL on a config-cached host, rebuild config (php artisan config:cache / config:clear).

Local HTTPS (Herd / Valet) for passkey testing

When you want passkeys on a .test host:

1. Secure the site: herd secure externa-core (Valet: valet secure …).
2. Set APP_URL=https://externa-core.test (must match the browser origin — RP ID / allowed_origins).
3. Vite / Laravel detectTls: Externa enables detectTls only when Herd cert files exist for the site. After herd secure, restart npm run dev so public/hot is https://externa-core.test:5173 (not 127.0.0.1 — that causes a black/blank screen). After herd unsecure, restart Vite again so it falls back to HTTP without looking for missing certs.
4. Restart Vite (npm run dev / composer run dev). Hard-refresh the browser. If the session looks wrong after flipping HTTP↔HTTPS, clear cookies for both schemes for that host.

Optional local path without Herd TLS: browse http://localhost (or *.localhost) with matching APP_URL — that is a secure context for WebAuthn.

Migration

Passkeys persist in the passkeys table (migration create_passkeys_table).

php artisan migrate

Schema (summary):

Fresh installs that already run composer setup / full migrate get this table automatically. Existing environments need one migrate after pulling the passkeys work.

Security notes

• No vendor forks — stay on official Fortify and @laravel/passkeys. Do not patch RP validation, credential storage, or challenge handling in vendor/.
• confirmPassword on manage — default Features::passkeys(['confirmPassword' => true]) so opening Security (and thus register/delete) requires a recent password confirmation. Keep this on unless you have a deliberate, reviewed exception.
• Do not disable RP checks — relying_party_id and allowed_origins exist to bind credentials to your site. Do not widen them to * or unrelated hosts.
• Throttle — Fortify registers a passkeys rate limiter alongside login / two-factor.
• Ownership — destroy is scoped to the authenticated user’s passkeys; deleting another user’s passkey returns an error and leaves the row intact.
• MFA equivalence — treat passkeys as a full MFA factor for two_factor_required, not as a weaker “remember me”. Prefer ≥2 authenticators (e.g. laptop + phone) so losing one device does not lock the account when the project requires MFA and TOTP is not enabled.

Source map