How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 8, 2021

The purpose of this article is to provide guidance on using SSL securely with LDAP clients in DS.

1 reader recommends this article


DS 7 introduces changes to security and key management. See Security Guide › Secure Connections and Security Guide › Key Management for further information.  

In pre-DS 7, you should follow the advice in this article.


DS supports SSL/TLS in two ways: the first is using a de-facto protocol called “LDAPS” often on port 636 and the second is using the standard START_TLS operation to switch a normal LDAP connection into TLS mode.

After configuring the server to provide either LDAPS or LDAP with START_TLS, you also need to configure the LDAP clients correctly; you will not have a secure connection unless the clients are configured correctly.

Most LDAP clients are written using a small number of different SSL toolkits, which need to be configured differently, but they all need either the server’s SSL certificate or the CA certificate that signed the server’s SSL certificate. You can extract these using the following command in the openssl command-line program:

$ openssl s_client -connect [hostname]:[port] -showcerts

replacing [hostname] and [port] with appropriate values.

The output will include all the certificates sent by the server, which you need to copy and paste into separate files. The certificate for a server created by DS's setup tool will look like this:

Certificate chain 0 s:/O=Administration Connector Self-Signed Certificate/CN=[hostname]    i:/O=Administration Connector Self-Signed Certificate/CN=[hostname] -----BEGIN CERTIFICATE----- MIICFTCCAX6gAwIBAgIEU9tJhjANBgkqhkiG9w0BAQUFADBPMTkwNwYDVQQKEzBB [...more base64...] AsdGJP+jxHEh -----END CERTIFICATE-----

You need to copy all the lines from BEGIN CERTIFICATE to END CERTIFICATE (inclusive) into a text file, in this case /path/to/my/server.pem.

However, if you have a certificate issued to you by a CA, the openssl output will look more like this:

Certificate chain 0 s:/serialNumber=something-unique/OU=XY12345668/OU=See (c)14/OU=Domain Control Validated - RapidSSL(R)/CN=[hostname]    i:/C=US/O=GeoTrust, Inc./CN=RapidSSL CA -----BEGIN CERTIFICATE----- MIIFNjCCBB6gAwIBAgIDE4OoMA0GCSqGSIb3DQEBBQUAMDwxCzAJBgNVBAYTAlVT [...base64 of the server certificate you can ignore...] TqMs90rAdzwrQTsuaQdUhx8rE6bzkO5WOEIphNQToPpIOUygZm4x8QdG -----END CERTIFICATE-----  1 s:/C=US/O=GeoTrust, Inc./CN=RapidSSL CA    i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA -----BEGIN CERTIFICATE----- MIID1TCCAr2gAwIBAgIDAjbRMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT [...base 64 of a certificate you can ignore...] LEL2TxyJeN4mTvVvk0wVaydWTQBUbHq3tw== -----END CERTIFICATE-----  2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA    i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA -----BEGIN CERTIFICATE----- MIIDVDCCAjygAwIBAgIDAjRWMA0GCSqGSIb3DQEBBQUAMEIxCzAJBgNVBAYTAlVT [...base 64 of the certificate you should copy...] 5fEWCRE11azbJHFwLJhWC9kXtNHjUStedejV0NxPNO3CBWaAocvmMw== -----END CERTIFICATE-----

You should copy the last certificate to /path/to/my/ca.pem.

DS SDK Clients

The ldapsearch (etc) tools provided with the DS server will automatically trust certificates signed by CA certificates held in the server’s config/truststore file. The DS documentation describes how to maintain that file.

If you are writing your own clients using the DS SDK, you have to provide the trusted CA certificate in a JKS file and pass that to a TrustManager building the SSLContext object.

To add the trusted CA certificate to a JKS file, use the following command:

$ keytool -keystore /path/to/my/truststore -import -alias root-ca -file /path/to/my/ca.pem

You will be prompted for a password to protect the truststore and then prompted to trust the new certificate.

JNDI Clients

A Java® client written using JNDI needs to have the server’s certificate (or CA’s certificate) imported into the JVM's cacerts keystore. The following code snippet will trust any servers with certificates signed by a CA in the cacerts keystore:

Hashtable env = new Hashtable(11); env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory"); env.put(Context.PROVIDER_URL, "ldaps://[hostname]:[port]/"); env.put(Context.SECURITY_PROTOCOL, "ssl"); DirContext ctx = new InitialDirContext(env);

OpenSSL® Clients

Most native LDAP clients use the OpenSSL library. Examples include the ldapsearch program on most Linux® distributions and on the Mac® OS X® operating system, which uses a simple text file listing all the trusted CA certificates.

You can add the CA certificate to the system-wide list of trusted CAs, but the location of that file varies widely and so won’t be discussed further.

The other option is to create a local list of trusted CAs and to append your CA certificate to that list using the following commands.

$ touch /path/to/my/ca-certs.pem $ cat /path/to/my/ca.pem >> /path/to/my/ca-certs.pem

To use the list of trusted CAs, you can set an environment variable using the following command:

$ LDAPTLS_CACERT=/path/to/my/ca-certs.pem $ export LDAPTLS_CACERT

Alternatively, set the TLS_CACERT option in an appropriate ldap.conf file. Then just run the ldapsearch program using the following command:

$ ./ldapsearch --hostname --port 4444 --baseDN "dc=example,dc=com" --searchScope base "(objectclass=*)"

Mozilla® NSS Clients

Some native LDAP clients use the Mozilla NSS library. An example is the ldapsearch program in Oracle® Solaris®. This library uses several databases inside a disk directory and you need to add the certificates to these databases.

To create a new set of NSS databases, create an empty directory and initialise it with the certutil command:

$ mkdir /path/to/my/nssdb $ certutil -N -d /path/to/my/nssdb

The certutil command will prompt for a password, which is not important unless you are storing private keys in the databases.

If you are using a self-signed certificate for your server then you should import it as a trusted peer:

$ certutil -A -d /path/to/my/nssdb -n "opendj" -i /path/to/my/server.pem -a -t P,,

Alternatively, if you have a certificate signed by a CA, then import the CA certificate into the database. You need to configure NSS to trust SSL certificates signed by it as a CA:

$ certutil -A -d /path/to/my/nssdb -n "ca" -i /path/to/my/ca.pem -a -t C,,

To use the databases with the client, you need to pass the directory to the client, for example:

$ ./ldapsearch --hostname --port 4444 --useSSL --trustAll --baseDN "dc=example,dc=com" --searchScope base "(objectclass=*)"

See Also

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

Developer's Guide › Authenticating To the Directory

Administration Guide › Preparing For Secure Communications

Administration Guide › LDAP Client Access Over SSL

SSL and Custom Sockets in JNDI

Mozilla NSS certutil documentation

Related Training

ForgeRock Directory Services Core Concepts (DS-400)

Related Issue Tracker IDs


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