Configuration — Passkey Settings

Everything is configured from the Passkey Settings single DocType (Desk → Passkey Settings). This page documents every field, its default, and the security consequence of changing it, then the way the settings interact with each other and with core’s Two Factor Authentication.

The fieldnames below are the app’s stored fieldnames. The upstream documents propose reusing them in System Settings, but no current-core compatibility or merge is assumed.

Login Modes

Relying Party

Enabling either authentication mode also uses the site’s encryption_key: second-factor ceremonies bind password-hash versions with it, and lifecycle exports use it for integrity. When site_config.json has no key, Frappe core’s get_encryption_key() creates and saves one on save, as it does for any encrypted field. An entry that is present but empty is refused. Back the key up separately before enrolling production users, and restore the original key (not a new one) when recovering existing encrypted data or a credential export.

For example, host_name = https://login.example.com and RP ID example.com trusts https://login.example.com; it does not also trust https://example.com. Add the apex origin explicitly only if the site or an iOS app genuinely uses it. The read-only Resolved Configuration panel shows the exact server-resolved set, plus the RP-change warning and stale inventory. The System Manager Desk alert distinguishes no working path, an app-only path, and web access at other configured origins. It uses configured host_name, not the request Host header.

Mobile Apps

If a native iOS / Android app should share the site’s passkeys, the Mobile Apps fields configure the trusted native origins and the two well-known association files: passkey_app_origins, passkey_android_package_name, passkey_android_cert_fingerprints, passkey_ios_team_id, and passkey_ios_bundle_id. They are documented in full — including how to obtain the Android signing-certificate fingerprint and how the association files are served — in mobile-apps.md. Leave them blank for a web-only site.

Enrollment

Require a passkey from decides who must enroll after they sign in. That prompt is a post-login interstitial: the session already exists, so it raises friction toward enrollment and is never a server-side login block. Phone / QR enrollment is always offered; a device counts as capable when it has a platform authenticator or a cross-device option. Users outside the scope take Everyone else. A blank Starting on means immediately; until that date, in-scope users are nudged instead of required. A per-user exemption beats every scope rule, including System Managers.

The enforcement preview counts users in the background on save, daily, or when you select Recalculate; opening the page only reads the cached count. Only the saved policy’s count is shown, with the time counting started; a policy without one shows Not counted yet. After a save or recount the open form checks every three seconds, up to ten times, for the new count. A recount that started earlier never replaces a newer one, and if the cache is cleared the preview shows Not counted yet until the next count. A full job queue does not prevent saving the policy, but its preview may remain uncounted or keep the previous count for that policy. Recalculate reports when the recount cannot start; retry after queue capacity is available.

For sites upgrading from before 15.0.0, the migration maps the old enrollment policy and scope to these settings. Non-enforcing policies also turn off Always require a passkey from System Managers. Users with the legacy Passkey Enforcement Exempt role keep their exemption as a per-user flag; the role assignments are left in place.

A user can’t get past enforcement — what to do

Enforce is a post-login interstitial, not a pre-session authentication block, but Block + Notify Admin can still prevent useful application access. The levers below go from least to most drastic. Pick the narrowest one that fits.

1. They said “I can’t set one up here.” With the default Device cannot create a passkey (Degrade to Nudge) the interstitial already let them through as a dismissible nudge (or silently when opted out, capped or cooling down), without emailing administrators. Nothing is blocking; help them enroll on a capable device (or issue a security key) when convenient. Only Block + Notify Admin keeps the gate up; there the button reads Contact administrator, because clicking it emails the System Managers. The fixes below apply then.
2. Exempt this one user (one click). Open the user’s User form → the Passkeys section (System Managers see it on anyone’s form). While a passkey is required from someone, it shows two admin actions; click Exempt from passkey enforcement. The exemption is stored per user by the app, not as a role, so a Role Profile cannot undo it. The user takes the Everyone else rung immediately, including a System Manager covered by Always require a passkey from System Managers. Remove enforcement exemption reverses it. There is no role-wide exemption setting.
3. Give them more grace logins. In the same section, Reset grace logins restores the user’s full deferral budget (the Grace sign-ins count) so the interstitial goes back to “Remind me later” instead of blocking. Use it to buy a capable-but-not-right-now user time to enroll.
4. Adjust scope or roles. If a whole non-privileged group is caught wrongly, set Require a passkey from to Selected roles and list Roles. This takes effect on the next login. System Managers stay in scope while Always require a passkey from System Managers is on.
5. If no System Manager can reach Desk, follow No System Manager can sign in. Lifting the requirement for the whole site is its last resort, not a way to let one user through.

There are no standing role-wide exemptions. Administrators are enforced first by default; recovery is an explicit per-user exemption.

Enforcement, Passkey Only Login and disabled password login govern interactive sign-in only; API-key and OAuth-token requests are not subject to them (see API keys and OAuth tokens).

Security

Notifications

The two-factor floor (both directions)

