OpenLDAP over TLS: Client Setup, StartTLS Testing and Troubleshooting

Turning on TLS in slapd is only half the job. Clients have to trust the certificate and actually use StartTLS or LDAPS. When something fails, the error messages are rarely helpful. This guide covers that second half: checking the server, setting up clients, testing, and troubleshooting. It’s written for CentOS 6 and works much the same on CentOS 7.

Haven’t set up the server yet? Start with Configure LDAP over TLS on CentOS 6. It walks through creating the certificate, loading it with ldapmodify and enabling LDAPS, with screenshots for each step. This page picks up where that one ends.

1. Confirm the server side

On the LDAP server, check that the TLS attributes are in cn=config and that slapd is listening:

ldapsearch -Y EXTERNAL -H ldapi:/// -b cn=config -s base -LLL olcTLSCertificateFile olcTLSCertificateKeyFile
netstat -tlnp | grep slapd

2. Copy the certificate to each client

Clients only need the certificate, never the key:

scp root@ldap.example.com:/etc/openldap/cacerts/LDAP.crt /etc/openldap/cacerts/
cacertdir_rehash /etc/openldap/cacerts

On CentOS 6, OpenLDAP is built against Mozilla NSS. When it reads PEM files from a directory, it needs the hash links that cacertdir_rehash creates.

3. Configure /etc/openldap/ldap.conf

URI         ldap://ldap.example.com/
BASE        dc=example,dc=com
TLS_CACERTDIR /etc/openldap/cacerts
TLS_REQCERT demand

Keep TLS_REQCERT demand in production. allow skips certificate checks and is only for short tests.

4. Test StartTLS and LDAPS

-ZZ makes StartTLS mandatory, so the command fails instead of silently falling back to plain text:

ldapsearch -x -ZZ -H ldap://ldap.example.com -b dc=example,dc=com -LLL uid=jdoe
ldapsearch -x -H ldaps://ldap.example.com -b dc=example,dc=com -LLL uid=jdoe

Look at the certificate the server presents:

openssl s_client -connect ldap.example.com:636 -showcerts </dev/null

On systems with OpenSSL 1.1.1 or newer, you can test StartTLS directly with -connect ldap.example.com:389 -starttls ldap.

5. System logins over TLS (authconfig)

authconfig --enableldap --enableldapauth \
  --ldapserver=ldap://ldap.example.com --ldapbasedn="dc=example,dc=com" \
  --enableldaptls --ldaploadcacert=file:///etc/openldap/cacerts/LDAP.crt --update

Troubleshooting common errors

• “TLS: hostname does not match CN in peer certificate”: the client connected by IP address or a different name. Use the exact name you entered as the Common Name, or reissue the certificate.
• “Peer’s Certificate issuer is not recognized”: the client doesn’t trust the certificate. Check that it’s in TLS_CACERTDIR and run cacertdir_rehash again.
• “ldap_start_tls: Connect error (-11)”: usually the same trust problem, or the server has no TLS attributes in cn=config. Go back to step 1.
• “Can’t contact LDAP server (-1)” on ldaps://: port 636 is closed. Check SLAPD_LDAPS=yes and the firewall.
• slapd won’t start after the change: the ldap user can’t read the key, or the key still has a passphrase.

For more detail, add -d 1 to any ldapsearch command to see the TLS handshake.

Hosted Linux server at www.zwiegnet.com/go

Related guides: Configure LDAP Server on CentOS 6 | Install and Configure phpLDAPadmin on CentOS 6