Knowledge Discovery 25.1
Getting Started Guide

# Set Up SSL/TLS Certificates and Trust Stores

When you want to run the Knowledge Discovery 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 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 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.

Copyright 2024 Open Text
Version 25.1 | Last updated January 2025

Send documentation feedback

Close

Send documentation feedback

To send feedback using your default email client, open an email window.

Otherwise, send your feedback and the information below to MFI-swpdl.idoldocsfeedback@opentext.com.

We appreciate your feedback!

Product: Knowledge Discovery 25.1

Topic Title: Set Up SSL/TLS Certificates and Trust Stores