Set Up SSL/TLS Certificates and Trust Stores

When you want to run the IDOL Docker Compose packages with SSL, you must either provide the SSL certificates (recommended), or provide an OpenSSL-based Certificate Authority to generate the certificates when you run the containers.

NOTE: If you configure the containers to generate the certificates, you must provide a certificate for your certificate authority that is able to sign Certificate Signing Requests.

You use the idol-ssl.env environment variables file to provide information about your certificates. The docker-compose.ssl.yml defines an ssl-volume bind mount, which provides the certificates from the host machine to the containers.

Between idol-ssl.env and the ssl-volume, the containers must be able to either find a certificate provided for the component, or use the Certificate Authority certificate and configuration to generate one. If the containers cannot obtain an appropriate certificate by either method, the docker-compose up command exits with an error.

When you use a custom Certificate Authority to generate your certificates, you must also set up a trust store for your user interfaces, to allow them to securely communicate with the SSL-activated IDOL components. See User Interface Trust Stores.

The following sections describe how to provide or generate the certificates, and trust stores.

Provide Certificates

OpenText recommends that you provide certificates for the container.

When you start a container with SSL activated, the container looks for a certificate at a configurable path for the component. You configure this path by using the environment variables.

The expected location is:

${IDOL_SSL_CA_MOUNTDIR}/${USER_SSL_CERTS_DIR}/${IDOL_SSL_COMMON_NAME}.cert.pem

where:

  • ${IDOL_SSL_COMMON_NAME} is the common name for the service.
  • ${IDOL_SSL_CA_MOUNTDIR} and ${USER_SSL_CERTS_DIR} are environment variable you can use to specify the location of the certificates.

For more information about these environment variables, see SSL Environment Variable Reference.

Generate Certificates

When you do not provide a certificate, Docker generates them for the component when you start up the container for the first time. In this case, you must have a Certificate Authority that is able to sign Certificate Signing Requests.

You control the location of the Certificate Authority certificate, and the password for it, by using environment variables.

  • The certificate is expected to be in the directory ${IDOL_SSL_SSL_CA_MOUNTDIR}/${IDOL_SSL_CACERT}.

  • The private key file is expected to be in the directory ${IDOL_SSL_SSL_CA_MOUNTDIR}/${IDOL_SSL_CAKEY}.

  • The password for the private key is expected to be set in the environment variable ${IDOL_SSL_CAPASS}.

User Interface Trust Stores

When you use a custom Certificate Authority to generate certificates, you must set up trust stores for your user interfaces (Find, MMAP, and Data Admin), to allow them to securely communicate with the SSL-activated IDOL components.

You construct the trust store from a PKCS 12 file of the issuing certificate and its private key, along with the root certificate.

To construct the trust store

  1. Create a cfg directory in the ${IDOL_SSL_CA_MOUNTDIR} directory. The SSL generation scripts require this directory to store the certificate generation configuration.

  2. Generate an intermediate PKCS 12 file. The following example command creates a file, intermediate.pkcs12 :

    openssl pkcs12 -export -in certs/intermediate.cert.pem -inkey private/intermediate.key.pem -passin pass:PRIVATE_KEY_PASSWORD -out certs/intermediate.pkcs12 -passout pass:PASSWORD_FOR_PKCS12_FILE

    where PRIVATE_KEY_PASSWORD is the password for your private key, and PASSWORD_FOR_PKCS12_FILE is your password for the PKCS12 file.

  3. Copy your root certificate (for example ca.cert.pem) to the intermediate certs directory to make it available to the trust store.

  4. Generate the chain file by concatenating the root certificate PEM and the issuing intermediate certificate PEM. For example:

    cat certs/ca.cert.pem certs/intermediate.cert.pem > ca-chain.cert.pem
  5. Choose the value of the IDOL_SSL_SUBJ_ALT_NAME environment variable.

    For a user interface (that is, something that you expect to access from a Web browser), use a wildcard value to generate a wildcard certificate. For example, if the computer hosting the certificate is accessible on the exampl.com domain, use *example.com. This option prevents warnings from your browser because of a difference between the domains that the certificate is valid for, compared with the domains that it is accessible on.

    For a back end component, the value that you choose is less important, because for this demo system the communications between the back end components and the user interfaces are not verified against the server they run on.

  6. Import your chain certificate into your browser. This step prevents warnings about the issued certificates being untrusted.