--- title: Prepare the truststore description: Directory Services 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. component: pingam version: 7.4 page_id: pingam:installation:prepare-trust-store canonical_url: https://docs.pingidentity.com/pingam/8.1/installation/prepare-trust-store.html llms_txt: https://docs.pingidentity.com/pingam/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Install", "Security"] page_aliases: ["install-guide:prepare-trust-store.adoc"] superseded_by: https://docs.pingidentity.com/pingam/8.1/installation/prepare-trust-store.html section_ids: prepare-am-trust-store: Create a truststore for AM --- # Prepare the truststore Directory Services 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. | > **Collapse: What if I am evaluating AM using an embedded DS?** > > If you are [installing AM for evaluation purposes](../evaluation/preface.html), 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: 1. Copy the default truststore; for example, `$JAVA_HOME/lib/security/cacerts`, name it `truststore`, and place it in a directory of your choice: ```bash $ 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. | 2. For improved security, 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: ```bash $ keytool -storepasswd -keystore /path/to/truststore Enter keystore password: changeit New keystore password: new-password Re-enter new keystore password: new-password ``` 3. 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](https://docs.pingidentity.com/pingds/7.4/security-guide/pki.html#about-deployment-ids). Use the `dskeymgr` command to export the CA certificate: ```bash $ /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. 4. Import the DS CA certificate into the new truststore: ```bash $ keytool \ -importcert \ -file /path/to/ca-cert.pem \ -keystore /path/to/truststore ``` 5. To configure the truststore in Apache Tomcat so that AM can access it, append the truststore settings to the `CATALINA_OPTS` variable in the `setenv` file. For example: * Linux * Windows In `$CATALINA_BASE/bin/setenv.sh`: ```bash 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" ``` In `$CATALINA_BASE/bin/setenv.bat`: ```powershell 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.