PingAM 7.5.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 that 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.
What if I am evaluating AM using an embedded DS?

If you are installing AM for evaluation purposes, AM creates a copy of your JDK’s default lib/security/cacerts truststore, names it truststore, and places it in /path/to/openam/security/keystores/.

AM then attempts to add the DS self-signed certificate to that store, with an alias of ds-ca-cert.

If the lib/security/cacerts truststore does not have the default password of changeit, and/or if it does not have at least 644 permissions, then AM installation will fail, as it will not be able to open the truststore to add the DS certificate.

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/openam directory before you install AM, the installation process detects that the directory is not empty and the installation fails.

    After AM is installed, you can move the truststore to a different directory. For example, the /path/to/openam/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

  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"

    Refer to 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/openam/security/keystores/. If you do, remember to update the truststore path in the container configuration.