ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: SSL certificates and secured connections in IDM

Last updated Apr 8, 2021

The purpose of this FAQ is to provide answers to commonly asked questions regarding SSL certificate management and SSL/TLS secured connections in IDM.

Frequently asked questions

Q. What is the difference between the keystore and truststore?

A. Truststores are used for storing trusted public certificate entries, CA and Self-Signed Certificates that you trust to validate the identity of the certificate presented to the server, and keystores are used for storing private keys; the truststore is used to find the certificates of trusted servers/clients when a remote party presents its certificate to the IDM server, whereas the keystore contains the encryption keys used by IDM.

Q. How do I import a DS certificate into the IDM truststore?

A. You can import a DS certificate into the IDM truststore by following the steps in Password Synchronization Plugin Guide › Enable IDM to trust DS Certificates.

Q. Why am I seeing SLHandshakeException: unable to find valid certification path errors?

A. If you see certificate errors such as the following in your logs:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed:  sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

This means that:

  • IDM is not pointing to the truststore, OR
  • The certificate presented by the client/server does not match the one in the truststore.

To resolve this issue, you should verify that the relevant certificate, and any intermediary and root certificates from the CA have been imported into the truststore location that's defined in the secrets.json file (IDM 6.5 and later) or the boot.properties file (pre-IDM 6.5).

See Security Guide › Managing Secret Stores, Certificates and Keys for further information.

If the error persists once you have verified your setup appears correct, you should enable SSL debug logging to investigate this issue further.

Q. How do I enable SSL debug logging?

A. SSL debugging traces the SSL handshaking phase. You can enable SSL debugging via the OPENIDM_OPTS environment variable.

On Unix® and Linux® systems:

$ cd /path/to/idm/ $ export OPENIDM_OPTS="-Djavax.net.debug=all" $ ./startup.sh

On Microsoft® Windows® systems:

C:\> cd \path\to\idm C:\path\to\idm> set OPENIDM_OPTS=-Djavax.net.debug=all C:\path\to\idm> startup.bat

You can also edit the startup.sh or startup.bat files to update the default OPENIDM_OPTS values.

Q. What are the javax.net.ssl.keyStore and javax.net.ssl.trustStore properties used for?

A. These properties allow you to specify the exact location of the keystore or truststore. These properties are set by IDM, but there can be a timing issue where the connection is made ahead of the properties being set, which can prevent the server finding the necessary certificates or keys. Therefore, it is sometimes necessary to set these properties, especially if you are experiencing certificate errors but have already verified that the certificate exists in the correct location and IDM is pointing to it.

You can set these properties as follows:

  1. Add the following to the system.properties file (located in the /path/to/idm/conf directory) depending on which store is needed:
    • Specify the location of the keystore: javax.net.ssl.keyStore=[keystore_location] javax.net.ssl.keyStorePassword=[keystore_passwword]
    • Specify the location of the truststore: javax.net.ssl.trustStore=[truststore_location] javax.net.ssl.trustStorePassword=[truststore_passwword]
  2. Restart IDM.

You can also edit the startup.sh or startup.bat files to update the JAVA_OPTS value to include these properties, for example, using the format: -Djavax.net.ssl.keyStore etc.

Q. Can I change which SSL/TLS ciphers are used by IDM?

A. Yes you can. See Installation Guide › Enable and Disable Secure Protocols and Cipher Suites (IDM 7 and later) or How do I limit the supported secure protocols and cipher suites in IDM 5.x and 6.x? for further information.

See Also

SSLHandshakeException or ClassCastException when using an HSM and Java 11 with ForgeRock products

How do I connect to IDM (All versions) with mutual SSL authentication from IG (All versions)?

Security Guide

Related Training


Related Issue Tracker IDs


Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.