Installing HCL Compass by using the keycloak.json file

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

Create a new folder named path/to/your/keycloak-json and copy the keycloak.json file in this folder.
```
$ mkdir /path/to/your/keycloak-json
$ cp keycloak.json /path/to/your/keycloak-json/.
```
Add the following settings to the hcl-compass docker run command, as described in Getting started with Docker.
- 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=<KEYCLOAK_URL> \
--env KEYCLOAK_DASBOARDS_CLIENT_ID=<KEYCLOAK_DASBOARDS_CLIENT_ID> \
--env KEYCLOAK_DASBOARDS_CLIENT_SECRET=<KEYCLOAK_DASBOARDS_CLIENT_SECRET> \
--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:8190/ in a browser to see the HCL Compass application running with Single Sign On functionality.