Keycloak Passkeys & WebAuthn: The Complete Guide

Last updated: May 2026

Keycloak supports WebAuthn and passkeys in two distinct modes: as a passwordless first-factor login (replacing the username/password form entirely) and as a phishing-resistant second factor (added on top of a password). The first mode is enabled through the WebAuthn Passwordless Policy and the “Webauthn Register Passwordless” required action; the second uses the standard “Webauthn Register” required action and a modified browser authentication flow. Both are configured in the Keycloak Admin Console under Authentication > Flows, Authentication > Required Actions, and Realm Settings > Authentication > Policies.

This guide covers both modes end to end for Keycloak 26.x (Quarkus). You will learn what passkeys and WebAuthn are, when to pick each mode, how to configure the relevant policies and flows, how users register and log in, and what browser and device support to expect. If you want broader context on why passwordless authentication is gaining traction before diving into configuration, read our post on why everyone is talking about passwordless authentication.

---

What are passkeys and WebAuthn?

WebAuthn (Web Authentication) is a W3C specification that standardises public-key credential creation and assertion in browsers. FIDO2 is the umbrella term for the combination of WebAuthn and the CTAP2 protocol that governs how authenticators (hardware keys, platform biometrics) communicate with the browser.

A passkey is a FIDO2 credential that is designed for everyday consumer use. Per the FIDO Alliance, a passkey allows users to sign in using the same mechanism they use to unlock their device — a biometric, PIN, or pattern — with no password involved. The distinguishing technical property is that a true passkey is a discoverable credential (also called a resident key): the credential ID and associated metadata are stored on the authenticator itself, so the browser can present an account selector to the user without requiring them to type a username first.

Keycloak acts as the Relying Party (RP) in all WebAuthn interactions. During registration:

1. Keycloak sends a challenge and the RP configuration to the browser.
2. The browser calls navigator.credentials.create(), which invokes the authenticator.
3. The authenticator generates a public-private key pair. The private key never leaves the authenticator.
4. The public key and credential metadata are returned to Keycloak and stored per-user.

During authentication, Keycloak sends a fresh challenge; the authenticator signs it with the private key; Keycloak verifies the signature against the stored public key. The credential itself proves user presence and, optionally, user verification (biometric or PIN confirmation).

Platform vs. roaming authenticators

Type	Examples	Notes
Platform	Touch ID, Windows Hello, Android biometrics	Built into the device; passkeys may sync via iCloud Keychain, Google Password Manager
Roaming	YubiKey, Titan Security Key	External hardware over USB, NFC, or Bluetooth; portable across devices

The Keycloak WebAuthn Policy’s Authenticator Attachment setting controls which types are allowed: platform, cross-platform, or unset (both). For most deployments, leaving this unset gives users maximum flexibility.

---

The two Keycloak WebAuthn modes at a glance

	Mode 1: Passwordless first-factor	Mode 2: Passkey as second factor
Required Action	Webauthn Register Passwordless	Webauthn Register
Policy	WebAuthn Passwordless Policy	WebAuthn Policy
Admin path	Authentication > Policies > WebAuthn Passwordless Policy	Authentication > Policies > WebAuthn Policy
Flow change needed?	None (default browser flow already supports it)	Yes — enable WebAuthn Authenticator in browser flow
User types password?	No	Yes (first factor)
Discoverable credential required?	Yes (Require Resident Key = Yes)	Recommended but not required
User verification	Required	Preferred or Required

Choose Mode 1 when your goal is a fully passwordless experience: users select a passkey from an account chooser and authenticate with a biometric or device PIN alone. Choose Mode 2 when you want to keep passwords as the primary credential but add a phishing-resistant second factor — a stronger alternative to TOTP. You can also run both simultaneously, which lets users choose at the login screen.

---

Mode 1: Passwordless first-factor login

How it works

When a user arrives at the Keycloak login page, they see a “Sign in with a passkey” option. Clicking it triggers navigator.credentials.get() with mediation: "conditional" or an explicit resident-key lookup. Because the credential is discoverable, no username is required upfront — the authenticator presents a list of matching accounts and the user selects one and verifies with biometrics or PIN.

Step 1 — Enable passkeys in the WebAuthn Passwordless Policy

In the Admin Console, navigate to:

