Adding MFA to your Keycloak login flow
Learn how to add MFA to your Keycloak login flow with Authsignal.
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.
MFA challenge via Authsignal pre-built UI.
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
Enable authenticators
Head to the Authenticators section in the Authsignal Portal to configure authenticators.
For this example, we have enabled Authenticator App.
Get API keys
Head to the API Keys section in the Authsignal Portal to get your API keys.
Keycloak configuration
Creating a new provider
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.
Download the Authsignal Java SDK JAR file
Download the Authsignal (version 2.0+) Java SDK (dependency) JAR file from Maven.
Copy the JAR files to the /providers/ directory
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:
Access your Keycloak Admin panel
Navigate to your project's Realm, and then to the 'Authentication' section
Select the 'browser' flow
Accessing the browser flow
Create a copy of this flow using the 'Action' dropdown in the top-right
Creating a copy of the browser flow
In your new copied flow, remove the existing 'Conditional OTP' authentication step.
Removing the existing Conditional OTP step
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.
Adding the Authsignal provider step
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.
Adding the Authsignal provider step
After adding the Authsignal Authenticator step
Ensure the Authsignal Authenticator step is required.
Ensuring the Authsignal Authenticator step is required
Click the settings cog on the Authsignal Authenticator step.
Add your secret key and API URL
Configuring the Authsignal Authenticator
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.
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.