Keycloak’s WebAuthn provider can handle passwordless login using passkeys, enabling users to authenticate with biometrics or a physical security key instead of a password.
Let’s see it in action. Imagine a user, Alice, who has registered a passkey with her browser for your Keycloak-protected application.
First, Alice navigates to your application’s login page. Instead of typing her username and password, she clicks a "Login with Passkey" button.
Your application, integrated with Keycloak, initiates a WebAuthn authentication request. Keycloak, in turn, prompts Alice’s browser for a registered passkey.
Alice’s browser then displays a prompt for her to authenticate using her passkey – perhaps a fingerprint scan, facial recognition, or a physical security key like a YubiKey.
Upon successful passkey authentication, the browser returns a signed assertion to Keycloak. Keycloak verifies this assertion against the user’s registered passkey credentials.
If verified, Keycloak issues an authentication session and redirects Alice back to your application, now logged in, without ever needing to enter a password.
The core problem this solves is the friction and security overhead associated with traditional password-based authentication. Passkeys offer a more secure, phishing-resistant, and user-friendly alternative.
Internally, Keycloak leverages the WebAuthn specification. When a user opts for passwordless login, Keycloak generates a challenge and sends it to the client. The client then interacts with the user’s authenticator (e.g., browser’s built-in biometric scanner, a hardware security key) to generate a signed response based on the challenge and the user’s registered credential. This signed response is sent back to Keycloak for verification.
The key levers you control in Keycloak for this are primarily within the Identity Providers section, specifically the Web Authn provider configuration. Here, you enable WebAuthn, choose between "Platform" and "Hybrid" authenticators (Platform uses device-bound authenticators like Face ID, Hybrid allows for external authenticators like YubiKeys), and configure options like requiring user verification or setting the authenticator attachment.
To enable passkey login specifically, you need to ensure the WebAuthn Identity Provider is configured and enabled in your realm. Crucially, users must have previously registered a passkey for their account. This registration process happens on the user’s profile page within Keycloak, under the "WebAuthn" tab. They would click "Add Device" and follow the prompts to register their passkey.
When a user initiates a passwordless login, Keycloak’s WebAuthn authenticator will look for any registered passkey associated with that user. If multiple passkeys are registered (e.g., one on their phone and one on a hardware key), the browser typically presents a choice to the user.
The actual flow for initiating a passwordless login from your application involves making a specific authentication request to Keycloak. You’d typically use a Keycloak adapter or the Keycloak Admin/Account REST APIs to trigger the WebAuthn challenge. The exact mechanism depends on your application’s integration method. For instance, if using Keycloak’s built-in account console, there’s a direct "Login with Passkey" option once a passkey is registered. For custom applications, you’d construct an authentication request that signals the intent for passwordless authentication, often by omitting or marking the password field as empty and relying on the WebAuthn provider to handle the subsequent challenge-response.
The first time a user attempts to use a passkey for authentication, they will be prompted to register it. This registration process involves creating a new credential associated with their Keycloak account. Keycloak generates a challenge, the browser interacts with the authenticator (e.g., prompts for Face ID), and if successful, the authenticator returns a public key and attestation data. This data is then stored by Keycloak, linked to the user, and used for subsequent authentication challenges.
The distinction between "Platform" and "Hybrid" authenticators in Keycloak’s WebAuthn configuration is subtle but important for user experience. "Platform" authenticators are tightly bound to the device, like the Face ID or Touch ID on a smartphone or the Windows Hello system on a laptop. These are generally considered more secure as the private key never leaves the device. "Hybrid" authenticators, on the other hand, encompass both platform authenticators and external authenticators like USB security keys (e.g., YubiKey). Choosing "Hybrid" allows users to use a wider range of devices for their passkeys, offering more flexibility. However, the specific authenticator presented to the user is ultimately determined by their device and browser capabilities.
Once a user has successfully logged in via passkey, their session is managed by Keycloak just like any other authenticated session. Subsequent requests to your application will be validated by Keycloak based on the session token, allowing seamless access without further authentication until the session expires or is explicitly logged out.
The next step after establishing passwordless login is exploring more advanced credential management, such as implementing credential recovery mechanisms for users who lose access to all their registered passkeys.