Realm Settings > Authentication > Policies > WebAuthn Passwordless Policy

Set the following:

• Enabled Passkeys: ON — this is the master toggle that activates passkey-style discoverable credential support in Keycloak 26.4+.
• Require Discoverable Credentials (requireResidentKey): Yes — this ensures credentials are stored on the authenticator and can be used without a typed username.
• User Verification Requirement: Required — forces a biometric or PIN check so the passkey proves both possession and user presence.
• RP Entity Name: A human-readable name for your service (e.g., “Acme Corp”). Displayed in the browser prompt.
• RP ID: Defaults to your Keycloak hostname. Must match the origin used at authentication time.
• Signature Algorithms: ES256 (ECDSA P-256) is universally supported; RS256 is a reasonable fallback for some hardware keys. Keep defaults unless you have a specific requirement.
• Attestation Conveyance Preference: none is appropriate for most web applications. Use direct or indirect only if you need to verify the authenticator model (enterprise scenarios).
• Authenticator Attachment: Leave unset for maximum flexibility, or set platform if you want device-bound passkeys only.

Step 2 — Configure the Required Action

Navigate to Authentication > Required Actions and confirm that Webauthn Register Passwordless is listed. Enable it. Optionally, toggle Default Action to ON if you want new users to be prompted to register a passkey immediately after their first login with a temporary password.

Do not confuse this with “Webauthn Register” (no “Passwordless” suffix) — that is the required action for the second-factor mode covered in Mode 2.

Step 3 — Authentication flow (no changes required for 26.x)

As of Keycloak 26.4, the default browser flow includes a Passkey login subflow that is activated automatically when Enabled Passkeys is ON. You do not need to edit the flow yourself. If you are using a custom browser flow, you will need to add a Passkey Form execution at the top level to support conditional mediation.

For background on how authentication flows work, see our guide on Keycloak custom authentication flows.

Step 4 — User registration

A user can register a passkey from the Account Console:

https://<keycloak_hostname>/realms/<realm_name>/account

Navigate to Account Security > Signing In, then click “Set up Security Key” under the Passwordless section. The browser will invoke the WebAuthn registration ceremony. The user selects or creates a passkey on their device (platform authenticator) or hardware key (roaming authenticator).

Alternatively, if you set “Webauthn Register Passwordless” as a default required action, the user is prompted to register immediately after completing any prior credential step.

Step 5 — Testing passwordless login

1. Open your application or the Account Console.
2. On the Keycloak login page, click Sign in with a passkey.
3. The browser presents an account chooser. Select the account.
4. Complete the biometric or PIN prompt.
5. You are authenticated — no password entered.

---

Mode 2: Passkey as a second factor (2FA)

How it works

The user enters a username and password as the first factor. After successful password verification, Keycloak evaluates the Conditional 2FA subflow in the browser flow. If the user has a registered WebAuthn credential and the flow conditions are met, Keycloak prompts for a passkey verification. This delivers phishing resistance at the second factor without requiring users to abandon passwords entirely.

For a broader discussion of MFA patterns, see our guide on multi-factor authentication integration patterns for enterprise applications.

Step 1 — Configure the WebAuthn Policy

Navigate to Realm Settings > Authentication > Policies > WebAuthn Policy (not the Passwordless Policy).

Key settings:

• RP Entity Name and RP ID: same guidance as Mode 1.
• Signature Algorithms: ES256 recommended.
• User Verification Requirement: preferred works for 2FA (the passkey verifies device possession even without biometric); required adds user presence verification.
• Require Discoverable Credentials: Optional for 2FA. If set to Yes, users can use the same passkey for both modes. If No, non-resident credentials (classic security key credentials) are also accepted.
• Attestation: none is standard.

Step 2 — Enable the Required Action

Navigate to Authentication > Required Actions and ensure Webauthn Register (without “Passwordless”) is enabled. Toggle Default Action to ON if you want all new users prompted to register a security key after first login.

To enroll an existing user:

1. Open the user in Admin Console: Users > [select user] > Required User Actions.
2. Add “Webauthn Register” to their required actions list.
3. On next login, they will be prompted to register a credential.

Users can also self-register by visiting the Account Console at https://<keycloak_hostname>/realms/<realm_name>/account > Account Security > Signing In > add a security key under the Two-Factor section.

