Running OpenLDAP with TLS encryption

Most modern LinuxDistributions will support OpenLDAP and TLS "out of the box". They'll all require generation of appropriate SSL certificates, and some will require additional configuration.


You'll want to create certificates. See SSLNotes to learn how.

When creating certificates, set the HostName (cn) to the name that you'll be connecting to the server on! It'll fail otherwise. For example, if you'll be using LDAP + TLS to, set the Common Name to, and only ever connect to that name. If you use another name that resolves to the same IP, it's not going to work.

It is important to have the permissions and ownership set right on your slapd.pem certificate. If you don't, slapd(8)? will fail to start and exit without displaying an error. The exact permissions will depend on your distribution.


Update your slapd.conf appropriately to point to your key files
TLSCACertificateFile /etc/ssl/cacert.pem
TLSCertificateFile /etc/ldap/certs/slapd-cert.pem
TLSCertificateKeyFile /etc/ldap/certs/slapd-key.pem
TLSRandFile /etc/ldap/certs/randfile

Distribution Specific notes

Debian Woody

Debian Woody ships with a version of slapd(8)? that doesn't have TLS support enabled. Check out the References section below for links to backports available for Debian Woody, or else rebuild the Debian slapd(8)? Package with TLS support yourself. Change the line in debian/rules from --without-tls to --with-tls.

You'll also need to change the init script: in /etc/init.d/slapd, change the line that says start-stop-daemon --start --quiet --pidfile "$pf" --exec /usr/sbin/slapd to read start-stop-daemon --start --quiet --pidfile "$pf" --exec /usr/sbin/slapd -- -h "ldaps:/// ldap:///". This starts slapd(8)? listening on the ldaps and ldap Ports. You can also use ldapi to use LDAP over a Unix domain socket.

Debian Sarge

The package that comes with Sarge has TLS support enabled. Instead of hacking up the init script, edit /etc/default/slapd and change the SLAPD_SERVICES variable to suit your site, eg
SLAPD_SERVICES="ldap:// ldaps:///"

The example above will cause slapd(8)? to listen on the ldap port only on the localhost interface, and on the ldaps port on any interface.

RedHat 7.x

RedHat 7.x supports TLS out of the box. All you have to do is recreate your slapd(8)? certificate and uncomment the TLS config lines in /etc/openldap/slapd.conf.

cd /usr/share/ssl/certs
make slapd.pem
... answer some questions ...

Remember our advice about the Common Name here.

Use the following commands to set the permissions correctly for RH 7.x:

chmod u=rw,g=r,o= slapd.pem
chown root.ldap slapd.pem

LDAP Client Authentication

See LDAPAuthentication for a detailed example for having user accounts in LDAP.


After configuring LDAP client authentication, you probably want to enable nscd(8) to load at boot (in runlevels 2, 3, 4, & 5). nscd(8) is a dæmon which keeps a cache of looked up passwords and groups for running programs, so that your LDAP (or NIS) server won't get hammered. It also increases clients responvity.

HTTP authentication in Apache

First, enable apache's LDAP authentication module (which should be distributed with apache2 in recent distributions), which is called authnz_ldap. (Debian-based distros: run a2enmod authnz_ldap)

The following assumes you are only doing this on SSL-enabled sites or on a LAN so that packet sniffing isn't a security concern:

        <Location /ldap.html>
                AuthName "test ldap auth"
                AuthType Basic
                # the following will check against the uid attribute
                AuthLDAPURL ldap://ldapserver.hostname/ou=People,dc=yourdomain,dc=com?uid
                # our ldap server allows anonymous binds, so don't need these:
                # AuthLDAPBindDN
                # AuthLDAPBindPassword

                # choose a method of access:
                # 1) TO LIMIT ACCESS TO A SET OF USERS:
                #Require ldap-user user1 user2 user3

                # use ldap instead of default "file"
                AuthBasicProvider ldap
                # allow AuthBasic to work
                AuthzLDAPAuthoritative off
                # valid-user is an AuthBasic directive...
                Require valid-user

                ## which ldap attribute do we use (defaults to uniqueMember)
                ## posixGroup objectClass uses the memberUid attribute:
                #AuthLDAPGroupAttribute memberUid
                #AuthLDAPGroupAttributeIsDN off
                #Require ldap-group cn=admins,ou=Group,dc=yourdomain,dc=com

Traps and Trip-ups

There are a few things to get tripped up on with LDAP.

Make sure you have the same hostnames in your server's SSL cert Common Name and TLS client configurations. Also make sure the permissions on the cert file (slapd.pem) are correct (see above).
In /etc/ldap.conf (pam_ldap's config file), make sure you spell the root user's (aka Manager) DN correctly. This sounds stupid but it's an easy one to miss.
Make sure authconfig hasn't bollocked your pam config.
LDAP lookups fail for non-root users
Your config files are probably not readable. Make sure /etc/nss-ldap.conf is readable by non-root users.
slapcat(8)? works for root, but ldapsearch(1) shows absolutely no entries

Perhaps the permissions on your database files disallow slapd(8)? from reading them (you'd think OpenLDAP would give an error in this case, but noooo...)

There's also the possibility that you forgot to edit /etc/ldap/ldap.conf (in Debian Sarge at least) to define the BASE and URI settings.

You should also try ldapsearch(1), passing the -h <hostname> and -b <base dn> too!

no structuralObjectClass operational attribute
This seems to occur in range of configurations, including having replication set up. Disabling replication has been reported to fix this, however that's not an optimal solution. The error probably occurs because the data in your tree isn't consistent. You should make sure schemacheck is turned on and try reimporting your database from an LDIF, fixing errors as you go.
ldap_sasl_bind_interactive_s No such attribute
You're trying to use SASL but isn't configured properly. Try ldapsearch -x, if this works, then you have SASL issues. The usual solution is to always use -x.

Using the special rootdn and rootpw values

OpenLDAP has a special root account that has root access to the LDAP tree, bypassing any ACLs that you have in place. This account is controlled through the rootdn and rootpw attributes in slapd.conf.

rootpw must be initialised from the output of the slappasswd command. This isn't immediately obvious from any of the documentation and trying to bind as the rootdn will fail silently if you initialise it with a plaintext value.

Neat and Useful Programs

Useful apps for your LDAP system

Contact management tools

  • directoryassistant - A small (and improvable) LDAP address book manager
  • turba - The contact manager from the Horde project
  • Many Email clients. In particular Evolution 2 should be able to search, edit and insert new contacts in the LDAP addressbook

Patches for LDAP support


See Also

Part of CategoryNotes and CategorySystemAdministration