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:
-
Copy the default truststore; for example,
$JAVA_HOME/lib/security/cacerts
, name ittruststore
, 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. -
For improved security, change the default password for the truststore.
The default password of the $JAVA_HOME/lib/security/cacerts
truststore ischangeit
.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
-
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.
-
-
Import the DS CA certificate into the new truststore:
$ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/truststore
-
To configure the truststore in Apache Tomcat so that AM can access it, append the truststore settings to the
CATALINA_OPTS
variable in thesetenv
file.For example:
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"
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.