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:
- Bypass the load balancer and point straight to a DS server; retest to determine if the load balancer is causing the connection issues.
- 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 restrictederrors in your server log, for example: javax.net.ssl.SSLHandshakeException: server certificate change is restrictedduring renegotiation
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 5.x and 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 5.x and 6|
|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|
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.
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 (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
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 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.
These are third-party tools that we suggest can be used for troubleshooting but are not supported by ForgeRock.