Step 3 — Edit the browser flow

The default browser flow ships with the WebAuthn Authenticator execution present but DISABLED. You need to enable it:

Navigate to Authentication > Flows and select the browser flow (or a copy you use as your active browser flow).

Locate the Browser – Conditional OTP (in older builds) or Conditional 2FA subflow. Inside it you will find:

• Condition — User Configured
• OTP Form
• WebAuthn Authenticator (set to DISABLED by default)

Change WebAuthn Authenticator from DISABLED to ALTERNATIVE. Setting it to ALTERNATIVE means users who have a WebAuthn credential can use it instead of OTP; setting it to REQUIRED would force it for all users in the subflow.

The Condition — Credential step ensures that if the user already authenticated with a passkey as the first factor (Mode 1), this 2FA subflow is skipped — preventing double-prompting. This logic works out of the box; no further configuration is needed for the condition.

If your browser flow is the default built-in flow, you must first create a copy (Action > Duplicate) before editing. Then bind the copy as the active browser flow under Realm Settings > Authentication > Flows or via the Action > Bind flow menu.

For advanced flow design — for example, requiring passkey 2FA only for specific clients or roles — see our guide on Keycloak step-up authentication.

Step 4 — Testing 2FA with passkeys

Scenario A: Password + passkey (2FA)

1. Open the application login page.
2. Enter username and password.
3. Keycloak evaluates the Conditional 2FA subflow. Because the user has a registered WebAuthn credential, the WebAuthn prompt appears.
4. Complete the biometric or PIN verification.
5. Authentication succeeds.

Scenario B: First-factor passkey + no 2FA prompt

If Mode 1 (Enabled Passkeys = ON) is also active and the user authenticates via passkey at the first step, the Condition — Credential check in the 2FA subflow detects that a passkey credential was already used and skips the WebAuthn second-factor prompt. The user is not prompted twice.

Scenario C: Password + passkey when first-factor passkeys are disabled

Set Enabled Passkeys = OFF in the WebAuthn Passwordless Policy. The “Sign in with a passkey” button disappears from the login screen. Users authenticate with password only, then are prompted for the passkey second factor (if registered). This is the purest MFA-only deployment.

---

Running both modes simultaneously

Keycloak supports having both modes active at the same time. Users with both a Passwordless credential and a WebAuthn (2FA) credential registered will:

• See a “Sign in with a passkey” option for full passwordless login (Mode 1).
• Also be prompted for a passkey second factor when using a password (Mode 2) — unless the Condition — Credential logic skips it.

When registering credentials for both modes on the same device, it is important to use different authenticator providers for each if the platform does not distinguish between discoverable and non-discoverable credentials. The Keycloak Account Console displays each credential type separately under Signing In.

For React/Next.js frontend integration with Keycloak passkeys, see our guide on Keycloak passkeys with React and Next.js.

---

Cross-device and syncable passkeys

Modern platform authenticators support passkey syncing across devices:

• Apple: Passkeys sync via iCloud Keychain across iOS 16+, macOS Ventura+.
• Google: Passkeys sync via Google Password Manager on Android 9+ and Chrome on desktop.
• Windows: Windows Hello creates device-bound passkeys; cross-device login is handled via Bluetooth CTAP2 (phone as authenticator).

Synced passkeys work seamlessly with Keycloak because the public key stored in Keycloak remains valid regardless of which synced instance of the private key signs the challenge. From Keycloak’s perspective, it sees a valid signature against the registered public key — the syncing is transparent.

For cross-device authentication (scanning a QR code to use a phone as an authenticator for a desktop browser), the browser handles CTAP2 hybrid transport automatically. No Keycloak-specific configuration is required.

Roaming hardware keys (YubiKey, etc.) are inherently portable and work across any device that supports USB-A, USB-C, or NFC. They do not sync but provide the strongest attestation guarantees.

---

Browser and authenticator support

Browser support

Browser	Minimum version	Notes
Chrome	67+	Full support including passkey UI, sync via Google Password Manager
Edge	79+	Full support; Windows Hello integrated
Safari	14+	Full support; iCloud Keychain sync on Apple devices
Firefox	60+	WebAuthn supported; passkey UI improvements in recent versions

