Enabling Webauthn Support in Keycloak

Overview

While Keycloak natively supports both webauthn and passwordless webauthn authentication, they are not part of any of the built-in flows. Enabling webauthn as an alternative MFA strategy is quite easy and, in my opinion, far more convenient than having to generate a one time password.

Arguably the most popular webauthn enabled security key is the YubiKey, but several others exist.

In order to enable webauthn we must:

1. Copy the default browser flow
2. Modify the flow to include a step for webauthn authentication
3. bind this new flow to browsers.

Implementation

Duplicate Existing Browser Flow

Simply click the options icon for the browser flow and select “duplicate”.

• Name your new flow, I usually use “browser with webauthn” for clarity
• Optionally update the description.

You should now have a new “browser with webauthn” flow that looks something like this:

In its simplest this flow:

• Accepts a valid session cookie if it exists
• Requires the user to authenticate with a password
• Checks if OTP is configured for the User
  • If so, require an OTP in order to satisfy the login requirements

Modify the Flow

Two modifications need to be made:

• Add an alternative webauthn step
• Switch OTP from required to alternative

1. click on the “+” next to “conditional OTP” step and click “Add step”
2. Search for “webauthn”
3. Add a “WebAuthn Authenticator” step - you should now see it at the bottom of the Conditional OTP flow in a disabled state
4. Switch the webauthn step from Disabled to Alternative
5. Switch the OTP Form step from Required to Alternative
6. use the six dots to the left of the webauthn step to drag it above the OTP Form step

Your flow should now look like this:

The flow now:

• Accepts a valid session cookie if it exists
• Requires the user to authenticate with a password
• checks if OTP is configured for the User
  • If so, requires EITHER:
    • A valid webauthn token response
    • An OTP

Bind the Flow

1. Click on the action dropdown in the upper right section of the page and select “Bind flow”
2. Select Browser flow

Now the default flow for all browser-based clients (the vast majority of your authentication requests) will use our webauthn-enabled flow.

Additionally, the “add security key” feature is now enabled on the user accounts/profile app found at: https://keycloak.example.com/realms/realm-name/account allowing users to self service and configure their webauthn devices.

Gotchas

As of Keycloak 23, The stock forms used by the account portal do not support prioritizing your MFA devices. By default, it will use them in the order you created them, which usually means that your OTP generator takes precedence over your security key.

A Keycloak admin can re-arrange a user’s MFA devices in order to prioritize their security key over their OTP generator the same way we organized the flow steps:

Alternatively modifications can be made to the account profile theme that supports re-arranging credentials. If hardware keys are a requirement in your environment it may be a better option to modify the realm’s required actions to register webauthn devices.