Truststore

Overview

The truststore is used by IG to verify TLS certificates presented by servers that it connects to.

It is built on top of the default Java truststore, which is itself built from the /etc/ssl/certs/ca-certificates.crt that is configured in the IG Docker image.

import-pem-certs.sh script

The Docker image contains a script import-pem-certs.sh in the /home/forgerock/ directory, which can be used to add additional certificates to the truststore.

The script takes a single PEM file (containing one or more certificates) and adds them to the truststore. If an error occurs, the script exits with a non-zero error code.

You can set the following environment variables to control the behaviour of the script:

Environment Variable	Purpose	Default
IG_PEM_TRUSTSTORE	Path to a PEM file representing a truststore. The PEM file can contain one or more X.509 certificates, each of which will be added to the truststore created by this script	No default. If this variable isn't populated, the script will exit with an error code -1
TRUSTSTORE_PATH	Path where the truststore created by this script is output	/home/forgerock/igtruststore
IG_DEFAULT_TRUSTSTORE	The default truststore that you want to extend. This truststore must already exist in the image. Typically, this is the default JVM truststore	$JAVA_HOME/lib/security/cacerts
TRUSTSTORE_PASSWORD	Password for the IG_DEFAULT_TRUSTSTORE and for the new truststore that is created	changeit

IG environment variables

The following environment variables must be set to configure IG to use a specific truststore (which can be created using the import-pem-certs.sh script or a different method):

Environment Variable	Purpose
IG_TRUSTSTORE_PATH	Path to the truststore to use. If you are using the import-pem-certs.sh script, this value should match the TRUSTSTORE_PATH value in the script
IG_TRUSTSTORE_PASSWORD	The password for the truststore. If you are using the import-pem-certs.sh script, this value should match the TRUSTSTORE_PASSWORD value in the script

Configuring the IG Truststore

The following process demonstrates adding additional certificates to the truststore and configuring IG to use that truststore:

1. Create a PEM file containing all the additional certificates that you want to trust.
2. Mount the PEM file into the Docker image.
3. Set the required environment variables in the import-pem-certs.sh script.
4. Run the import-pem-certs.sh script.
5. Confirm the script ran successfully by checking the exit code and any error messages in the output.
6. Configure the IG environment variables to use this truststore.
7. Start IG.