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.
3. Add a client to your realm by selecting Clients. In the Client ID field, entire 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 /data folder.
   3. Restart the HCL Compass REST API server.
   4. Call the setup script that is located in the /bin directory to enable SSO for each repository that you require:

      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.