How to Configure Microsoft Azure Active Directory as Keycloak Identity Provider to Enable Single Sign-On for HCL Compass

HCL Compass version 2.0.3 introduced a Single Sign-On option for customers powered by Keycloak. Keycloak is an open-source identity and access management tool that allows users to configure various identity providers for authentication. Below is a step-by-step overview of the process of configuring Microsoft Azure Active Directory as an identity provider for Keycloak to extend single sign-on for HCL Compass to Azure Active Directory users. For the below steps, we will assume that there is an already existing Azure Active Directory multi-tenant or single-tenant. For more detailed information on integrating Keycloak with HCL Compass refer to our product documentation.

Configuring Microsoft Azure Application Registration

1. Create an Application Registration for Keycloak

This application will be what Keycloak uses to authenticate your active directory users with your Azure tenant. Navigate to https://portal.azure.com and select the App registrations option under the Azure servicessection.

• Note: You will need administrative permissions to create an app registration.

Select the New registration option in the upper left-hand corner.

Provide a name for the application you are registering and select the account type that you would like to be supported (multi-tenant or single-tenant). Then select the register button.

Once you have registered your application you will be returned to the Application registration’s overview page. Note your Application (client) ID as you will need it later when creating your identity provider in the Keycloak administration console.

2.Create a Client Secret for your Newly Registered Application

Navigate to the Certificates and secrets section. Create a new client secret and copy the client secret value that was generated as you will need to use this when establishing your identity provider in the Keycloak administration console.

Create Realm and Client in Keycloak Administration Console

1. Sign into the Keycloak Administration Console

Follow Keycloak documentation to get your Keycloak server setup and running in your environment. There are multiple ways to host your Keycloak instance. If you would like to download the standalone server and run the bin/standlone.sh script, you can download the distribution file here:

• https://www.keycloak.org/downloads.html

If you would like to use containerization to host your Keycloak instance you can find the jboss/keycloak image in Docker Hub and follow the instructions found here:

• https://hub.docker.com/r/jboss/keycloak/

Once you have the Keycloak server up and running, login to the Keycloak admin console. Depending on how you have configured Keycloak, you should be able to access the admin console at https://hostname:8443/authwhere hostname is the name of your Keycloak server.

2. Create a Realm

After logging into the Keycloak admin console with your admin credentials, click the Select realm option and select the Add realm option. A Keycloak realm secures and manages a set of users, credentials, roles, and groups. Realms are isolated from one another and can only manage and authenticate the users that are created within their realm. Realms can only be created and managed by Keycloak admins.

3. Create and Configure a Client within your Newly Created Realm

Select the Clients tab from the sidebar and select the Create button in the right-hand corner to create a new client. Note that the access type for the client should be set to Public and your valid redirect URI should specify the URI where your HCL Compass instance is running. You must specify the wildcard in your URI, so that any extension in HCL Compass’ application may be navigated to after successful authentication. Specify the root URL where Compass is running. Note that by default Compass runs on port 8190. This can be changed by editing the server.port property in the application.properties file for Compass on your machine. When this port is set to 443, as done in the following examples, only your hostname will be needed to navigate to Compass. For example, https://hostname, where hostname is the name of your server.

Create Microsoft Identity Provider in Keycloak Administration Console

Identity Provider for Microsoft Azure Multi-Tenant Applications

Note: If you have registered a single-tenant application in Microsoft Azure, skip this section and follow the steps in the section below titled “Identity Provider for Microsoft Azure Single-Tenant Applications.”

1. Add Microsoft as an Identify Provider in your Realm

Navigate to the Identity Provider tab and select Microsoft as your provider from the dropdown list. You will now use the client ID and client secret value that you previously saved when registering your application in Microsoft Azure. Once you have entered these values in their respective fields click save. Note your redirect URI as you will need to use it in the following step.

2. Add Redirect URI generated from Keycloak to Azure Application Registration

Navigate back to https://portal.azure.com and return to the app that you registered in the previous steps. Under the Overview section for the registered app select the Add a Redirect URI option. Then select the Add a platform option and select the Web option as your platform. Next copy the redirect URI you saved when configuring your identity provider in Keycloak and paste it into the Redirect URI option for the platform you’re configuring in Azure.

Identity Provider for Microsoft Azure Single-Tenant Applications

1. Create OpenID Connect v1.0 as an Identity Provider in your Realm

