Prepare the truststore

From Directory Services 7 onwards, all connections to DS instances must be over a secure connection, including LDAPS.

To connect to a DS instance over LDAPS, AM requires access to the self-signed certificate that DS generates.

AM also requires access to CA certificates for making secure connections to other sites, for example calling out to social providers using HTTPS.

To provide these certificates to AM, you use a truststore that contains the necessary certificates, and configure AM to use that truststore when starting up.

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

As a best practice, you should create a new truststore with the certificates you need in your environment, and configure your container to use it. You should not add the DS certificate to the JVM’s truststore, since other applications may be using it.

AM supports a single truststore. Because this truststore is also used for outbound HTTPS connections, the truststore must contain the CA certificates of sites that your instance communicates securely with.

For example, to keep all existing CA certificates, copy the cacerts keystore file, change its password to a secure one, and import the DS certificate into it.

Then, make sure that your web application container (for example, Apache Tomcat) loads that file as its truststore.

Using a separate truststore for AM means that updates to the JVM truststore in patch releases will not be 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.

You should periodically update the AM truststore 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

Create a copy of the default truststore for AM to use, and configure your container to use the store:

Make a copy of your JDK’s 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 /my/directory/truststore

If you place the truststore in the /path/to/openam directory before installing AM, the installation process will detect that the directory is not empty and the installation will not continue.

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

For security reasons, you should 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 /my/directory/truststore
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
```
Export the DS server certificate:
```
$ keytool -exportcert \
-keystore /path/to/opendj/config/keystore \
-storepass $(cat /path/to/opendj/config/keystore.pin) \
-alias ssl-key-pair \
-rfc \
-file ds-cert.pem
```
The default DS server certificate only has the hostname you supplied at setup time, and localhost, as the value of the SubjectAlternativeName attribute; however, certificate hostname validation is strict.

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

Import the DS server certificate into the new truststore:

$ keytool \
-importcert \
-file ds-cert.pem \
-keystore /my/directory/truststore

To configure the truststore in Apache Tomcat so that AM can access it, append the truststore settings to the CATALINA_OPTS variable in the $CATALINA_BASE/bin/setenv.sh file.

For example:
```
export CATALINA_OPTS="$CATALINA_OPTS -Djavax.net.ssl.trustStore=/my/directory/truststore\
-Djavax.net.ssl.trustStorePassword=new-password\
-Djavax.net.ssl.trustStoreType=jks"
```
Refer to your specific container’s documentation for information on configuring truststores.

Once 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 reconfigure its path in the container.

AM 7.2.2

Prepare the truststore

Create a truststore for AM