How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 12, 2023

The purpose of this article is to provide information on making AM communicate with a secured LDAP (LDAPS) server such as DS (SSL/TLS enabled). This information applies whether you are using the DS-generated self-signed certificate or a CA-signed certificate for a CA that may or may not already be present in the security store.


2 readers recommend this article
Note

This article does not apply to AM 7 and later, because DS 7 introduces a secure by default approach. One aspect of this approach is that all connections to DS 7 instances must be made using secure connections, including LDAPS. See Preparing a Truststore for further information on making AM communicate with a secured LDAP server in AM 7 and later.

Making AM communicate with a secured LDAP server

When your LDAP server uses LDAP secured access (LDAPS), you must import the LDAP server certificate into the JVM truststore used by AM. This allows the JVM to trust the LDAP server certificate and enables AM to connect to the secured LDAP server. Additionally, there are some version-specific issues you should be aware of to ensure your setup is successful. See the Known issues section for further information.

Once you have resolved any version-specific issues, you can proceed to import the LDAP server certificate into the JVM truststore used by AM; the following instructions differ depending on whether you are using the default JVM truststore or a non-default one:

Note

It is best practice to create a new JVM truststore with the certificates you need in your environment, and configure your container to use it, rather than use the default JVM truststore.

See How do I import a certificate into the truststore used by AM (All versions) for SSL? for further information.

Known issues

The following known issues affect specific AM / Java® versions:

AM version Java version Issue

AM 6.0.0.x

ssoadm in AM 6.0.0.x, 6.5.0 and 6.5.0.1

JDK 1.8.0_192 or later;

JDK 11

These versions of AM and ssoadm ​​​​do not correctly support the TLSv1.2 protocol.
AM 6.x JDK 1.8.0_181 These versions of AM introduce stricter hostname validation.

Lack of TLS 1.2 protocol support

AM 6.0.0.x, and certain ssoadm versions (in AM 6.0.0.x, 6.5.0 and 6.5.0.1) ​​​​do not correctly support the TLSv1.2 protocol, whereas using more secure ciphers or installing DS in production mode forces the protocol version to TLSv1.2. In Java versions prior to JDK 1.8.0_192, unsupported cipher suites were simply ignored, which is why these connections continued to work despite the mismatch in protocol versions.

Changes were introduced in JDK 1.8.0_192 (JDK-8162362 : Introduce system property to control enabled ciphersuites), which changed how the JDK determined which cipher suites (and resulting protocol) to use. As a consequence of these Java changes, AM and ssoadm cannot communicate with DS using a SSL/TLS secured connection because it uses different cipher suites and protocol to the DS server; both the client and server must support the same cipher suites and protocol agreed upon when attempting to establish a secure connection.

You can resolve this issue as follows:

  • If the issue is on the AM side, you can upgrade to AM 6.5 or later; you can download this from Backstage.
  • If the issue is on the ssoadm side, you can upgrade to AM 6.5.0.2 or AM 6.5.1, and then upgrade ssoadm to version 5.1.2.3; you can download this from Backstage.

See AM 6.0.0.x, IDM 6.x and Rest2LDAP cannot connect to DS 6 after restricting DS cipher suites or Java upgrade and Cannot install or use ssoadm in AM 6.0.x, 6.5.0 and 6.5.0.1 after restricting configuration store (DS) cipher suites or Java upgrade for further information and workarounds.

Stricter hostname validation

LDAP SSL hostname validation is stricter in AM and DS than it was in earlier versions. AM checks the hostname in the LDAP server certificate correctly matches the hostname used to connect to the secured directory server (for example, DS or Active Directory®) and DS checks that the server it is trying to connect to has a certificate that matches the hostname.

Java 1.8.0_181 introduced changes to improve LDAP support by enabling endpoint identification algorithms by default for LDAPS connections; this also results in stricter hostname validation.

As a result of these changes, you must ensure the hostname you are connecting to the LDAP server with matches the hostnames specified in the server certificate via the SAN (Subject Alternative Name). See LDAP connection fails with No subject alternative DNS name matching error in AM and DS (All versions) for further information.

Using the default JVM truststore

You can do this as follows:

  1. If you are using the DS generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command: $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin If you want to export the certificate in PEM format, you should use the following command instead: keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into the JVM truststore used by AM using the following keytool command: $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype] For example, your command would look similar to this if you were importing the DS generated self-signed certificate into the JVM truststore, where AM is deployed and running on Apache Tomcat™ web container: $ keytool -importcert -alias server-cert -file /path/to/server-cert.crt -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -storetype JKS

Finally, AM should be configured to connect to the LDAP server on the secured port as required.

Using a non-default truststore

You can do this as follows:

  1. If you are using the DS generated self-signed certificate, you must first export this with its alias of 'server-cert' using the following keytool command: $ keytool -export -alias server-cert -file server-cert.crt -keystore /path/to/ds/config/keystore -storetype [storetype] -storepass:file /path/to/ds/config/keystore.pin If you want to export the certificate in PEM format, you should use the following command instead: keytool -exportcert -alias [alias] -keypass [keypassword] -keystore [keystore] -storetype [storetype] -storepass [storepassword] -rfc -file [keyStore.pem]
  2. Add the following JVM option to the web container or application server on which you have deployed AM to identify your truststore: -Djavax.net.ssl.trustStore=/path/to/truststore
  3. Import the generated self-signed certificate or the issuer certificate of the CA who signed the LDAP server certificate (if it is not already present in the store) into your truststore using the following keytool command: $ keytool -importcert -alias [alias_of_certificate_entry] -file [path_to_certificate_file] -trustcacerts -keystore /path/to/truststore -storetype [storetype]

Finally, AM should be configured to connect to the LDAP server on the secured port as required.

See Also

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

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

FAQ: SSL certificate management in AM and Agents

FAQ: SSL certificate management in DS 6.x

Setting Up Keys and Keystores

Using Self-Signed Certificates

Preparing Configuration Stores

Related Training

N/A

Related Issue Tracker IDs

N/A


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