Installing Che in TLS mode with self-signed certificates

This guide is for development only. Do not use self-signed certificates in production.

The following section describes the deployment and configuration of Eclipse Che for use in TLS mode with self-signed certificates. It consists of following steps:

Generate needed keys and certificates if needed
Prepare target deployment environment (one of the following):
- Minikube (Kubernetes)
- Minishift (OpenShift 3)
- CodeReady Containers (OpenShift 4)
Configure the browser

Deploying Che with self-signed TLS certificates on OpenShift 4 using Operator

This section describes how to deploy Che with self-signed TLS certificates on OpenShift Container Platform 4. To do that:

Generate an OpenShift certificate.
Use it when deploying Che.
Import it into a browser.

Prerequisites

A running OpenShift instance, version 4 or higher
Have all required keys and certificates generated

Procedure

Get the OpenShift 4 self-signed certificate:

$ oc get secret router-ca -n openshift-ingress-operator -o jsonpath="{.data.tls\.crt}" | \
  base64 -d > ca.crt

Pre-create a namespace for Che:
```
$ oc create namespace che
```

Create a secret from the CA certificate:

$ oc create secret generic self-signed-certificate --from-file=ca.crt -n=che

Deploy Che using chectl:

$ chectl server:start --platform=crc --installer=operator --self-signed-cert

Deploying Che with self signed TLS certificates on Kubernetes

This section describes how to deploy Che with self-signed TLS certificates on the Kubernetes platform.

Prerequisites

A running Kubernetes instance, version 1.9 or higher
Have all required keys and certificates generated

Procedure

Pre-create a namespace for Che:
```
$ kubectl create namespace che
```

Create a secret with the domain key and the certificate:

$ kubectl create secret tls che-tls --key=domain.key --cert=domain.crt -n che

Create a secret from the CA certificate:

$ kubectl create secret generic self-signed-certificate --from-file=ca.crt -n che

Deploy Che using chectl:

$ chectl server:start --platform=minikube --installer=operator --self-signed-cert

Deploying Che with self-signed TLS certificates on OpenShift 3 using Operator

This section describes how to deploy Che with self-signed TLS certificates on the OpenShift 3 platform.

Prerequisites

A running OpenShift instance, version 3.11 or higher
Have all required keys and certificates generated

Procedure

$ oc login -u system:admin --insecure-skip-tls-verify=true
$ oc project default

Re-configure the router with the generated certificate:

$ oc delete secret router-certs
$ cat domain.crt domain.key > minishift.crt
$ oc create secret tls router-certs --key=domain.key --cert=minishift.crt
$ oc rollout latest router

Pre-create a namespace for Che:
```
$ oc create namespace che
```

Create a secret from the CA certificate:

$ oc create secret generic self-signed-certificate --from-file=ca.crt -n=che

Deploy Che using chectl. Eclipse Che is installed with TLS mode by default:

$ chectl server:start --platform=minishift --installer=operator --self-signed-cert

Generating self-signed TLS certificates

This section describes how to prepare self-signed TLS certificates to use with Che on different platforms.

Prerequisites

The expected domain name where Che deployment is planned:

Table 1. Expected (default) domain names

Platform Default domain

Minishift

$( minishift ip ).nip.io

Minikube

$( minikube ip ).nip.io

CodeReady Containers

apps-crc.testing

Table 1. Expected (default) domain names
Platform	Default domain
Minishift	`$( minishift ip ).nip.io`
Minikube	`$( minikube ip ).nip.io`
CodeReady Containers	`apps-crc.testing`

The location of the openssl.cnf file on the target machine:

Table 2. Usual OpenSSL configuration file locations
Linux distribution	File location
Fedora, Red Hat Enterprise Linux, CentOS	`/etc/pki/tls/openssl.cnf`
Debian, Ubuntu, Mint, Arch Linux	`/etc/ssl/openssl.cnf`

Procedure

Set the necessary environment variables:

$ CA_CN="Local Eclipse Che Signer"
$ DOMAIN=*.<expected.domain.com>
$ OPENSSL_CNF=<path_to_openssl.cnf>

Example with Minikube on Fedora 31

$ CA_CN="Local Eclipse Che Signer"
$ DOMAIN=\*.$( minikube ip ).nip.io
$ OPENSSL_CNF=/etc/pki/tls/openssl.cnf

Example with crc on OSX

$ export CA_CN="Local Eclipse Che Signer"
$ export DOMAIN=*.apps-crc.testing
$ export OPENSSL_CNF=/System/Library/OpenSSL/openssl.cnf

Generate the root CA key. Add the -des3 parameter to use a passphrase:
```
$ openssl genrsa -out ca.key 4096
```

Generate the root CA certificate:

$ openssl req -x509 \
  -new -nodes \
  -key ca.key \
  -sha256 \
  -days 1024 \
  -out ca.crt \
  -subj /CN="${CA_CN}" \
  -reqexts SAN \
  -extensions SAN \
  -config <(cat ${OPENSSL_CNF} \
      <(printf '[SAN]\nbasicConstraints=critical, CA:TRUE\nkeyUsage=keyCertSign, cRLSign, digitalSignature'))

Generate the domain key:
```
$ openssl genrsa -out domain.key 2048
```

Generate the certificate signing request for the domain:

$ openssl req -new -sha256 \
    -key domain.key \
    -subj "/O=Local {prod}/CN=${DOMAIN}" \
    -reqexts SAN \
    -config <(cat ${OPENSSL_CNF} \
        <(printf "\n[SAN]\nsubjectAltName=DNS:${DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth")) \
    -out domain.csr

Generate the domain certificate:

$ openssl x509 \
    -req \
    -sha256 \
    -extfile <(printf "subjectAltName=DNS:${DOMAIN}\nbasicConstraints=critical, CA:FALSE\nkeyUsage=digitalSignature, keyEncipherment, keyAgreement, dataEncipherment\nextendedKeyUsage=serverAuth") \
    -days 365 \
    -in domain.csr \
    -CA ca.crt \
    -CAkey ca.key \
    -CAcreateserial -out domain.crt

This procedure allows to use domain.crt and domain.key for TLS Route and Ingress, and ca.crt for importing into browsers.

Using Che with TLS

This section describes how to import a root certificate authority into the browser to use Che with self-signed TLS certificates.

Google Chrome

Go to chrome://settings/certificates, the Authorities tab, click Import, and find the generated rootCA.crt (or ca.crt for OpenShift 4) file.
Select Trust this certificate for identifying websites and click OK.
Browser is satisfied with Che certificate and is reporting a secure connection.

Firefox

Go to about:preferences, search for certificates, and click View Certificates.
Go to the Authorities tab, click Import, and find the generated rootCA.crt (or ca.crt for OpenShift 4) file.
Select Trust this CA to identify websites and click OK.
Browser is satisfied with Che certificate and is reporting a secure connection.

macOS

Open Keychain Access.
Select the System keychain and drag & drop the rootCA.crt (or ca.crt for OpenShift 4) file there.
Double-click the imported CA, go to Trust, and select When using this certificate: Always Trust.
If the browser still reports an invalid certificate, restart the browser.

Tags: