A truststore contains certificates that are needed to set up a secure connection to other services. The most common Certificate Authorities (CA) that issue certificates are in the default truststore of the Java Virtual Machine (JVM). In case the Onegini Token Server needs to establish a secure connection to a service with a certificate that is either self-signed or issued by a CA that is not trusted by default, you need to configure a custom truststore.
When the Onegini Token Server uses a self-signed certificate for its own domain, you also need to configure a custom keystore. A custom keystore is not needed when the Onegini Token Server only needs to set up a secure connection to other systems with a certificate that cannot be resolved with the default truststore.
This page describes how to configure a custom truststore. It is divided into the following sections:
- Generate the truststore
- Location of the truststore
- Configure the container
- Restart the docker container
- Common errors
Generate the truststore
If you would like to trust imported certificates in addition to generally trusted root Certificate Authorities, you have to use (a copy of) default truststore as a base.
Typically, the default truststore is located under
<java-home>/lib/security/cacerts. The default password is
Generate a truststore by importing the certificate(s) you want to trust. In this example, the certificates are inside a file called
keytool -importcert -file clientCert.pem -alias token-server -keystore truststore.jks
Once prompted, enter the password for the truststore. Save this password in a secure location because you will need it later.
Location of the truststore
Create a folder for the truststore
Before we can use the truststore, we need to create a folder to store the truststore file. This folder will be mounted to the Onegini Token Server container later on.
mkdir -p /opt/onegini/data/truststore
If you are using SELinux, you need to give Docker access to this folder. To do this you can use the following command:
chcon -Rt svirt_sandbox_file_t /opt/onegini/data/truststore
Copy the truststore
Copy the truststore to the folder we have created for it. When a custom truststore is needed, the Onegini Token Server will resolve it from this location.
cp truststore.jks /opt/onegini/data/truststore/truststore.jks
Before we can use the truststore in the Onegini Token Server container we need to give the user
to the truststore.
chown -R 1000 /opt/onegini/data/truststore
Configure the container
The configuration example is for the engine of the Onegini Token Server. You can use the same mechanism to configure the custom truststore for the admin.
Mount your local directory
/opt/onegini/data/truststore as volume
This is how you configure the mapping in docker-compose for the engine:
engine: volumes: - "/opt/onegini/data/truststore:/opt/data/truststore" ports:
Custom truststore only
When your environment only has a custom truststore, but no custom keystore, add the following to the
JAVA_OPTS=-Djavax.net.ssl.trustStore="/opt/data/truststore/truststore.jks" -Djavax.net.ssl.trustStorePassword=<YOUR TRUSTSTORE PASSWORD>
Custom keystore and custom truststore
When your environment has both a custom keystore and a custom truststore, add the following environment variables:
TOKEN_SERVER_TRUSTSTORE_ENABLED=true TOKEN_SERVER_TRUSTSTORE_PASSWORD=<YOUR TRUSTSTORE PASSWORD>
Restart the docker container
Restart the docker container to use the custom truststore.
You can find errors like these in the logs when the Onegini Token Server tries to set up a secure connection but cannot resolve the certificate chain from the truststore:
javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target