SSL Configuration

Enabling SSL is recommended for all ODAS clusters.

Configuration Settings

The following configuration settings are used to configure SSL:

  • SSL_CERTIFICATE_FILE
  • SSL_KEY_FILE
  • ENABLE_SSL

Defaults with okctl

If the ENABLE_SSL value is set to true in the configuration file and no other SSL configuration value is used, okctl will generate a CA certificate and a certificate/key (with the IP of the local machine as the common name for the cert) in the current directory:

  • .auth/ca.pem - the CA certificate
  • .auth/cert.pem - the certificate (including it's full chain)
  • .auth/cert.key - the certificate private key

It will then set the following values automatically when updating the cluster configuration:

SSL_CERTIFICATE_FILE: file:///path/to/current/dir/.auth/cert.pem
SSL_KEY_FILE: file:///path/to/current/dir/.auth/cert.key

You can disable this behavior by removing the ENABLE_SSL setting or specifying your own values for these settings.

Certificate Requirements

ODAS has two requirements for the certificate file:

  1. It must be in PEM format
  2. It must contain the full certificate chain. Not including the full chain will cause some clients to reject this certificate.

Note

For Let's Encrypt certificates, the full chain of certificates is in the fullchain.pem file.

Configuring SSL

If you have a particular certificate and key file you would like to configure, put the following values in your configuration:

SSL_CERTIFICATE_FILE: file:///path/to/cert.pem
SSL_KEY_FILE: file:///path/to/cert.key

Validating the SSL Configuration

Once your cluster is updated with the certificate configuration, you can use the openssl CLI to verify it can be fully validated.

For example, if your Web UI is at https://okera.company.com:8083, you can run:

$ openssl s_client -connect okera.company.com:8083
CONNECTED(00000005)
depth=2 O = Digital Signature Trust Co., CN = DST Root CA X3
verify return:1
depth=1 C = US, O = Let's Encrypt, CN = Let's Encrypt Authority X3
verify return:1
depth=0 CN = *.company.com
verify return:1
---
Certificate chain
0 s:/CN=*.okerademo.com
i:/C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3
1 s:/C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3
i:/O=Digital Signature Trust Co./CN=DST Root CA X3
...

If you see an error such as "unable to verify the first certificate", it may mean you do not have the full chain or the hostname/IP on which you are accessing the cluster do not match the Common Name in the certificate.