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
This file contains multiple CA certificates. Its password, by default, is
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
and places it in
AM then attempts to add the DS self-signed certificate to that store, with an alias of
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/openamdirectory 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
For security reasons, you should change the default password for the truststore.
The default password of the
keytool -storepasswdoption 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
SubjectAlternativeNameattribute; however, certificate hostname validation is strict.
ds-cert.pemfile 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_OPTSvariable in the
export CATALINA_OPTS="$CATALINA_OPTS -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m \ -Djavax.net.ssl.trustStore=/my/directory/truststore \ -Djavax.net.ssl.trustStorePassword=new-password \ -Djavax.net.ssl.trustStoreType=jks"
set "CATALINA_OPTS=%CATALINA_OPTS% -server -Xmx2g -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m - -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.