Enabling the HCL Compass Keycloak Single Sign On feature

You can enable the Keycloak Single Sign On feature to install and deploy the Keycloak service with the hcl-compass helm chart or you can enable the Keycloak Single Sign On feature by using an external Keycloak instance that is installed outside of the hcl-compass helm chart.

Before you begin

Before you can start setting up HCL Compass Single Sign On, you must first setup Keycloak TLS (SSL).

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/.
```

Procedure

Enable Keycloak Single Sign on by using one of the following methods:

Installing and deploying Keycloak with the hcl-compass helm chart.
Using external Keycloak running outside of the hcl-compass helm chart
Enable the Single Sign On (Keycloak) feature using Keycloak running on HCL Compass Solution Console

To enable Keycloak Single Sign On by installing and deploying Keycloak with the hcl-compass helm chart:
1. Create a keycloak-tls configMap for Keycloak TLS (SSL) files:
  1. Create a new folder named path/to/your/keycloak/tls that contains both the tls.crt and tls.key files.
```
$ mkdir /path/to/your/keycloak/tls
```
  2. Add the tls.crt and tls.key files from the path/to/your/keycloak/tls folder to the configMap called keycloak-tls.
```
$ kubectl create configmap keycloak-tls --from-file /path/to/your/keycloak/tls/ --namespace [namespace_name]
```
  3. Ensure that the configMap keycloak-tls is created and that it contains both the tls.crt and tls.key files from the path/to/your/keycloak/tls path.
```
$ kubectl get cm keycloak-tls -o yaml --namespace [namespace_name]
```
2. Create a file named keycloak.yaml. Enable the Keycloak service to run the Keycloak Administration Console on URL https://[Your_Cluster_IP_Address]:30104.
```
keycloak:
  enabled: true
  service:
    enabled: true
    type: NodePort
    exposePort: 30104
    ipAddress: [Your_Cluster_IP_Adrress]
    tls:
      enabled: true
      configMapName: keycloak-tls
sso:
  enabled: true
  configSet: ("SSO_CONFIG_1" "SSO_CONFIG_2" .... "SSO_CONFIG_n")
```
  Add -f keycloak.yaml to the helm_install or helm_upgrade command.
To enable Keycloak Single Sign On by using external keycloak outside of the hcl-compass helm chart:
1. Create a keycloak-json configMap for the keycloak.json file:
  1. Create a new folder named path/to/your/keycloak/json that contains the keycloak.json files
```
$ mkdir /path/to/your/keycloak/json
```
  2. Add the keycloak.json file from the path/to/your/keycloak/json folder to the configMap called keycloak-json.
```
$ kubectl create configmap keycloak-keycloak --from-file /path/to/your/keycloak/json/ --namespace [namespace_name]
```
  3. Ensure that the configMap keycloak-json is created and that it contains the keycloak.json file from the path/to/your/keycloak/json path.
```
$ kubectl get cm keycloak-json -o yaml --namespace [namespace_name]
```
2. Create a file named keycloak.yaml. Enable the Keycloak service and keycloak.jsonFile to run Keycloak outside of the hcl-compass helm chart.
```
keycloak:
  enabled: true
  urlMapping: [Keycloak_URL]
  username: [Keycloak_Admin_Usename]
  password: [Keycloak_Admin_Password]
  realmName: [Keycloak_Realm_Name]
  dashboardsClientID: [Keycloak_Dashboards_Client_ID]
  dashboardsClientSecret: [Keycloak_Dashboards_Client_Secret]  
jsonFile:
  enabled: true
  configMapName: keycloak-json
```
3. Add -f keycloak.yaml to the helm_install or helm_upgrade command.
To enable the Single Sign On (Keycloak) feature by using Keycloak running on HCL Compass Solution Console:
Adding a client to the existing SoFySolution Realm and keycloak.json are required to enable the Keycloak feature on the HCL Compass Solution Console. Refer to Keycloak Integration and follow steps 3-5 and step 7 and then download the keycloak.json file for the new client. Ensure that you add a new username sol-admin as described in step 7.
1. Install the HCL Compass Solution chart, access to the Solution Console and link to the HCL Compass home page using steps 3 and 4 in Deploying HCL Compass on Google Kubernetes Engine.
2. To access the Keycloak Administration URL to create a new client and download the keycloak.json file:
  - Within the Solution Console, click on the USER MANAGEMENT icon on the left side of the page to display the SoFySolution Realm settings page.
  - Select Client on the left side of the page and create a new client and download the keycloak.json file as described in steps 3-5 in Keycloak Integration.
  - Edit and add the following line to the keycloak.json file:
```
"disable-trust-manager": true
```
3. Setting up keycloak-json configmap for the keycloak.json file.
  1. Create a new folder named path/to/your/keycloak that contains the keycloak.json file for installing and configuring Keycloak on HCL Compass pod container.
```
$ mkdir /path/to/your/keycloak
```
  2. Add the keycloak.json file from the path/to/your/keycloak/tls folder to the configMap called keycloak-json.
```
$ kubectl create cm keycloak-json --from-file /path/to/your/keystore/keycloak.json --namespace [namespace_name]
```
  3. Ensure that the configMap keycloak-json is created and that it contains the keycloak.json file from the path/to/your/keycloak path.
```
$ kubectl get cm keycloak-json -o yaml --namespace [namespace_name]
```
4. Create a file called keycloak.yaml. Enable the Keycloak and SSO configuration for the hcl-compass pod container and the keycloak.json file.
```
hcl-compass:
  keycloak:
    enabled: true
    service:
      type: NodePort
      exposePort: [Keycloak_Port_Number]
      ipAddress: [Keycloak_IP_Adrress]
      username: [Keycloak_Admin_Usename]
      password: [Keycloak_Admin_Password]
      realmName: [Keycloak_Realm_Name]
      dashboardsClientID: [Keycloak_Dashboards_Client_ID]
      dashboardsClientSecret: [Keycloak_Dashboards_Client_Secret]
    jsonFile:
      enabled: true
      configMapName: keycloak-json

  # SSO settings in compass container
  sso:
    enabled: true
    configSet: ("SSO_CONFIG_1" "SSO_CONFIG_2" .... "SSO_CONFIG_n")
```
  - Each SSO configuration SSO_CONFIG_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:
```
configSet: ("-username admin -password "" -dbset DefectTracking  -ssousername SYSTEM_SSO1" "-username admin -password "" -dbset EssentialSAFe -ssousername SYSTEM_SSO2")
```
    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.
5. Upgrade the HCL Compass Solution Chart by adding -f keycloak.yaml to the helm upgrade command.
6. Access again the Solution Console and link to the HCL Compass home page by using step 4 in Deploying HCL Compass on Google Kubernetes Engine.
7. Log in to HCL Compass by selecting the Use SSO Identity checkbox.