How to Enable TLS in OpenLDAP

Configure certificates and trust for OpenLDAP StartTLS and LDAPS, enforce secure binds, verify the deployment, and diagnose common handshake failures.

Type
Tutorial
Level
Advanced
Technologies
OpenLDAP, LDAP, LDAPS, PKI
On this page

Transport Layer Security (TLS) is fundamental to securing directory communication—ensuring confidentiality, integrity, and authenticating endpoints for LDAP. Enabling TLS in OpenLDAP is a concrete, technical task that, when performed correctly, protects directory credentials and data from interception or tampering. This guide distills the requirements and precise steps to enable TLS in OpenLDAP, explains critical operational caveats, and clarifies advanced scenarios like mutual TLS authentication.

Why Secure OpenLDAP with TLS?

Unencrypted LDAP exposes information—including credentials—to anyone who can observe network traffic. TLS addresses this by encrypting traffic in transit, authenticating servers (and optionally clients), and defending against common attacks like credential theft or passive eavesdropping. For any production deployment or integration—especially when handling authentication—securing OpenLDAP with TLS is a baseline best practice.

There are two mechanisms for TLS in OpenLDAP:

  • StartTLS: Begins with an unencrypted connection, then negotiates TLS within the same session, typically on the standard LDAP port (389).
  • LDAPS: Traditional LDAP-over-SSL, with encryption from the outset, listening on port 636.

Both approaches ultimately provide strong security when properly configured, but each has distinct operational characteristics.

SSL/TLS in OpenLDAP: StartTLS vs. LDAPS

StartTLS upgrades a standard LDAP connection to TLS using a protocol-specific negotiation, avoiding the need for a separate port and making it easier to integrate with existing deployments. Clients must explicitly request the StartTLS operation after connecting.

LDAPS uses a dedicated port (636), establishing TLS immediately during connection setup. This can simplify firewalls and client configuration in some networks. Both modes can be enabled simultaneously, and both leverage the same underlying TLS infrastructure in OpenLDAP.

It's important to note:

  • StartTLS operates on port 389 (the traditional LDAP port).
  • LDAPS operates on port 636.
  • Both provide equivalent encryption, but protocol compatibility or legacy software may dictate which to use.

Certificate and Key Requirements

Enabling TLS in OpenLDAP requires at minimum:

  • A valid server X.509 certificate—the Common Name (CN) or a subjectAltName must match the server's fully-qualified domain name (FQDN).
  • The private key corresponding to the server certificate.
  • The certificate authority (CA) certificate or chain that signed the server certificate.

Typical locations might include:

  • /etc/ssl/certs/server.crt (server certificate)
  • /etc/ssl/private/server.key (private key)
  • /etc/ssl/certs/ca-cert.pem (CA certificate)

The private key must not be encrypted (must have no passphrase), as slapd cannot unlock password-protected key files when running unattended.

Client certificates are only required if mutual TLS (client authentication) is to be enforced; otherwise, only server-side certificates are necessary. This distinction is critical for deployment planning.

Configuring TLS for OpenLDAP

Server-Side Configuration

Using slapd.conf

TLS settings in slapd.conf typically use:

  • TLSCertificateFile – Path to the server certificate.
  • TLSCertificateKeyFile – Path to the unencrypted private key.
  • TLSCACertificateFile – Path to the CA certificate (can include a chain).
  • TLSCACertificatePath – Directory containing CA certificates.

Example:

text
TLSCertificateFile      /etc/ssl/certs/server.crt
TLSCertificateKeyFile   /etc/ssl/private/server.key
TLSCACertificateFile    /etc/ssl/certs/ca-cert.pem

Using cn=config

In cn=config (the dynamic configuration backend), the equivalent settings are the olcTLS* attributes, such as:

  • olcTLSCertificateFile
  • olcTLSCertificateKeyFile
  • olcTLSCACertificateFile
  • olcTLSCACertificatePath

These can be managed with ldapmodify and appropriate LDIF files.

Client-Side Configuration

Clients must trust the CA that issued the server certificate. This trust is specified in the client’s ldap.conf using:

  • TLS_CACERT – Points to the CA certificate file.
  • TLS_CACERTDIR – Points to a directory of CA certificates.

