FAQ: SSL certificates and secured connections in IDM/OpenIDM

Last updated Sep 27, 2019

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

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/OpenIDM.

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

A. You can import a DS/OpenDJ certificate into the IDM/OpenIDM truststore by following the steps in Password Synchronization Plugin Guide › To Import the DS Certificate into the IDM Truststore.

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:

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/OpenIDM is not pointing to the truststore, OR
  • The certificate being presented by the client/server does not match what is present in the truststore.

To resolve this issue, you should verify that the relevant certificate, any intermediary and root certificates from the CA have been imported into the truststore location that's defined in the secrets.json file, or the boot.properties file depending on IDM/OpenIDM version. 

See Integrator's Guide › Accessing IDM Keys and Certificates 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/OpenIDM, 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/OpenIDM 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:
    • Specify the location of the truststore:
  2. Restart IDM/OpenIDM.

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/OpenIDM?

A. Yes you can. See How do I limit the supported secure protocols and cipher suites in IDM/OpenIDM (All versions)? 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)?

Integrator's Guide › Securing and Hardening Servers

Related Training


Related Issue Tracker IDs

OPENICF-681 (LDAP connector: provide the ability to pick up a specific private key in a keystore using certificate alias)

Copyright and TrademarksCopyright © 2019 ForgeRock, all rights reserved.