Skip to main content

Configuring HTTPS

GGCE API and Web application traffic need to be secured with SSL certificates and endpoints only accessible through https. The following steps are involved in enabling https:

  1. Register GGCE domain names in the DNS
  2. Generate a new SSL private key and a Certificate Signing Request (CSR)
    • On Windows you can use IIS to generate and sign certificates and skip the remaining steps!
  3. Submit the CSR to a Certificate Authority for signature
  4. Apply signed certificate and private key to GGCE

DNS names​

GGCE requires one hostname to be registered in your organization's DNS.

First, pick a name where users will access GGCE. Here are some suggestions, assuming that the internal network domain is internal.lan:

  • ggce.internal.lan
  • ggce.genebank.internal.lan
  • pick-your-own.internal.lan

Ask your network administrator to add the DNS entry to the DHCP/DNS as CNAME records pointing to your Docker host.

Generate a Certificate Signing Request​

Use the configuration template ggce-ssl.conf shown below to specify the advanced configuration of the GGCE certificate. Update the configuration according to your needs.

ggce-ssl.conf
[req]
default_bits = 2048
distinguished_name = req_distinguished_name
req_extensions = req_ext
prompt = no

[req_distinguished_name]
C = DE
O = Crop Trust
OU = Genebank
CN = GGCE
DC = lan
0.DC = internal

[req_ext]
keyUsage = digitalSignature
extendedKeyUsage = serverAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = ggce.internal.lan
# IP.1 = <IP of DOCKER HOST>

Create a new private key in ggce.key and a CSR ggce.csr to be submitted to the Certificate Authority for signature:

openssl req -out ggce.csr -keyout ggce.key -newkey rsa:2048 -nodes -sha256 -config ggce-ssl.conf
tip

OpenSSL is installed on Linux and Mac systems and is available for Windows. It provides the openssl command.

Request the certificate​

Send or upload the CSR to your certificate provider and wait for them to send you the signed certificate.

Once received (let's assume the file is called ggce.crt) you can check that the certificate corresponds to your private key ggce.key with:

openssl pkey -in ggce.key -pubout -outform pem | sha256sum
openssl x509 -in ggce.crt -pubkey -noout -outform pem | sha256sum

The outputs of the two commands must match!

If you also received the CA certificate chain (or CA bundle), you should merge the certificate and the chain into a single file ggce-chain.crt: first the text contents of your certificate, followed by the contents of the CA bundle.

Update traefik/dynamic.yml with your new certificate that corresponds to the key from which it was generated:

tls:
  # ... other lines
  certificates:
    # This is a our new certificate/key pair
    - certFile: /opt/traefik/ggce-chain.crt # Not after: 31 February 2021
      keyFile: /opt/traefik/ggce.key

It's good practice to add a comment with the expiration date of the certificate to that line. You can obtain certificate details by running:

openssl x509 -in ggce.crt -noout -text

... and look for the Not After : line.

Renewing certificates​

Certificates expire. It's best to add a reminder to your Calendar so you can start the renewal process before they expire.

Check the configuration in traefik/dynamic.yml for the currently active certFile/keyFile pair.

Generate a new CSR for your existing private key ggce.key and certificate ggce.crt:

openssl x509 -x509toreq -in ggce.crt -out new-ggce.csr -signkey ggce.key

Once you receive the signed certificate, copy it to traefik/ folder and update in traefik/dynamic.yml only the certFile line that corresponds to this key.

Sign the CSR with DC​

In case your Domain Controller DC provides Certificate Services and a CA certificate that is trusted by all computers in the domain, you can use the DC to sign the certificate request.

Domain Administrator privileges required

Certificate not issued (Denied) Denied by Policy Module The permissions on the certificate template do not allow the current user to enroll for this type of certificate.

cmd.exe needs to be "Run as..." a user with Domain Administrator privileges.

Send the ggce.csr file to your Domain Administrator. They will sign the CSR by running the following command in cmd.exe:

certreq -submit -attrib "CertificateTemplate:WebServer" ggce.csr ggce.crt

This command will prompt the Domain Administrator to select the signing CA and will save the signed certificate as ggce.crt. The Administrator should send this file back and it needs to be added to the traefik/ subfolder.

Self-signed certificate​

Use properly signed certificates

We strongly advise against using self-signed certificates! Use this option only for testing on your local machine or as a last resort.

You can use Traefik's self-signed certificate by updating traefik/dynamic.yml to:

tls:
  stores:
    default: {}

# All other lines commented out or removed.

You need to update your compose file to instruct GGCE UI to ignore TLS errors by setting NODE_TLS_REJECT_UNAUTHORIZED environment variable to 0:

  ggce-ui:
    image: dockerhub.croptrust.org/grin-global/grin-global-ui/gg-ce-web:...
    environment:
      NODE_TLS_REJECT_UNAUTHORIZED: 0