Custom truststore¶

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.

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/jssecacerts or <java-home>/lib/security/cacerts. The default password is changeit.

Generate a truststore by importing the certificate(s) you want to trust. In this example, the certificates are inside a file called clientCert.pem.

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

Grant access¶

Before we can use the truststore in the Onegini Token Server container we need to give the user 1000 access 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 /opt/data/truststore.

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:

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.

Common errors¶

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