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.
Before you begin
Note: Use of the REST API server is not supported in an on premises environment,
such as on Windows and Linux. To use the HCL Compass REST API server in a supported
environment, deploy the HCL Compass REST
API server to a Kubernetes environment. For more information, see Getting Started with HCL Compass Helm Chart.
Note: The following instructions were written based on the Keycloak
docker image install.
About this task
Procedure
-
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.
-
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.
- 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.
- 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
- 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.
-
Configure Keycloak in HCL Compass.
- enable Keycloak integration in the application.properties file.
Set
keycloak.enabled=true
. - Copy the keycloak.json file to the REST API servers
/share
folder. - Restart the HCL Compass REST API server.
- 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.
- enable Keycloak integration in the application.properties file.
Set
-
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 thekeycloak-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 . If view-users is listed in the Assigned Role field, you can create Compass users without needing to use the Compass administration tool.
- Click the Members tab.
- Click the + sign to add a user.
- 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.
- Click Add Member.