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 Jun 15, 2021

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: javax.net.ssl.SSLHandshakeException: 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_192 or later DS 5.x and 6

AM 5, 5.5, 5.5.1 and 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 5, DS 5.5, DS 5.5.1, DS 5.5.2 or 6 after restricting DS cipher suites or Java upgrade

SSL handshake failed with no cipher suites in common in DS 5 after restricting cipher suites or upgrading Java

JDK 1.7  DS 5 Invalid Padding length error when attempting to connect to DS 5 or OpenDJ 3.x via LDAPS
JDK 1.7 (pre-update 51) DS 5 LDAPS client connections fail with SSLHandshakeException: no cipher suites in common in DS 5 and OpenDJ 3.x
Note

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

Caution

Pre-DS 7: 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. DS 7 and later reload file-based keystores and truststores when their contents change.

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 -Djavax.net.debug=SSL,handshake,trustmanager' bin/start-ds
Note

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:

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

These files are located in /path/to/ds/config; in DS 6.x, 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 (All versions)? 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.
Note

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

See Also

FAQ: SSL certificate management in DS 5.x or 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 5.x and 6.x?

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

LDAP Access

Security Problems

About Logs

LDAP Connection Handler

Related Training

N/A

Related Issue Tracker IDs

N/A


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