Navigate to the Identity Provider tab and select OpenID Connect v1.0 as your provider from the dropdown list.

Make sure to note the redirect URI for your identity provider as you will need to use it in the following step. 

Navigate to the Import from URL section and paste the following url where directoryID is the Directory (tenant) ID for your Azure single-tenant application that you have registered.

https://login.microsoftonline.com/{directoryID}/v2.0/.well-known/openid-configuration

Then press the import button and the following settings should be automatically populated for the identity provider: Authorization URL, Token URL, Logout URL, User Info URL, Issuer, and JWKS URL. You will now use the client ID and client secret value that you previously saved when registering your application in Microsoft Azure. Once you have entered these values in their respective fields, navigate to the Client Authorization setting and select the client secret sent as basic auth option. Then save the identity provider which you have configured.

Configuring Default Identity Provider Redirector (Optional)

1. Set Default Identity Provider for Browser Authentication Flow

If you want to ensure that users are automatically redirected to your identity provider instead of the Keycloak login page when using single-sign-on with Compass, you must specify the default identity provider redirector. Navigate to the Authentication tab on the sidebar in the Keycloak admin console. Under the Flows tab ensure that the Browser option is selected from the dropdown list. Then for the Identity Provider Redirectoroption select Actions and then Config.

Set the Default Identity Provider value to “microsoft.” Then click the Save button.

Once this is configured upon selection of the SSO option on the Compass login page, the user will no longer be redirected to the Keycloak login page, but instead will be automatically redirected to Microsoft’s login page.

Configuring HCL Compass to use Keycloak as a Single Sign-On Provider

1. Download the keycloak.json File for the Client

Navigate back to your Keycloak administration console and select the client that you created in the previous steps. Navigate to the Installation tab for your client and select Keycloak OIDC JSON as the format option. Download this file and note its location.

2. Copy the Downloaded keycloak.json File to the API Server’s “/config” Folder

Locate the API server’s “/config” folder or if necessary add a config folder in the same location where the “application.properties” file is located and add the keycloak.json file that you downloaded into this folder.

3. Enable Keycloak Integration in “application.properties”

Set the keycloak.enabled property that is located in the “application.properties” file on the API server to be true to ensure that Keycloak is enabled.

4. Call Setup Script to Enable SSO

Ensure that your HCL Compass API server is running. If it was currently running for the previous steps, you will need to re-start it to ensure that the saved changes are applied.

For each repo for which you want to enable SSO, call the below setup script from the “/bin” directory.

• CQPerl setupSSO.pl <repository_name> <admin_user_name> <sso_user_name>

5. Ensure HCL Compass User Exists with the Same Keycloak Login Username

An HCL Compass user with the Keycloak login name should exist or should be created in the HCL Compass User Administration tool. For example, if you logged into your Microsoft account using your email: compass.user@hcl.com then you must ensure that a user has been created in HCL Compass with the username compass.user@hcl.com.

Using Microsoft Azure Active Directory Credentials for HCL Compass Authentication

1. Select Use SSO Identity Option to Sign into HCL Compass

If Keycloak has been enabled successfully, the HCL Compass login dialog will show a Use SSO Identityoption. Once this option is selected, the username and password input fields will be disabled. Select the application in which you have enabled Keycloak and click Login.

If the default identity provider option was set to “microsoft”, then upon selecting the Use SSO Identity option on the Compass Login page you will be automatically redirected to the Microsoft login page.

Otherwise, if no default identity provider has been set then you will be redirected to the Keycloak login page. On the Keycloak login page you will see a Microsoft login option available.

2. Enter Microsoft Azure Active Directory Credentials

Upon a successful login using Microsoft credentials, the user should be redirected to the HCL Compass welcome page.

Now that Microsoft Azure Active Directory has been configured as an identity provider, if the user is already signed into their Microsoft account they will be automatically authenticated and redirected to HCL Compass’ welcome page. This reduces login time and allows a user to be signed into multiple applications with the same set of credentials.

What other SSO identity providers would you like to use with HCL Compass?

Let us know in the comments!

Need more information about HCL Compass?

HCL Compass is a low-code/no-code change management software for enterprise level scaling, process customization, and control to accelerate project delivery and increase developer productivity. If this sounds right for you, visit our site and explore the benefits of becoming an HCL Compass user.