Importing untrusted TLS certificates to Che

External communications between Che components are, by default, encrypted with TLS. Communications of Che components with external services such as proxies, source code repositories, and Identity Provider (Keycloak or RH-SSO) may require using TLS. Those communications require the use of TLS certificates signed by trusted Certificate Authorities.

When the certificates used by Che components or by an external service are signed by an untrusted CA, it can be necessary to import the CA certificate in the Che installation so that every Che component will consider them as signed by a trusted CA.

Typical cases that may require this addition are:

  • When the underlying Kubernetes cluster that uses TLS certificates signed by a CA that is not trusted.

  • When Che server or workspace components connect to external services such as Keycloak or a Git server that use TLS certificates signed by an untrusted CA.

Che uses labeled ConfigMaps in namespace as sources for TLS certificates. The ConfigMaps can have an arbitrary number of keys with a random number of certificates each.

On OpenShift, when the cluster contains cluster-wide trusted CA certificates added through the cluster-wide-proxy configuration, Che Operator detects them and automatically injects them into this ConfigMap:

  • Che automatically labels the ConfigMap with the"true" label.

  • Based on this annotation, OpenShift automatically injects the cluster-wide trusted CA certificates inside the ca-bundle.crt key of ConfigMap

Some Che components require to have a full certificate chain to trust the endpoint. If the cluster is configured with an intermediate certificate, then the whole chain (including self-signed root) should be added to Che.

Adding new CA certificates into Che

The following procedure is applicable for already installed and running instances and for instances that are to be installed.

If you are using Che version lower than v7.23.0 see this guide on how to apply additional TLS certificates.
  • The kubectl tool is available.

  • Namespace for Che exists.

  1. Save the certificates you need to import, to a local file system.

    • Certificate files are typically stored as Base64 ASCII files, such as .pem, .crt, .ca-bundle. But, they can also be binary-encoded, for example, as .cer files. All Secrets that hold certificate files should use the Base64 ASCII certificate rather than the binary-encoded certificate.

    • Che already uses some reserved file names to automatically inject certificates into the ConfigMap, so you should avoid using the following reserved file names to save your certificates:

      • ca-bundle.crt

      • ca.crt

  2. Create a new ConfigMap with the required TLS certificates:

    $ kubectl create configmap custom-certs --from-file=<bundle-file-path> -n=eclipse-che

    Add another -from-file=<bundle-file-path> flag to apply more than one bundle. Otherwise, create another ConfigMap.

  3. Label created ConfigMaps with both and labels:

    $ kubectl label configmap custom-certs -n <che-namespace-name>
  4. Deploy Che if it has not been deployed before. Otherwise wait until the rollout of Che components finishes. If there are running workspaces, they should be restarted for the changes to take effect.

Verification at the Che installation level

When something does not work as expected after adding the certificates, here is a list of things to verify:

  • In case of a Che Operator deployment, the namespace where the CheCluster is located contains labeled ConfigMaps with the right content:

    $ kubectl get cm, -n eclipse-che

    Check the content of ConfigMap by running:

$ {orch-cli} get cm __<name>__ -n {prod-namespace} -o yaml
  • Che Pod Volumes list contains a volume that uses ca-certs-merged ConfigMap as data-source. To get the list of Volumes of the Che Pod:

    $ kubectl get pod -o json <che-pod-name> -n eclipse-che | jq .spec.volumes
  • Che mounts certificates in folder /public-certs/ of the Che server container. This command returns the list of files in that folder:

    $ kubectl exec -t <che-pod-name> -n eclipse-che -- ls /public-certs/
  • In the Che server logs, there is a line for every certificate added to the Java truststore, including configured Che certificates.

    $ kubectl logs <che-pod-name> -n eclipse-che
  • Che server Java truststore contains the certificates. The certificates SHA1 fingerprints are among the list of the SHA1 of the certificates included in the truststore returned by the following command:

    $ kubectl exec -t <che-pod-name> -n eclipse-che -- keytool -list -keystore /home/user/cacerts
    Your keystore contains 141 entries:

    To get the SHA1 hash of a certificate on the local filesystem:

    $ openssl x509 -in <certificate-file-path> -fingerprint -noout
    SHA1 Fingerprint=3F:DA:BF:E7:A7:A7:90:62:CA:CF:C7:55:0E:1D:7D:05:16:7D:45:60

Verification at the workspace level

  • Start a workspace, obtain the namespace name in which it has been created, and wait for the workspace to be started.

  • Get the name of the workspace Pod with the following command:

    $ kubectl get pods -o=jsonpath='{.items[0]}' -n <workspace namespace> | grep '^workspace.*'
  • Get the name of the Che-Theia IDE container in the workspace Pod with the following command:

    $ kubectl get -o json pod <workspace pod name>  -n <workspace namespace> | \
        jq -r '.spec.containers[] | select(.name | startswith("theia-ide")).name'
  • Look for a ca-certs ConfigMap that should have been created inside the workspace namespace:

    $ kubectl get cm ca-certs <workspace namespace>
  • Check that the entries in the ca-certs ConfigMap contain all the additional entries you added before. In addition, it can contain ca-bundle.crt entry which is a reserved one:

    $ kubectl get cm ca-certs -n <workspace namespace> -o json | jq -r '.data | keys[]'
  • Confirm that the ca-certs ConfigMap has been added as a volume in the workspace Pod:

    $ kubectl get -o json pod <workspace pod name> -n <workspace namespace> | \
        jq '.spec.volumes[] | select( == "ca-certs")'
      "configMap": {
        "defaultMode": 420,
        "name": "ca-certs"
      "name": "che-self-signed-certs"
  • Confirm that the volume is mounted into containers, especially in the Che-Theia IDE container:

    $ kubectl get -o json pod <workspace pod name> -n <workspace namespace> | \
       jq '.spec.containers[] | select(.name == "<theia ide container name>").volumeMounts[] | select(.name == "che-self-signed-certs")'
      "mountPath": "/public-certs",
      "name": "che-self-signed-certs",
      "readOnly": true
  • Inspect the /public-certs folder in the Che-Theia IDE container and check that its contents match the list of entries in the ca-certs ConfigMap:

    $ kubectl exec <workspace pod name> -c <theia ide container name> -n <workspace namespace> -- ls /public-certs