Preparing a Truststore

Directory Services 7 introduces a secure by default approach. One aspect of this approach is that all connections to DS 7 instances must be made using secure connection, including LDAPS.

To connect to a DS instance using 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 7 only supports a single truststore. As the truststore is also used for outbound HTTPS connections, your truststore also needs to 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, ensure your web application container; for example, Apache Tomcat, is loading that file as its truststore.

What if I am Evaluating 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.

Important

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.

To Create a Truststore for AM

Follow the steps in this procedure to 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
```
Caution
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.
(Optional) It is recommended to change the default password for the truststore.
Tip
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:
```
$ /path/to/opendj/bin/dskeymgr export-ca-cert \
--deploymentKey $DEPLOYMENT_KEY \
--deploymentKeyPassword password \
--alias ds-ca-cert \
--outputFile ds-ca-cert.pem
```
Note that $DEPLOYMENT_KEY is a Unix variable that contains the DS deployment key, so that it is not logged in the user's command history.
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.

Import the DS certificate into the new truststore:

$ keytool \
  -importcert \
  -alias ds-ca-cert \
  -file ds-ca-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.

Preparing a Truststore

Important

Caution

Tip