PingAM 8.0.0

Prepare the truststore

PingDS requires secure connections using LDAPS. To connect to a DS server securely, AM needs access to DS’s CA certificate. AM also needs access to CA certificates for making secure connections to other sites; for example, connections to social providers using HTTPS.

To give AM access to these certificates, you create a truststore that contains the certificates, and configure AM’s web application container to use that truststore when starting up.

AM uses a single truststore for LDAPS and outbound HTTPS connections. This truststore must contain the CA certificates of the sites with which AM communicates securely.

By default, Apache Tomcat loads the truststore configured for its JVM (for example, $JAVA_HOME/JRE/lib/security/cacerts). The default JVM truststore contains multiple CA certificates. Its password, by default, is changeit.

As a best practice, create a new truststore with the certificates required for your AM deployment, then configure your container to use it. Don’t add the DS CA certificate to the JVM’s truststore because JVM updates are likely to overwrite the cacerts file.

To keep all existing CA certificates, you can copy the cacerts keystore file, change its password to a secure one, and import the DS CA certificate into it. Then, configure your web application container, for example, Apache Tomcat, to load that file as its truststore.

Using a separate truststore for AM means updates to the JVM truststore in patch releases aren’t taken into account. This can cause operational issues, for example, when distrusted root CA certificates are removed, or when new root CA certificates are added.

To mitigate this risk, update the AM truststore periodically to reflect the latest JVM truststore settings.

Create a truststore for AM

These steps create a copy of the default JVM truststore, and configure the AM web application container to use the new truststore:

  1. Copy the default truststore. For example, $JAVA_HOME/lib/security/cacerts, name it truststore, and place it in a directory of your choice:

    $ cp $JAVA_HOME/lib/security/cacerts /path/to/truststore

    If you place the truststore in the /path/to/am directory before you install AM, the installation process detects the directory isn’t empty and the installation fails.

    After AM is installed, you can move the truststore to a different directory. For example, the /path/to/am/security/keystores directory.

  2. For improved security, change the default password for the truststore.

    The default password of the $JAVA_HOME/lib/security/cacerts truststore is changeit.

    Use the keytool -storepasswd option to change the default password:

    $ keytool -storepasswd -keystore /path/to/truststore
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password

  3. Export the DS certificate.

    • On the DS host, export the DS CA certificate.

      DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.

      Use the dskeymgr command to export the CA certificate:

      $ /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--outputFile /path/to/ca-cert.pem

    • Copy the ca-cert.pem file to an accessible location on the AM host.

  4. Import the DS CA certificate into the new truststore:

    $ keytool \
-importcert \
-file /path/to/ca-cert.pem \
-keystore /path/to/truststore

    Enter the keystore password when prompted and confirm you trust this certificate.

  5. To configure the truststore in Apache Tomcat so that AM can access it, append the truststore settings to the CATALINA_OPTS variable in the setenv file.

    For example:

    • Linux

    • Windows

    In $CATALINA_BASE/bin/setenv.sh:

    export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \
-Djavax.net.ssl.trustStore=/path/to/truststore \
-Djavax.net.ssl.trustStorePassword=new-password \
-Djavax.net.ssl.trustStoreType=jks"

    In $CATALINA_BASE/bin/setenv.bat:

    set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m -
-Djavax.net.ssl.trustStore=/path/to/truststore -
-Djavax.net.ssl.trustStorePassword=new-password -
-Djavax.net.ssl.trustStoreType=jks"

    Read your specific container’s documentation for information on configuring truststores.

    After AM is installed, you can move the truststore to a different location. For example, the /path/to/am/security/keystores/. If you do, remember to update the truststore path in the container configuration.