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:
Procedure
-
Set up Keycloak.
- The Keycloak Docker image requires you to specify both a pricate 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 COMPASS_URL=<HCL_COMPASS_URL> \
-v /path/to/your/keycloak/tls/:/etc/x509/https \
-p 8080:8080 -p 8445:8443 \
compass-docker-dev-local.us-artifactory1.nonprod.hclpnp.com/compass-keycloak:2.0.4
-
The
hcl-compass-keycloak container is created with a default Realm
configuration called
HCL-Compass
which includes a default Client ID named
Compass 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 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 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
Compass
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.