How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I troubleshoot connection via LDAPS issues in DS (All versions)?

Last updated Jan 12, 2023

The purpose of this article is to provide information on troubleshooting connection via LDAPS issues in DS. This article assumes you are connecting to a DS from AM using a secure LDAP connection (over SSL/TLS).

2 readers recommend this article

Load balancer configuration

If you are using a load balancer in front of DS, you should ensure you have specified the appropriate details in the SSL certificates depending on your configuration:

  • If the load balancer is doing SSL pass-through, you only need to specify the DS hostnames in the SSL certificates.
  • If the load balancer is using SSL, you need to specify the load balancer hostname as the Cert Subject and the DS hostnames as the Subject Alternate Names.

To help pinpoint these issues, you should try the following tests and let us know the results when you submit a ticket with the troubleshooting data:

  1. Bypass the load balancer and point straight to a DS server; retest to determine if the load balancer is causing the connection issues.
  2. Point the load balancer to an individual DS server and retest. Repeat with the other DS servers. If this works, it suggests there is an issue with the DS Subject Alternative Name or with a known feature in the Oracle® JDK that prevents a triple handshake vulnerability. An issue can manifest as a result of the JDK feature if the load balancer does SSL session resumption with multiple different SSL certificates. This is discussed in the following Stack Overflow article and Puppet Server: Known Issues: SSL Server Certificate Change and Virtual IP Addresses. If it is affecting you, you will also see server certificate change is restricted errors in your server log, for example: server certificate change is restrictedduring renegotiation

Java upgrades

Some Java® upgrades have caused LDAPS issues in DS as indicated in the following table:

Java versions DS versions Solution
JDK 1.8.0_282 or later DS 6 Status command doesn't work, but dsconfig does: OPENDJ-8651 (status command doesn't work with latest JDK8 versions)
JDK 1.8.0_192 or later DS 6 AM 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 6 after restricting DS cipher suites or Java upgrade

If you use DS 6.5, 6.5.1 or 6.5.2 with Java 11, it is recommended you disable TLS 1.3 because of known issues with Oracle JDK 11 and OpenJDK 11's implementation of TLS 1.3. See How do I disable TLS 1.3 when running DS 6.5, 6.5.1 or 6.5.2 with Java 11.0.5 and earlier, or Java 1.8.0_272 and later? for further information.

Troubleshooting connection issues


DS 7 and later reload file-based keystores and truststores when their contents change.

DS 6.x: If you have made any changes to the keystore or truststore, you should make sure you have restarted DS to ensure it is using the updated files before proceeding to troubleshoot.

There are a number of different types of data that you should collect to help us troubleshoot connection issues via LDAPS. If you are experiencing connection issues, you should collect the following data and submit it to us when you raise the ticket to enable us to help you more quickly:

  • Server logs
  • SSL debug logs
  • Keystore information
  • Current JVM options
  • Third-party tools output

Server logs

Server logs (Access and Error) record details about all the operations processed by the server, in addition to details of all server events, errors and warnings. If there are CONNECT messages in the Access log, you know that the DS server is at least receiving TCP connections from AM.

These files are located in the /path/to/ds/logs directory where DS is installed.

SSL debug logs

The SSL debug logs provide detailed SSL debugging information. When enabled, the SSL debug logs are output to the server.out file, which is located in the /path/to/ds/logs directory where DS is installed.

You can enable SSL debug logs by starting the DS server with additional options:

OPENDJ_JAVA_ARGS='-server,handshake,trustmanager' bin/start-ds

Enabling SSL debug logs is not supported with the embedded DS. Whereas the embedded DS is tightly coupled with AM and runs within the same JVM instance, there is no mechanism or option available to isolate AM from this scenario or to allow for the Java arguments of the embedded instance to take precedence.

Keystore information

Keystore information provides us with details about the contents of each keystore and truststore; keystores are used for private keys whereas truststores are used for public, signed certificates.

By default, truststore and/or keystore files and passwords are stored in different stores depending on their purpose:

  • admin-truststore and admin-keystore for administration purposes.
  • truststore and keystore for everything else.
  • ads-truststore for replication purposes (DS 6.x only).

These files are located in /path/to/ds/config; ads-truststore is located in /path/to/ds/db/ads-truststore for new installs.

See Cryptographic Keys for further information.

You can run the keytool command for each keystore and truststore to see the contents:

$ keytool -list -v -keystore [keystore] -storetype [storetype] -storepass [password]

replacing [keystore] with the full path and name of the keystore or truststore file, [storetype] with the type of keystore (for example JCEKS or JKS), and [password] with the corresponding keystore or truststore password.

Current JVM options

Current JVM settings can be useful when troubleshooting connection issues. See How do I collect JVM data for troubleshooting DS? for information on finding your current JVM settings.

Third-party tools output

There are two third-party tools, which can help with debugging LDAPS connection issues by providing information about the SSL connection as well as attempting a SSL handshake. These tools are:

  • openssl - you can run a command such as the following to provide this information: $ openssl s_client -connect [hostname:port] -showcerts Press Ctrl+C to quit openssl.
  • Keystore explorer - this is a GUI application that provides similar information. You need to specify the hostname and port to get the connection information.

These are third-party tools that we suggest can be used for troubleshooting but are not supported by ForgeRock.

See Also

How do I disable TLS 1.0 and TLS 1.1 in DS (All versions)?

FAQ: SSL certificate management in DS 6.x

AM (All versions) fails to connect to DS using a secured connection with an ERROR: Connection factory became offline

How do I configure LDAPS clients in DS 6.x?

How do I make AM 6.x communicate with a secured LDAP server?

LDAP Access

Security Problems

About Logs

LDAP Connection Handler

Related Training


Related Issue Tracker IDs


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.