Use WebAuthn authentication in keycloak

No one likes passwords (except hackers)

With @loicdesroc we are building our own business, around authentication. When we started please-open.it we realised authentication was an everyday work

What is WebAuthn

Webauthn is the new authentication protocol, validated by the W3C last march :
https://www.w3.org/TR/webauthn/

In a few words : passwordless authentication

It is a public key-based authentication for web applications.

WebAuthn VS Credential management

Credentials management

Credential management is also a W3C recomendation : https://www.w3.org/TR/credential-management-1 It is a frontend only feature, which you can easily integrate in your login web form.

Example : https://credential-management-sample.appspot.com/
explainations : https://developers.google.com/web/updates/2017/06/credential-management-updates

We think as developers you MUST include such a feature in your login forms.

Google has a great password manager included in chrome and also available on your Google account : https://passwords.google.com/?standalone=false&hl=en&utm_source=google-account&utm_medium=web

Your browser suggests a strong password to match the website's constraints and keeps it for you.

The process behind is never changed, no backend modification, also the same security issues for many websites based on old frameworks...

Webauthn

Webauthn is not a small evolution of the user interface. It is a new way of registering and login as a user.

Auth0 has a great explaination here : https://webauthn.me/introduction

https://www.scottbrady91.com/FIDO/A-FIDO2-Primer-and-Proof-of-Concept-using-ASPNET-Core

from : https://webauthn.me/introduction

It uses some authentication hardware or biometric devices, on operating systems that are FIDO2 certified.

Microsoft Hello has recently being certified FIDO2 : Microsoft Windows 10 tech community blog post

I have no biometric sensor on my Xiaomi Air 13.3 laptop, so I have this simple USB FIDO key for 5.5€

Keycloak and webauthn support

Official support status

Currently, Keycloak does not support webauthn natively. They planned a two-factor authentication with WebAuth.

https://www.keycloak.org/2019/03/w3c-web-authentication-(webauthn).html

https://github.com/webauthn4j/webauthn4j team is working hard for a V1.0 soon.

See more : https://webauthn4j.github.io/webauthn4j/en/

Keycloak webauthn authenticator

https://github.com/webauthn4j/keycloak-webauthn-authenticator

This keycloak plugin is based on the last version of webauthn4j library. Be carreful, it is not already in a production state.

How to build and install

As show in the documentation, you need a JDK and maven to build it. A simpler way is to use a docker image with maven and a volume.

        
            git clone https://github.com/webauthn4j/keycloak-webauthn-authenticator.git
            docker run -ti -v /please-open.it/keycloak/keycloak-webauthn-authenticator/:/usr/src/app/ zenika/alpine-maven mvn install
            # /please-open.it/keycloak/keycloak-webauthn-authenticator is the directory where I cloned git repository.
        
    

Then, I copied it to my keycloak container :

            
                docker cp /please-open.it/keycloak/keycloak-webauthn-authenticator/webauthn4j-ear/keycloak-webauthn4j-ear-0.3.RELEASE.ear keycloak:/opt/jboss/keycloak/standalone/deployments
                # for a clean installation
                docker restart keycloak
            
        

Users registration

There is 2 ways of registering users with a webauthn support : as a second factor or as a password replacement.

For those twice possibilities, we need to register a public key to each user. Using the WebAuthn Register component, we have to add it as a required action.

Add the webauthn register and check it as a default action.

Now open a login page (using, IE the account detail app : https://myKeycloak/auth/realms/myRealm/account and register a new user :

Next step will ask you for your authenticator :

Now the user is correctly registered. In the users list, you see your registered user. Because webauthn authenticator operates as a plugin, the public key is stored in an attribute :

Users authentication

The master piece of hacking in this part is replacing the browser login flow by a new one based on a copy of the original, incluing the new webauthn authenticator.

Go to "authentication", select the "browser" flow an make a copy using the "copy" button.

Now in the new flow, use "Add execution" button to add "WebAuthn Authenticator" provider.

We state it as required in our flow. You can make it as an alternative authentication method.

In the bindings tab, change the browser flow to your newly crated flow.

By removing "Username Password Form" execution in "Browser flow" and replace it by "Choose user" execution, you will have a new login form.

The new login form has only a username field. The next step is the webauthn process.

This is a little trick. The "Choose user" is used in "Forgot password" process, that's why we have the title.

Have you noticed ? No more password... \o/

Want to test it ?

Where is a "standard" version, with webauthn as a 2nd factor. You do not need any valid email to try it.

https://app.please-open.it/auth/realms/internal.please-open.it/account