Paranoid Penguin - Authenticate with LDAP

The directory server is running, so now it's time to configure crypto and add some users.

Last month, we did some of the preliminary work in setting up an OpenLDAP server. We installed the base, server and, where applicable, client packages for OpenLDAP, and we entered some basic configuration information into the file /etc/openldap/slapd.conf (slapd is OpenLDAP's server dæmon).

This month, we configure TLS encryption, start the dæmon and begin building an LDAP database. We won't have a finished authentication server yet, but we'll be pretty close. Next month, in this series' third and final installment, we'll get there.

TLS for Secure LDAP Transactions

By default, OpenLDAP transactions over networks are conducted in clear text. If you're using OpenLDAP, for example, as a centralized address book server on a trusted network, that's probably fine. But if you're using it to authenticate users, regardless of whether the networks involved are trusted, you really ought to encrypt your LDAP communications to protect your users' passwords from eavesdroppers.

The LDAP v.3 protocol, support for which was introduced in OpenLDAP 2.0, provides encryption in the form of Transport Layer Security (TLS), the same mechanism used by web browsers and mail transport agents. TLS is the successor to SSL, the Secure Sockets Layer. All you need to do to take advantage of this is create a server certificate on your LDAP server; add a couple more lines to /etc/openldap/slapd.conf, and optionally, tweak slapd's startup options.

To generate a server certificate, you need OpenSSL. This already should be present on your system, because binary OpenLDAP packages depend on OpenSSL.

What sort of certificate you should use as your LDAP certificate actually is a fairly subtle question. Will the server need a certificate that has been signed by some other certificate authority (CA), such as Thawte or VeriSign? That is, will your LDAP clients need to see an externally verifiable certificate when connecting to your server? Or, will your organization be its own CA? If so, will the LDAP server also act as your local CA, issuing and signing both its own and other hosts' and users' certificates?

If your needs match any of those scenarios, you'll need to do a bit more work than I'm able to describe here. Suffice it to say that the certificate slapd uses can't have a password associated with it—its key can't be DES-encrypted—so a self-signed certificate, though technically a CA certificate, shouldn't be used as an actual CA certificate for signing other certificates. If you want to use your LDAP server as a real CA, you'll need to create two keys, a password-protected CA key and a password-free slapd key. Vincent Danen's article “Using OpenLDAP for Authentication” ( discusses this.

For many if not most readers, it will be enough to create a self-generated TLS-only certificate to be used by slapd and slapd alone. If you don't care about being a CA and you don't need your LDAP clients to be able to verify the server certificate's authenticity via some third party, you can create your certificate like this:

bash-$> openssl req -new -x509 -nodes \
-out slapdcert.pem -keyout slapdkey.pem \
-days 365
Using configuration from /usr/share/ssl/openssl.cnf
Generating a 1024 bit RSA private key
writing new private key to 'slapdkey.pem'

On this command line I told OpenSSL to generate a new X.509 certificate, without password protection, with the certificate (public key) stored in the current working directory in the file slapdcert.pem, and the private key stored in the file slapdkey.pem, with a lifetime of 365 days,

After issuing this command, you will be prompted for distinguished name information for the new certificate and key. For OpenLDAP's purposes, the most important field here is the common name. This must be set to your LDAP server's DNS name, which is the name your LDAP clients will see associated with this certificate. If your LDAP server's IP address, for example, reverse resolves to but its server certificate shows a CN of, LDAP clients will reject the certificate and therefore will be unable to negotiate TLS connections (with unpredictable results, depending on your client software).

Once you've got certificate and key files, copy them into /etc/openldap if you weren't already in that directory when you created them. Make sure that both of these are owned by ldap or whatever user your Linux distribution runs slapd as, Red Hat and SuSE use ldap, and that your key file has very strict permissions, such as -r--------. Your certificate file may, however, be world-readable, because this contains a public key.

It's possible to specify the same filename after both the -out and -keyout options, resulting in both the certificate and private key being stored in a single file. This is fine if you don't intend to share the certificate. Keeping the two separate, however, allows you to distribute the server certificate while still keeping the server (private) key secret.

Naturally, it isn't enough to have certificate/key files in place; you need to tell slapd to use them. As with most slapd configuration, this happens in /etc/openldap/slapd.conf. Listing 1 shows the sample slapd.conf entries from last month's column (in case you've forgotten what we covered), plus three additional ones: TLSCipherSuite, TLSCertificateFile and TLSCertificateKeyFile.

TLSCipherSuite specifies a list of OpenSSL ciphers from which slapd will choose when negotiating TLS connections, in decreasing order of preference. To see which ciphers are supported by your local OpenSSL installation, issue this command:

openssl ciphers -v ALL

In addition to those specific ciphers, you can use any of the wild cards supported by OpenSSL, which allow you to specify multiple ciphers with a single word. For example, in Listing 1 TLSCipherSuite is set to HIGH:MEDIUM:+SSLv2; as it happens, HIGH, MEDIUM and +SSLv2 all are wild cards.

HIGH means “all ciphers using key lengths greater than 128 bits”; MEDIUM is short for “all ciphers using key lengths equal to 128 bits”, and +SSLv2 means “all ciphers specified in the SSL protocol, version 2, regardless of key strength”. For a complete explanation of OpenSSL ciphers, including all supported wild cards, see the ciphers(1) man page.

TLSCertificateFile and TLSCertificateKeyFile are more obvious. They specify the paths to your certificate file and private key file, respectively. If both certificate and key are combined in a single file, you can specify the same path for both parameters.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Nice tutorial...

Mike's picture

I wish you had published this a couple months ago before I started my expedition on making this work at my site. Most of the info is out there, Mick has done a great job filtering through and compiling it all in one place. I look forward to part 3!

One comment on the section titled "slapd Startup Options". I'm running OpenLDAP 2.2.13 on RHEL 4. When it came to locking down plaintext connections and enforcing TLS/LDAPS, I had to manually change the following line in /etc/init.d/ldap:

daemon ${slapd} -u ldap -h '"ldap:/// ldaps:///"' $OPTIONS $SLAPD_OPTIONS


daemon ${slapd} -u ldap -h '"ldap:// ldaps:///"' $OPTIONS $SLAPD_OPTIONS

Great tutorial

R07h3m's picture

Very good, clear and simple, thanks for this howto.

Re: Paranoid Penguin: Authenticate with LDAP

Anonymous's picture

Thank you Mick for excellent tutorials.....

In this tutorial when addding ldap data e.g.

dn: dc=wiremonkeys,dc=org
objectclass: top
objectclass: organization
o: Wiremonkeys of St. Paul

I had to add the following to be able to get the data into ldap:

dn: dc=wiremonkeys,dc=org
objectclass: top
objectclass: organization
objectclass: dcObject
o: Wiremonkeys of St. Paul
dc: wiremonkeys

I've commented only in that others may get the same errors I did... namely "attribute 'dc' not allowed" or "naming attribute 'dc' is not present in entry".

Thanks for the tutorial....