Keycloak integration

Keycloak provides open source identity and access management and can be integrated with HCL Compass to help you manage your HCL Compass users.

1. In Keycloak, if you do not already have a Realm, you must create one. Using the Select Realm dropdown menu, select Add Realm. Provide a name for your realm and click Create.
   If you use Keycloak in environments outside of HCL Compass and you have already created a realm, you can skip this step.
2. In your realm, under Configure, select User Federation or Identity Providers. Which option you choose will depend on which user authentication service you plan to use.
   Note: If you are configuring an identity provider in Keycloak, you must create a new authentication flow for that identity provider so that Keycloak detects users on their first login. The HCL Compass server automatically creates users in Keycloak when a user is invited or when the Keycloak administrator clicks the Validate SSO button from the Server Setup page.

   This authentication flow must be created and set for the identity providers First Login Flow option. This will ensure that when a user signs in for the first time using the credentials from their identity provider, that the user will be appropriately mapped to the already created user in Keycloak.

   For more information on creating and configuring the authentication flow, see Automatically link existing first login flow.

3. Add a client to your realm by selecting Clients. In the Client ID field, enter in an ID that is specific to HCL Compass. Enter in values for Client Protocol and Root URL. The Root URL field must point to where your HCL Compass REST API server is located. Click Save.
4. Configure your client in the Settings screen. Ensure that the Access Type is set to Public, and that you have values entered in both the Valid Redirect URIs and the Web Origins fields. These are the only fields that are required to setup Keycloak with HCL Compass. All others fields are optional
5. Download the keycloak.json file for the client in the Installation tab. Select the format that you want the file in by using the Format Option dropdown and then select Download.
6. Configure Keycloak in HCL Compass.
   1. enable Keycloak integration in the application.properties file. Set keycloak.enabled=true.
   2. Copy the keycloak.json file to the REST API servers /share folder.
   3. Restart the HCL Compass REST API server.
   4. To enable SSO for each required repository, the administrator must sign into the application, navigate to the Server Setup page, and click the Validate SSO button. Alternatively, the setup script that is located in the /bin directory can be called for the same purpose with the following syntax:

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

      Note: The value for <sso_user_name> should be an internal name provided by the administrator. This name should be unique and should not be used for any other function in HCL Compass.
7. When configuring HCL Compass, an HCL Compass user with the Keycloak login name must be created in the HCL Compass user administration. The Keycloak login name can vary based upon the User Federation that is being used. By default, HCL Compass uses the preferred_username field from Keycloak to determine the HCL Compass username. To change this to email, update the keycloak-mapping-field in the application.properties file.
   Note: HCL Compass administrative users can add Keycloak users without needing to create a user in the Compass Administration Tool. The administrative user must:

   • Be a Keycloak user
   • Have the view-users role assigned to them. To check, click Role Mappings > Client Roles > Realm Management > Assigned Role. If view-users is listed in the Assigned Role field, you can create Compass users without needing to use the Compass administration tool.

   To create a Compass user from within the UI, perform the followings steps:

   1. Click the Members tab.
   2. Click the + sign to add a user.
   3. The search box will search for users in Keycloak and in Compass. If the user is listed in Keycloak, but not listed in Compass, Compass will create a Compass user for that member.
   4. Click Add Member.

   When searching for users, if you encounter a message that says You do not have privileges to view Keycloak users, go to Keycloak and ensure that the Compass administrative user has the view-users role assigned to them in Keycloak.