Skip to main content

​
Overview

In this guide, we will demonstrate how to leverage a Keycloak provider to seamlessly integrate MFA into a traditional username and password login flow using Authsignal’s pre-built UI, enhancing security with minimal disruption to the user experience.

Keycloak provider code example
The above example can be extended to meet your specific requirements.

​
Prerequisites

This guide assumes you have a basic understanding of Keycloak and Authsignal. If you are new to Keycloak, we recommend you follow the Keycloak Quickstart guide to get up and running.

​
Authsignal configuration

1

Enable authenticators

Head to the Authenticators section in the Authsignal Portal to configure authenticators.For this example, we have enabled Authenticator App.
2

Get API keys

Head to the API Keys section in the Authsignal Portal to get your API keys.

​
Keycloak configuration

​
Creating a new provider

1

Download the provider JAR files

Download the pre-built authsignal-keycloak-*.jar JAR file. Alternatively, you can build the JAR file yourself using the GitHub repository.
2

Download the Authsignal Java SDK JAR file

Download the Authsignal (version 2.0+) Java SDK (dependency) JAR file from Maven.
3

​
Configuring the Authsignal Authentication flow

If you have not already created a Keycloak realm, do this by clicking the Create realm button in the Keycloak admin UI (within the Keycloak drop-down menu top left).
After installing the provider JAR files, you’ll need to configure Keycloak to use Authsignal for MFA. This section walks through setting up a custom authentication flow that incorporates the Authsignal Authenticator. To configure the authentication flow:
1

Access your Keycloak Admin panel

2

Navigate to your project's Realm, and then to the 'Authentication' section

3

Select the 'browser' flow

4

Create a copy of this flow using the 'Action' dropdown in the top-right

5

In your new copied flow, remove the existing 'Conditional OTP' authentication step.

6

Add the Authsignal provider to the flow.

Inside the subflow which already contains the ‘Username Password Form’, we need to add the Authsignal provider as a step.
7

Select the Authsignal Authenticator.

If you successfully added the Authsignal .JAR files to the /providers/ folder in the previous steps, you will see the Authsignal Authenticator listed in the menu - select it to add it to your flow.

8

Ensure the Authsignal Authenticator step is required.

9

Click the settings cog on the Authsignal Authenticator step.

Add your Server API secret key and API host.
When Enroll by default is toggled on, users will be prompted to enroll an authenticator when they first log in. If toggled off, the user will not be prompted to enroll an authenticator, and you will need to handle enrollment programmatically.
10

Enable the new Authsignal flow

Finally, click the Action -> Bind flow button. Select the browser flow to enable the new Authsignal flow.

​
Conclusion

That’s it! You’ve successfully added MFA to your Keycloak login flow using Authsignal. To test the flow, log in and you will be prompted to enroll an authenticator. The next time you log in, you will be prompted to complete an MFA challenge.
Want to use Keycloak groups and roles in your authentication rules? See the Groups and Roles guide for instructions on setting this up.