W3C Web Authentication (WebAuthn)
Keycloak provides support for W3C Web Authentication (WebAuthn). Keycloak works as a WebAuthn’s Relying Party (RP).
|
WebAuthn’s operations success depends on the user’s WebAuthn supporting authenticator, browser, and platform. Make sure your authenticator, browser, and platform support the WebAuthn specification. |
Adding WebAuthn authentication to a browser flow
-
Click Authentication in the menu.
-
Click the Browser flow.
-
Select Duplicate from the "Action list" to make a copy of the built-in Browser flow.
-
Enter "WebAuthn Browser" as the name of the copy.
-
Click Duplicate.
-
Click the name to go to the details
-
Click the trash can icon 🗑️ of the "WebAuthn Browser Browser - Conditional OTP" and click Delete.
If you require WebAuthn for all users:
-
Click + menu of the WebAuthn Browser Forms.
-
Click Add step.
-
Click WebAuthn Authenticator.
-
Click Add.
-
Select Required for the WebAuthn Authenticator authentication type to set its requirement to required.
-
Click the Action menu on the top of the screen.
-
Select Bind flow from the drop-down list.
-
Select Browser from the drop-down list.
-
Click Save.
|
If a user does not have WebAuthn credentials, the user must register WebAuthn credentials. |
Users can log in with WebAuthn if they have a WebAuthn credential registered only. So instead of adding the WebAuthn Authenticator execution, you can:
-
Click + menu of the WebAuthn Browser Forms row.
-
Click Add sub-flow.
-
Enter "Conditional 2FA" for the name field.
-
On the WebAuthn Browser Forms row, click the plus sign + and select Add step.
-
Select Conditional for the Conditional 2FA to set its requirement to conditional.
-
On the Conditional 2FA row, click the plus sign + and select Add condition.
-
Click Add condition.
-
Select Condition - User Configured.
-
Click Add.
-
Select Required for the Condition - User Configured to set its requirement to required.
-
Drag and drop WebAuthn Authenticator into the Conditional 2FA flow
-
Select Alternative for the WebAuthn Authenticator to set its requirement to alernative.
The user can choose between using WebAuthn and OTP for the second factor:
-
On the Conditional 2FA row, click the plus sign + and select Add step.
-
Click Add step.
-
Select OTP Form from the list.
-
Click Add.
-
Select Alternative for the OTP Form to set its requirement to alernative.
Authenticate with WebAuthn authenticator
After registering a WebAuthn authenticator, the user carries out the following operations:
-
Open the login form. The user must authenticate with a username and password.
-
The user’s browser asks the user to authenticate by using their WebAuthn authenticator.
Managing WebAuthn as an administrator
Managing credentials
Keycloak manages WebAuthn credentials similarly to other credentials from User credential management:
-
Keycloak assigns users a required action to create a WebAuthn credential from the Reset Actions list and select Webauthn Register.
-
Administrators can delete a WebAuthn credential by clicking Delete.
-
Administrators can view the credential’s data, such as the AAGUID, by selecting Show data….
-
Administrators can set a label for the credential by setting a value in the User Label field and saving the data.
Managing policy
Administrators can configure WebAuthn related operations as WebAuthn Policy per realm.
-
Click Authentication in the menu.
-
Click the Policy tab.
-
Click the WebAuthn Policy tab.
-
Configure the items within the policy (see description below).
-
Click Save.
The configurable items and their description are as follows:
| Configuration | Description |
|---|---|
Relying Party Entity Name |
The readable server name as a WebAuthn Relying Party. This item is mandatory and applies to the registration of the WebAuthn authenticator. The default setting is "keycloak". For more details, see WebAuthn Specification. |
Signature Algorithms |
The algorithms telling the WebAuthn authenticator which signature algorithms to use for the Public Key Credential. Keycloak uses the Public Key Credential to sign and verify Authentication Assertions. If no algorithms exist, the default ES256 is adapted. ES256 is an optional configuration item applying to the registration of WebAuthn authenticators. For more details, see WebAuthn Specification. |
Relying Party ID |
The ID of a WebAuthn Relying Party that determines the scope of Public Key Credentials. The ID must be the origin’s effective domain. This ID is an optional configuration item applied to the registration of WebAuthn authenticators. If this entry is blank, Keycloak adapts the host part of Keycloak’s base URL. For more details, see WebAuthn Specification. |
Attestation Conveyance Preference |
The WebAuthn API implementation on the browser (WebAuthn Client) is the preferential method to generate Attestation statements. This preference is an optional configuration item applying to the registration of the WebAuthn authenticator. If no option exists, its behavior is the same as selecting "none". For more details, see WebAuthn Specification. |
Authenticator Attachment |
The acceptable attachment pattern of a WebAuthn authenticator for the WebAuthn Client. This pattern is an optional configuration item applying to the registration of the WebAuthn authenticator. For more details, see WebAuthn Specification. |
Require Resident Key |
The option requiring that the WebAuthn authenticator generates the Public Key Credential as Client-side-resident Public Key Credential Source. This option applies to the registration of the WebAuthn authenticator. If left blank, its behavior is the same as selecting "No". For more details, see WebAuthn Specification. |
User Verification Requirement |
The option requiring that the WebAuthn authenticator confirms the verification of a user. This is an optional configuration item applying to the registration of a WebAuthn authenticator and the authentication of a user by a WebAuthn authenticator. If no option exists, its behavior is the same as selecting "preferred". For more details, see WebAuthn Specification for registering a WebAuthn authenticator and WebAuthn Specification for authenticating the user by a WebAuthn authenticator. |
Timeout |
The timeout value, in seconds, for registering a WebAuthn authenticator and authenticating the user by using a WebAuthn authenticator. If set to zero, its behavior depends on the WebAuthn authenticator’s implementation. The default value is 0. For more details, see WebAuthn Specification for registering a WebAuthn authenticator and WebAuthn Specification for authenticating the user by a WebAuthn authenticator. |
Avoid Same Authenticator Registration |
If enabled, Keycloak cannot re-register an already registered WebAuthn authenticator. |
Acceptable AAGUIDs |
The white list of AAGUIDs which a WebAuthn authenticator must register against. |
Attestation statement verification
When registering a WebAuthn authenticator, Keycloak verifies the trustworthiness of the attestation statement generated by the WebAuthn authenticator. Keycloak requires the trust anchor’s certificates imported into the [truststore](https://www.keycloak.org/server/keycloak-truststore).
To omit this validation, disable this truststore or set the WebAuthn policy’s configuration item "Attestation Conveyance Preference" to "none".
Managing WebAuthn credentials as a user
Register WebAuthn authenticator
The appropriate method to register a WebAuthn authenticator depends on whether the user has already registered an account on Keycloak.
New user
If the WebAuthn Register required action is Default Action in a realm, new users must set up the WebAuthn security key after their first login.
-
Open the login form.
-
Click Register.
-
Fill in the items on the form.
-
Click Register.
After successfully registering, the browser asks the user to enter the text of their WebAuthn authenticator’s label.
Existing user
If WebAuthn Authenticator is set up as required as shown in the first example, then when existing users try to log in, they are required to register their WebAuthn authenticator automatically:
-
Open the login form.
-
Enter the items on the form.
-
Click Save.
-
Click Login.
After successful registration, the user’s browser asks the user to enter the text of their WebAuthn authenticator’s label.
Passwordless WebAuthn together with Two-Factor
Keycloak uses WebAuthn for two-factor authentication, but you can use WebAuthn as the first-factor authentication. In this case, users with passwordless WebAuthn credentials can authenticate to Keycloak without a password. Keycloak can use WebAuthn as both the passwordless and two-factor authentication mechanism in the context of a realm and a single authentication flow.
An administrator typically requires that Security Keys registered by users for the WebAuthn passwordless authentication meet different requirements. For example, the security keys may require users to authenticate to the security key using a PIN, or the security key attests with a stronger certificate authority.
Because of this, Keycloak permits administrators to configure a separate WebAuthn Passwordless Policy. There is a required Webauthn Register Passwordless action of type and separate authenticator of type WebAuthn Passwordless Authenticator.
Setup
Set up WebAuthn passwordless support as follows:
-
(if not already present) Register a new required action for WebAuthn passwordless support. Use the steps described in Enable WebAuthn Authenticator Registration. Register the
Webauthn Register Passwordlessaction. -
Configure the policy. You can use the steps and configuration options described in Managing Policy. Perform the configuration in the Admin Console in the tab WebAuthn Passwordless Policy. Typically the requirements for the security key will be stronger than for the two-factor policy. For example, you can set the User Verification Requirement to Required when you configure the passwordless policy.
-
Configure the authentication flow. Use the WebAuthn Browser flow described in Adding WebAuthn Authentication to a Browser Flow. Configure the flow as follows:
-
The WebAuthn Browser Forms subflow contains Username Form as the first authenticator. Delete the default Username Password Form authenticator and add the Username Form authenticator. This action requires the user to provide a username as the first step.
-
There will be a required subflow, which can be named Passwordless Or Two-factor, for example. This subflow indicates the user can authenticate with Passwordless WebAuthn credential or with Two-factor authentication.
-
The flow contains WebAuthn Passwordless Authenticator as the first alternative.
-
The second alternative will be a subflow named Password And Two-factor Webauthn, for example. This subflow contains a Password Form and a WebAuthn Authenticator.
-
The final configuration of the flow looks similar to this:
You can now add WebAuthn Register Passwordless as the required action to a user, already known to Keycloak, to test this. During the first authentication, the user must use the password and second-factor WebAuthn credential. The user does not need to provide the password and second-factor WebAuthn credential if they use the WebAuthn Passwordless credential.
LoginLess WebAuthn
Keycloak uses WebAuthn for two-factor authentication, but you can use WebAuthn as the first-factor authentication. In this case, users with passwordless WebAuthn credentials can authenticate to Keycloak without submitting a login or a password. Keycloak can use WebAuthn as both the loginless/passwordless and two-factor authentication mechanism in the context of a realm.
An administrator typically requires that Security Keys registered by users for the WebAuthn loginless authentication meet different requirements. Loginless authentication requires users to authenticate to the security key (for example by using a PIN code or a fingerprint) and that the cryptographic keys associated with the loginless credential are stored physically on the security key. Not all security keys meet that kind of requirements. Check with your security key vendor if your device supports 'user verification' and 'resident key'. See Supported Security Keys.
Keycloak permits administrators to configure the WebAuthn Passwordless Policy in a way that allows loginless authentication. Note that loginless authentication can only be configured with WebAuthn Passwordless Policy and with WebAuthn Passwordless credentials. WebAuthn loginless authentication and WebAuthn passwordless authentication can be configured on the same realm but will share the same policy WebAuthn Passwordless Policy.
Setup
Set up WebAuthn Loginless support as follows:
-
(if not already present) Register a new required action for WebAuthn passwordless support. Use the steps described in Enable WebAuthn Authenticator Registration. Register the
Webauthn Register Passwordlessaction. -
Configure the
WebAuthn Passwordless Policy. Perform the configuration in the Admin Console,Authenticationsection, in the tabPolicies→WebAuthn Passwordless Policy. You have to set User Verification Requirement to required and Require Resident Key to Yes when you configure the policy for loginless scenario. Note that since there isn’t a dedicated Loginless policy it won’t be possible to mix authentication scenarios with user verification=no/resident key=no and loginless scenarios (user verification=yes/resident key=yes). Storage capacity is usually very limited on security keys meaning that you won’t be able to store many resident keys on your security key. -
Configure the authentication flow. Create a new authentication flow, add the "WebAuthn Passwordless" execution and set the Requirement setting of the execution to Required
The final configuration of the flow looks similar to this:
You can now add the required action WebAuthn Register Passwordless to a user, already known to Keycloak, to test this. The user with the required action configured will have to authenticate (with a username/password for example) and will then be prompted to register a security key to be used for loginless authentication.
Vendor specific remarks
Compatibility check list
Loginless authentication with Keycloak requires the security key to meet the following features
-
FIDO2 compliance: not to be confused with FIDO/U2F
-
User verification: the ability for the security key to authenticate the user (prevents someone finding your security key to be able to authenticate loginless and passwordless)
-
Resident key: the ability for the security key to store the login and the cryptographic keys associated with the client application
Windows Hello
To use Windows Hello based credentials to authenticate against Keycloak, configure the Signature Algorithms setting of the WebAuthn Passwordless Policy to include the RS256 value. Note that some browsers don’t allow access to platform security key (like Windows Hello) inside private windows.