Mobile: iOS 16+ and Android 9+ provide native passkey support. Ensure your Keycloak login page is served over HTTPS — WebAuthn is blocked on non-secure origins.

Fallback behaviour

Users who do not have a passkey registered or whose browser does not support WebAuthn will:

• In Mode 1: see the standard username/password form if the Conditional Passkey flow also includes a Username/Password form as a fallback.
• In Mode 2: be prompted for OTP (if configured as an alternative in the 2FA subflow) or be told no second factor is available.

Always configure at least one fallback authentication method to avoid locking out users on unsupported hardware or browsers. You can also use Keycloak custom authentication flows to build nuanced fallback logic.

---

Choosing between the two modes

Scenario	Recommended mode
Consumer app where you want to eliminate passwords entirely	Mode 1 (Passwordless)
Enterprise app with existing password policy; add strong MFA	Mode 2 (Passkey as 2FA)
High-assurance app requiring step-up for sensitive operations	Mode 2 + step-up flows
Gradual migration: offer passwordless alongside passwords	Both modes simultaneously
Regulated environment requiring phishing-resistant MFA	Either mode (both are FIDO2)

For feature-level details on Skycloak’s passwordless capabilities, see the passwordless feature page. For MFA configuration options, see the multi-factor authentication feature page.

---

Frequently asked questions

What is the difference between a passkey and WebAuthn in Keycloak?

WebAuthn is the underlying W3C protocol that Keycloak implements to handle public-key credential registration and authentication. A passkey is a specific type of WebAuthn credential — one that is discoverable (resident), designed for user-friendly account selection without entering a username first, and often synced across a user’s devices via a platform provider. All passkeys are WebAuthn credentials, but not all WebAuthn credentials are passkeys. In Keycloak, the “Webauthn Register Passwordless” required action creates passkey-type credentials, while “Webauthn Register” creates standard WebAuthn credentials suited for second-factor use.

Can Keycloak use passkeys for passwordless login?

Yes. Since Keycloak 26.4, enabling Enabled Passkeys in the WebAuthn Passwordless Policy and setting Require Discoverable Credentials to Yes activates passkey-style first-factor login in the default browser flow. Users register a passkey via the Account Console and can then sign in by selecting their account from a browser prompt and completing a biometric or PIN check — no password required.

Do Keycloak passkeys sync across devices?

Keycloak itself does not manage passkey syncing; that is handled by the platform (Apple iCloud Keychain, Google Password Manager, or a hardware key). When a passkey syncs to another device, the underlying public key registered with Keycloak remains the same, so authentication continues to work on the new device without any Keycloak-side changes. For hardware roaming authenticators (YubiKey, etc.), the credential is not synced but is physically portable.

What is the “Webauthn Register” vs “Webauthn Register Passwordless” required action?

Keycloak ships with two separate required actions for WebAuthn registration. Webauthn Register creates a standard WebAuthn credential governed by the WebAuthn Policy — intended for second-factor use. Webauthn Register Passwordless creates a discoverable credential governed by the WebAuthn Passwordless Policy — intended for passwordless first-factor login. Each required action registers a distinct credential. You can enable both for a user if you want them to use passkeys in both modes.

How does Keycloak prevent prompting for passkeys twice (first factor and second factor)?

The default browser flow includes a Condition — Credential step inside the Conditional 2FA subflow. This condition checks whether the credential type used for the first factor overlaps with the second-factor credential type. If the user already authenticated via a Passwordless WebAuthn credential, the condition evaluates to false and the 2FA subflow is skipped. This logic works automatically; no additional configuration is needed. If you use a custom flow, you must replicate this condition to avoid double-prompting users who rely on Mode 1.

---

Managing Keycloak passkeys at scale

Configuring WebAuthn policies and flows is straightforward in a single realm, but managing these settings consistently across multiple realms, keeping Keycloak patched, and handling credential recovery for users who lose their device adds operational overhead that compounds as your user base grows.

Skycloak provides managed Keycloak hosting with production-ready infrastructure, automated upgrades, and support from engineers who work with Keycloak authentication flows daily. If you would rather focus on your application than on Keycloak operations, see the Skycloak pricing page or explore managed Keycloak hosting to get started.