Keycloak

​

Overview

Keycloak is an open-source identity and access management solution that offers a wide range of authentication capabilities. These capabilities can be extended and tailored to specific project requirements using custom providers, which act as modular extensions to Keycloak’s core functionality. 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.

​

Code Example

You can find the Keycloak provider code example referenced in this guide on GitHub. For advanced situations, you can modify the provider to meet your specific requirements. However, this provider should work for most use cases.

​

Authsignal Configuration

​

Enabling authenticators

For the purposes of this example, we have enabled the Authenticator App on our tenant in the Authsignal Portal.

​

API keys & region URL

We also need to get the API keys and region URL for our tenant from the Authsignal Portal.

We will use the secret and the region URL in the next section.

​

Keycloak Configuration

​

Creating a new provider

1. 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 (version 2.0+) Java SDK (dependency) JAR file from Maven.
3. Copy the above two JAR files to your Keycloak server /providers/ directory.

​

Configuring the Authsignal Authentication Flow

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 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 file 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 that the Authsignal authenticator step is required.

9. Click the settings cog on the Authsignal authenticator step. Add your API keys and region URL from the Authsignal Portal.

​

Conclusion

That’s it! You’ve successfully added MFA by integrating Keycloak with Authsignal.