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.
In order to use Keycloak authentication with
HCL Compass, you must first have Keycloak installed.
If you do not already have Keycloak installed and configured, see the
Keycloak
Documentation.
Note: HCL Compass
supports the following versions of Keycloak:
- Docker Images:
- jboss/keycloak: Version 16.1.1
- jboss/keycloak: Version 15.0.2
- Standalone versions:
- All versions of Keycloak 15.x
- All versions of Keycloak 16.x
About this task
After Keycloak is installed, you can integrate Keycloak into
your HCL Compass environment by
performing the following steps:
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.
-
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 . 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:
- 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.
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.
What to do next
Login to HCL Compass. Selecting Sign
in will redirect the user to the Keycloak login dialog. A success login
redirects the user back to HCL Compass
where the users accessible application are displayed. Click the Let's
go! button on any application to proceed to the HCL Compass applications welcome
page.