Chapter 3. Installing CodeReady Workspaces in TLS mode with self-signed certificates

The following section describes the deployment and configuration of CodeReady Workspaces with self-signed certificates. Self-signed certificates are certificates that are not signed by a commonly trusted certificate authority (CA), but instead signed by a locally created CA. Self-signed certificates are not trusted by default. For example, when a website owner uses a self-signed certificate to provide HTTPS services, users who visit that website see a warning in their browser.

Warning

Self-signed certificates are usually used in development and evaluation environments. Use in production environments is not recommended.

3.1. Generating self-signed TLS certificates

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

Prerequisites

  • The expected domain name where the CodeReady Workspaces deployment is planned.
  • The location of the openssl.cnf file on the target machine.

    Table 3.1. Usual OpenSSL configuration file locations

    Linux distributionFile location

    Fedora, Red Hat Enterprise Linux, CentOS

    /etc/pki/tls/openssl.cnf

    Debian, Ubuntu, Mint, Arch Linux

    /etc/ssl/openssl.cnf

Procedure

  1. Set the necessary environment variables:

    $ CA_CN="Local Red Hat CodeReady Workspaces Signer"
    $ DOMAIN=*.<expected.domain.com>
    $ OPENSSL_CNF=<path_to_openssl.cnf>
  2. Generate the root Certificate Authority (CA) key. Add the -des3 parameter to use a passphrase:

    $ openssl genrsa -out ca.key 4096
  3. 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'))
  4. Generate the domain key:

    $ openssl genrsa -out domain.key 2048
  5. Generate the certificate signing request for the domain:

    $ openssl req -new -sha256 \
        -key domain.key \
        -subj "/O=Local Red Hat CodeReady Workspaces/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
  6. 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.

3.2. Deploying CodeReady Workspaces with self-signed TLS certificates on OpenShift 4

This section describes how to deploy CodeReady Workspaces with self-signed TLS certificates on a local OpenShift 4 cluster.

CodeReady Workspaces uses a default router certificate to secure its endpoints. Therefore, it depends on the OpenShift cluster configuration whether a self-signed certificate is used or not. CodeReady Workspaces automatically detects if the OpenShift default router uses a self-signed certificate by analyzing its certificate chain.

Prerequisites

Procedure

  1. Log in to the default OpenShift project:

    $ oc login -u <username> -p _<password>
  2. 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
  3. Pre-create a namespace for CodeReady Workspaces:

    $ oc create namespace {prod-namespace}
  4. Create a secret from the CA certificate:

    $ oc create secret generic self-signed-certificate --from-file=ca.crt -n={prod-namespace}
  5. Deploy CodeReady Workspaces using crwctl:

    $ crwctl server:start --platform=openshift --installer=operator

    When using CodeReady Containers, substitute openshift in the above command with crc.

3.3. Deploying CodeReady Workspaces with self-signed TLS certificates on OpenShift 3

This section describes how to deploy CodeReady Workspaces with self-signed TLS certificates generated by the user on the OpenShift 3 platform.

Note

This method involves reconfiguration of OpenShift router to use user-provided TLS certificates.

Prerequisites

Procedure

  1. Log in to the default OpenShift project:

    $ oc login -u system:admin --insecure-skip-tls-verify=true
    $ oc project default
  2. Reconfigure the router with the generated certificate:

    $ oc delete secret router-certs
    $ cat domain.crt domain.key > openshift.crt
    $ oc create secret tls router-certs --key=domain.key --cert=openshift.crt
    $ oc rollout latest router
  3. Create a namespace for CodeReady Workspaces:

    $ oc create namespace workspaces
  4. Create a secret from the CA certificate:

    $ oc create secret generic self-signed-certificate --from-file=ca.crt -n=workspaces
  5. Deploy CodeReady Workspaces using crwctl. Red Hat CodeReady Workspaces is installed with TLS mode by default:

    $ crwctl server:start --platform=openshift --installer=operator

3.4. Importing self-signed TLS certificates to browsers

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

When a TLS certificate is not trusted, the error message Authorization token is missing. Click here to reload page blocks the login process. To prevent this, add the public part of the self-signed CA certificate into the browser after installing CodeReady Workspaces.

3.4.1. Getting the self-signed CA certificate from CodeReady Workspaces deployment

When crwctl is used to deploy CodeReady Workspaces, it exports a self-signed CA certificate into a cheCA.crt file to the current user home directory. To get the certificate, use one of the following two methods:

  • Exporty the certificate using the crwctl command:

    $ crwctl cacert:export
  • Read the self-signed-certificate secret from the CodeReady Workspaces namespace:

    $ oc get secret self-signed-certificate -n workspaces

3.4.2. Adding certificates to Google Chrome on Linux or Windows

Procedure

  1. Navigate to URL where CodeReady Workspaces is deployed.
  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.
    2. Click Certificates and navigate to the Details tab.
    3. Select the certificate to use and export it:

      • On Linux, click the Export button.
      • On Windows, click the Save to file button.
  3. Go to Google Chrome Settings, then to the Authorities tab
  4. In the left panel, select Advanced and continue to Privacy and security.
  5. At the center of the screen, click Manage certificates and navigate to Authorities tab.
  6. Click the Import button and open the saved certificate file.
  7. Select Trust this certificate for identifying websites and click the OK button.
  8. After adding the CodeReady Workspaces certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.

3.4.3. Adding certificates to Google Chrome on macOS

Procedure

  1. Navigate to URL where CodeReady Workspaces is deployed.
  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.
    2. Click Certificates.
    3. Select the certificate to use and drag and drop its displayed large icon to the desktop.
  3. Double-click the exported certificate to import it into Google Chrome.

3.4.4. Adding certificates to Keychain Access for use with Safari on macOS

Procedure

  1. Navigate to URL where CodeReady Workspaces is deployed.
  2. Save the certificate:

    1. Click the lock icon on the right of the window title bar.
    2. Select the certificate to use and drag and drop its displayed large icon to the desktop.
  3. Open the Keychain Access application.
  4. Select the System keychain and drag and drop the saved certificate file to it.
  5. Double-click the imported CA, then go to Trust and select When using this certificate: Always Trust.
  6. Restart Safari for the added certificated to take effect.

3.4.5. Adding certificates to Firefox

Procedure

  1. Navigate to URL where CodeReady Workspaces is deployed.
  2. Save the certificate:

    1. Click the lock icon on the left of the address bar.
    2. Click the > button next to the Connection not secure warning.
    3. Click the More information button.
    4. Click the View Certificate button on the Security tab.
    5. Click the PEM (cert) link and save the certificate.
  3. Navigate to about:preferences, search for certificates, and click View Certificates.
  4. Go to the Authorities tab, click the Import button, and open the saved certificate file.
  5. Check Trust this CA to identify websites and click OK.
  6. Restart Firefox for the added certificated to take effect.
  7. After adding the CodeReady Workspaces certificate to the browser, the address bar displays the closed lock icon next to the URL, indicating a secure connection.