Install and deploy HCL Compass container with Single Sign On feature using Keycloak

Keycloak provides open source identity and access management and can be integrated with HCL Compass to support Single Sign On (SSO) in HCL Compass.

Before you begin

Note: Using HCL Compass on Docker and Docker Compose is not supported when deployed in a production environment. To use HCL Compass in a container in a production environment, deploy HCL Compass to a Kubernetes environment.

For more information, see Deploying HCL Compass on SoFy Sandbox.

To install and deploy Single Sign On for HCL Compass, note the following:

You must be familiar with and follow the instructions in Getting started with Docker.
You must be familiar with Keycloak integration.

Procedure

Set up Keycloak.
- The Keycloak Docker image requires you to specify both a private key and a certificate for serving HTTPS over port 8443. You must provide two files:
  - tls.crt: A certificate.
  - tls.key: A private key.
  You must set a keystore password during execution of the keytool and openssl commands. Replace HOST_NAME with your Keycloak hostname or IP address.
```
$ keytool -genkey -alias [HOST_NAME] -keyalg RSA -keystore keycloak.jks -validity 10950
$ keytool -importkeystore -srckeystore keycloak.jks -destkeystore keycloak.p12 -deststoretype PKCS12
$ openssl pkcs12 -in keycloak.p12 -nokeys -out tls.crt
$ openssl pkcs12 -in keycloak.p12 -nocerts -nodes -out tls.key
```
  Createa new folder named path/to/your/keycloak/tls, copy the tls.crt and tls.key files into this folder.
```
$ mkdir /path/to/your/keycloak/tls
$ cp tls.crt /path/to/your/keycloak/tls/.
$ cp tls.key /path/to/your/keycloak/tls/.
```
Deploy the Keycloak container.
- Set the Keycloak username and password.
- Set the hcl-compass URL.
- Mount the path/to/your/keycloak folder to the hcl-compass-keycloak container location /etc/x509/https.
```
docker run -d --name hcl-compass-keycloak -h hcl-compass-keycloak \
 --env KEYCLOAK_USER=admin \
 --env KEYCLOAK_PASSWORD=admin \
 --env CCM_URL=<hcl-compass_URL> \
 --env DASHBOARDS_URL=<Opensearch_Dashboards_URL> \
 -v /path/to/your/keycloak/tls/:/etc/x509/https \
 -p 8080:8080 -p 8445:8443 \
 hclcr.com/ccm-keycloak:2.2.0
```
- The hcl-compass-keycloak container is created with a default Realm configuration called HCL-Compass which includes a default Client ID named CCM and a default User with the username admin and password admin. To update the default Realm name and default Client ID name to your selected name, add the following environment variables to the above docker run command.
```
  --env  KEYCLOAK_REALM_NAME=<Custom_Realm_name> \
  --env  KEYCLOAK_CLIENT_NAME=<Custom_Client_ID> \
```
- To import your own realm configuration file during container deployment, set the KEYCLOAK_IMPORT environment variable to your realm configuration file name and mount the realm configuration folder to a folder in the hcl-compass-keycloak container. For example, if your realm configuration is valled keycloak-realm.json and it is located in /path/to/your/keycloak/realm-file/ folder, add the following to the above docker run command:
```
 --env  KEYCLOAK_IMPORT=/keycloak/<KEYCLOAK_REALM_IMPORT_FILE_NAME>  \
 -v /path/to/your/keycloak/realm-file/:/keycloak \
```
Add the following settings to the hcl-compass docker run command, as described in Getting started with Docker.
- Enable Keycloak, set Realmname, add username, password, and dashbaords client ID and secret.
- Enable SSO
- Add the SSO_CONFIG_SET environment variable and provide SSO configuration for each database repository during deployment of the hcl-compass container.
- Mount the path/to/your/keycloak-json folder to the hcl-compass container location /opt/hcl/compass/compass-rest-server-distribution/data/keycloak.
```
--env KEYCLOAK_ENABLED=TRUE \
--env KEYCLOAK_URL=https://localhost:8445 \
--env SSO_ENABLED=TRUE \
--env KEYCLOAK_REALM_NAME=CCM \
--env KEYCLOAK_USERNAME=admin \
--env KEYCLOAK_PASSWORD=admin \
--env KEYCLOAK_DASBOARDS_CLIENT_ID=dashboards-client \
--env KEYCLOAK_DASBOARDS_CLIENT_SECRET=58846041-eb1e-46d8-bac4-b2ba541ff49 \
--env SSO_ENABLED=TRUE  \ 
--env SSO_CONFIG_SET=(\"SSO_CONFIG_1\"\"SSO_CONFIG_2\" ..... \"SSO_CONFIG_n\") \
-v /path/to/your/keycloak-json/:/opt/hcl/compass/compass-rest-server-distribution/data/keycloak \
```
- Each SSO configuration SSO_CONFIX_x must be set with the following format:
```
-username [Username] -password [User password] -dbset [dbset_name] -ssousername [sso_user_name]
```
- The following example illustrates the proper configuration for a two SSO configuration. In this case, one is for DefectTracking-SAMPL and the other is for EssentialSAFe-SAMPL repository applications:
```
--env SSO_CONFIG_SET="(\" -username admin -password \"\" -dbset DefectTracking -ssousername SSO_USER\" \"-username admin -password \"\" -dbset EssentialSAFe -ssousername SSO_USER\")"
```
  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.
Enter https://localhost:8445/ in a browser to start the Keycloak Administration Console using the username and password that was set during deployment of the hcl-compass container.
- When you access the Keycloak Administration Console, you will see a default hcl-compass realm is already configured, and that it has a default CCM Client ID and a default user with username admin.
- To create more Keycloak users, follow the directions for Creating a User in the Keycloak documentation.
- For each Keycloak user, you must also create the same user in the HCL Compass user administration for each repository by following the directions for Adding a user.
Enter https://localhost:8190/ in a browser to see the HCL Compass application running with Single Sign On functionality. The deault Single Sign On user is admin with a default password admin.