“Passkey as Second Factor” is enforced structurally, by keeping core’s Two Factor Authentication turned on. The app guards this pairing from both sides:

• Enabling passkey 2FA requires System Settings → Enable Two Factor Authentication to already be on. Saving Passkey Settings with passkey_as_second_factor on while core 2FA is off is refused. The reason: the app relies on core’s 2FA machinery as a structural floor in addition to its own login veto. If core 2FA is on but no role has two-factor enabled, the save proceeds with an orange warning (the backstop then covers nobody — enable it for role All).

• Disabling core Two Factor Authentication is refused while passkey_as_second_factor is on. Attempting to turn Enable Two Factor Authentication from on to off in System Settings throws, because it would silently evaporate the backstop while the passkey-2FA UI kept working. Turn off “Passkey as Second Factor” in Passkey Settings first.

A raw bench console / db_set edit can bypass both validators and leave the two desynced (passkey_as_second_factor=1 while core 2FA is off). The final login veto still blocks enrolled users, and the security posture panel on the Passkey Settings page flags the missing floor.

For a user with a usable passkey, the second-factor requirement is enforced at the final login hook, not only by the app’s login-page JavaScript. Password, email-link, social/OAuth, LDAP, and other core login paths are vetoed unless this app completed the passkey step or explicitly handed the user to core OTP via fallback_to_otp. That OTP handoff creates a short-lived, one-time marker bound to core’s tmp_id; a direct call to core OTP without that marker remains blocked. The rule also applies to Administrator after Administrator has explicitly enrolled a usable passkey.

Every password-to-passkey ceremony captures a keyed, non-reversible version of the current password hash at the password leg and compares it again immediately before session minting. A password rotation during the ceremony therefore fails closed without retaining the password for the normal passkey-only leg. The password itself is retained only where an allowed OTP fallback, or an external authentication account without a local hash marker, requires core to re-authenticate.

Settings interaction matrix (operator terms)

Login-veto rows above apply to users with usable credentials. Stale-only users are not subject to those per-user vetoes; the stored flags and settings-save guards remain in place.

Per-user “Passkey Only Login”

On /passkeys, the switch is labelled Passwordless login only; it is the same setting as Passkey Only Login on the WebAuthn User Handle.

This is a per-user switch (on the user’s WebAuthn User Handle row), not a site setting. It disables password / email-link / social first-factor login for that one user while a usable passkey exists. An existing password hash is kept. With only stale keys, the flag persists but its veto pauses; it applies again when a usable key exists. It is the released-branch lever for “no passwords for this account”; the site-wide equivalent needs the self-hoster override in operations.md.

• The user’s own switch needs a fresh passkey confirmation — never a password and never a sudo window. (A password must not be able to switch off the very flag that says “a password is not enough”.) Turning it on there requires at least two usable passkeys, so a single lost device never locks the account out.
• A System Manager can clear it on the user’s WebAuthn User Handle form; that is how a user who lost every passkey is recovered (A user lost their passkey). Turning it on from that form requires at least one usable credential and a passkey login mode.
• Administrator is exempt only from this per-user passkey-only login veto. That preserves the password break-glass path for an Administrator who has not opted into the passkey second factor. Once Administrator explicitly enrolls a usable credential while Passkey as Second Factor is active, alternate/core login paths are protected exactly like any other enrolled user’s. The site-wide disable_user_pass_login flag also has no Administrator exemption. See security.md and recovery.md.

Transactional race protection

Security-sensitive read/modify/write paths take database locks in a consistent order. Credential assertion bookkeeping re-locks the credential before advancing counters; UV setup locks the user and credential; registration locks the user, handle, and credential census before applying the per-user cap and insert; passkey-only credential deletion/toggling locks the shared login floor; Passkey Settings mode changes lock the Single rows before checking flagged users; and the Passkey Settings / System Settings floor checks read each other’s values with locking reads. These locks protect the credential and mode floors. RP reads in ordinary census and ceremony effect checks are uncached but non-locking; they can retain a request transaction snapshot. Only bulk stale removal serializes its RP read with settings saves. See the RP-change residual risks, including per-request host_name overlap.

Request hardening and numeric limits

Guest endpoint limits also count IPv6 addresses together by /64; IPv4 limits are unchanged. Credential audit records and notification emails retain the full client IP. Frappe’s own IP-based login tracker remains under core control; the app does not monkeypatch it. Email login identifiers are trimmed and lowercased before authentication. Non-email usernames (including Administrator) are trimmed but retain their case. Discoverable passkey login takes no identifier; subsequent fallback legs use the canonical user stored by the server.

Login redirects remain core-sanitised by frappe.utils.sanitise_redirect; the app leaves core’s login handler unchanged.

All five integer settings require values within these inclusive ranges when saved:

Zero retains existing semantics: the credential cap defaults to 10, the re-authentication window defaults to 600 seconds, zero prompts disables nudges, zero cooldown allows immediate repeat prompting, and zero grace blocks deferral immediately. Existing out-of-range settings must be corrected before their next save; this change does not rewrite stored configuration.