If this is not set, TLS negotiation will fail because the client cannot verify the server’s identity.

Example:

text
TLS_CACERT     /etc/ssl/certs/ca-cert.pem

Operational Caveats: Permissions and Key Management

TLS security depends not just on cryptography but also operational discipline. Key points:

  • The server’s private key must be readable only by the slapd process owner (typically openldap). Suggested permission: at least 0640, owned by openldap user and group.
  • Certificate files (server and CA) may be world-readable but must not be writable by unauthorized users.
  • Encrypted private key files are not supported: slapd cannot prompt for or accept a passphrase at startup. Using an encrypted key will cause slapd to fail to read the key and not start.
  • When rotating certificates, ensure old keys are securely destroyed and permissions are correctly maintained.

Failure to maintain these standards can lead to slapd startup errors, exposure of private keys, or failures in client negotiation due to missing trust.

Enabling and Testing TLS in OpenLDAP

Listening for LDAPS and StartTLS

  • To enable LDAPS, configure slapd to listen on ldaps:// (port 636) via the server startup parameters or within the configuration. Multiple listeners (for ldap:// and ldaps://) can be specified.
  • StartTLS requires no additional listener; slapd must be configured with TLS, and clients initiate StartTLS explicitly.

Basic Validation

After configuration:

  • Use ldapsearch or similar tools to test StartTLS support:
    • For StartTLS: Issue a search with -ZZ to enforce StartTLS, expecting a successful encrypted connection.
  • To test LDAPS, connect on port 636.
  • Use openssl s_client to inspect the presented certificate, chain, and reported TLS parameters.
  • A successful test results in:
    • No certificate validation errors.
    • An encrypted connection (confirmed by ldapsearch or openssl).
    • slapd logs showing the TLS negotiation; failure here suggests misconfiguration of files, permissions, or trust.

Optional: Mutual TLS and Certificate-based Authentication

While default TLS usage requires only server-side certificates, OpenLDAP can be configured to enforce mutual TLS (mTLS)—requiring clients to present valid certificates.

In this mode:

  • slapd checks the client certificate chain against its trusted CA list.
  • The client’s X.509 subject DN can be mapped to a user entry in the directory.
  • Mapping transformations or exceptions are managed with olcAuthzRegexp rules.

Operational caveats include:

  • Certificate subject names must match (or be mapped to) LDAP DNs of users.
  • Discrepancies between certificate subject and LDAP entry will result in failed authentication.
  • mTLS is only required in environments demanding strong client identification and cannot be used in all application scenarios.

Common Misconceptions and Troubleshooting Advice

Misconceptions

  • You must use both StartTLS and LDAPS for best security.
    • In reality, either is sufficient for full encryption. Both may be enabled for legacy/client compatibility, but it is not a requirement.
  • Client certificates are always required for TLS.
    • Server certificates alone are enough for encrypted traffic and server authentication; client certs are needed only for mutual TLS.
  • Encrypted private keys are supported by slapd.
    • They are not—slapd cannot prompt for a passphrase, causing startup failures if an encrypted key is provided.
  • Any certificate from any CA is suitable.
    • Certificates must form a trusted chain back to a CA trusted by clients, and the server certificate’s subject CN or SAN must match the actual hostname used for connection.

Troubleshooting Tips

  • Connection fails with “certificate verify failed”: The client likely lacks the CA certificate or has an incorrect path in ldap.conf.
  • slapd fails to start, or reports key errors: Most often, this involves wrong permissions or an encrypted private key.
  • Client reports hostname mismatch: The server certificate does not match the address used by the client.
  • Mutual TLS authentication fails: The client certificate is untrusted, mismatched, or there is no LDAP user mapping.

Best Practices and Further Reading

  • Rotate and audit certificates regularly; update configuration when certificates renew.

  • Use strong permissions; keys must not be accessible by unauthorized users.

  • Minimize CA sprawl by trusting only those authorities required for your deployment.

  • Always consult and validate with the latest, official OpenLDAP documentation:

    • OpenLDAP Administrator’s Guide (TLS/SSL)
    • OpenLDAP Faq-O-Matic on TLS

Following these principles will let you confidently deploy and maintain robust, encrypted OpenLDAP environments.

Sources

Related resources