Web Authentication(WebAuthn) sample plugin for Keycloak , implements with webauthn4j.
The webauthn's support based on this repository has been merged into keycloak master and released in keycloak-8.0.0. Therefore, this project will not be maintained basically and can not work on keycloak-8.0.0 and later version.
This sample plugin is developed in order to implement features defined in the design document for WebAuthn support onto keycloak, clarify issues for realizing these features and give feedback onto this design document.
If you use the previous commits or versions, please first undeploy it, and after that, deploy the ear of the current version or commit.
$ mvn wildfly:undeploy
$ mvn clean install wildfly:deploy
If not undeploy the existing ear, an error occurs. This is because the current version removed RegisterAuthenticator implemented as Authenticator considering the issue.
We've confirmed that this demo had worked well under the following environments:
2 Factor Authentication with Resident Key Not supported Authenticator Scenario
2 Factor Authentication with Resident Key Not supported Authenticator Scenario
2 Factor Authentication with Resident Key supported Authenticator Scenario
2 Factor Authentication with Resident Key supported Authenticator Scenario
Authentication with Resident Key supported Authenticator Scenario
Authentication with Resident Key supported Authenticator Scenario
Build:
$ mvn install
Add the EAR file to the Keycloak Server:
$ cp webauthn4j-ear/target/keycloak-webauthn4j-ear-*.ear $KEYCLOAK_HOME/standalone/deployments/
Or deploy the EAR file dynamically when the Keycloak Server is running:
$ mvn clean install wildfly:deploy
Report coverage
$ mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent test
$ mvn org.jacoco:jacoco-maven-plugin:report
This prototype consists of two components:
This enables users to register their accounts on keycloak with their authenticators' generating public key credentials. It is implemented as Required Action
.
This enables users to authenticate themselves on keycloak by their authenticators. It is implemented as Authenticator
.
To enable user without their accounts on keycloak to register them on the authentication flow:
User registration
in 'Realm Settings' - 'Login'To enable users to register their accounts with their authenticators' creating public key credentials:
register Webauthn Register
Required Action in 'Required Actons' - 'Register'
check Enabled
and Default Action
for registered Webauthn Register
Required Action
To enable users having their accounts on keycloak to authenticate themselves on keycloak by their authenticators:
Auth Type | Requirement | |
---|---|---|
Cookie | ALTERNATIVE | |
Kerberos | DISABLED | |
Identity Provider Redirector | ALTERNATIVE | |
Copy of Browser Forms | ALTERNATIVE | |
Username Password Form | REQUIRED | |
OTP Form | OPTIONAL | |
WebAuthn Authenticator | REQUIRED |
Resident Key
)Auth Type | Requirement | |
---|---|---|
Cookie | ALTERNATIVE | |
Kerberos | DISABLED | |
Identity Provider Redirector | ALTERNATIVE | |
WebAuthn Authenticator | REQUIRED |
The user can only register their own authenticator. The user and the administrator can manage the registered authenticator. For the user to do so, the administrator set Realm Settings -> Themes -> Account Theme
to "webauthn".
As the metadata of the authenticator, the user can put the editable label onto their authenticator to identify it when registering it.
The user and the administrator can edit this label.
If the user wants to edit this label, please access to User Account Service and edit Public Key Credential Label
.
If the administrator wants to edit some user's registered authenticator's label, please access to Users -> (User Name) -> Attributes
and edit public_key_credential_label
.
As the metadata of the authenticator, its AAGUID is stored onto keycloak when registering it.
The user and the administrator can view this AAGUID.
If the user wants to view this AAGUID, please access to User Account Service and look up Public Key Credential AAGUID
.
If the administrator wants to view some user's registered authenticator's label, please access to Users -> (User Name) -> Attributes
and look up public_key_credential_aaguid
.
The user and the administrator can delete the registered authenticator.
If the user wants to delete its own regestered authenticator, please access to User Account Service and clean up Public Key Credential ID
, Public Key Credential Label
and Public Key Credential AAGUID
.
If the administrator wants to delete some user's registered authenticator, please access to Users -> (User Name) -> Attributes
and delete public_key_credential_id
, public_key_credential_label
and public_key_credential_aaguid
.
The user can re-register the authenticator.
The administrator goes to Users -> (User Name) -> Details
and add WebAuthn Register
as Required User Actions
.
The user logs onto keycoak. After authentication in the login form, keycloak asks them to register ther authenticator.
Browser Flow (Use Resident Key
) automatically asks users to authenticate on their authenticators. Therefore, the users without their accounts have no chance to register them on this flow.
For such the users to register their accounts, please use the default Browser Flow. It is helpful to user Authentication Flow Overrides
on Client Settings. You can set the default Browser Flow for User Account Service (Client ID: account) to let users register their accounts at first.
On registration, the browser asks you if you would like to store ID and its credential on your authenticator(namely, Resident Key). If you push OK button, the browser tells your authenticator to do so explicitly. If not, whether ID and its credential is Resident Key or not depends on authenticators.
Please note the followings:
In Authentication with Resident Key supported Authenticator Scenario, only user's ID and its credential as Resident Key can be valid. Therefore, if you register ID and its credential that is not as Resident Key and try to authenticate with them, you fail to authenticate.
Not all authenticators are capable of this Resident Key. The Authenticator lack of Resident Key capability fails to register user's ID and its credential when Resident Key is required explicitly.
Not all browsers support this Resident Key. At least, I've confirmed that Microsoft Edge (ver.44) supports Resident Key.