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
Micro Focus 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
-
Create a
cfg
directory in the${IDOL_SSL_CA_MOUNTDIR}
directory. The SSL generation scripts require this directory to store the certificate generation configuration. -
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, andPASSWORD_FOR_PKCS12_FILE
is your password for the PKCS12 file. -
Copy your root certificate (for example
ca.cert.pem
) to the intermediatecerts
directory to make it available to the trust store. -
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
-
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.
-
Import your chain certificate into your browser. This step prevents warnings about the issued certificates being untrusted.