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
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.
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
AM then attempts to add the DS self-signed certificate to that store, with an alias of
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.
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
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
(Optional) It is recommended to change the default password for the truststore.
The default password of the
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
$DEPLOYMENT_KEYis 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
SubjectAlternativeNameattribute; 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_OPTSvariable in the
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.