Configuring an OpenLDAP Server

The first step in using LDAP as a distributed login database is to get the server software running. This process entails obtaining and installing the software, setting it up to handle your domain, setting encryption options, and running the server. The Section 8.3 will show you how to create a directory that contains all your site’s user accounts.

Obtaining and Installing OpenLDAP

OpenLDAP’s official home page is http://www.openldap.org. You can obtain the OpenLDAP source code from this site, but the OpenLDAP site doesn’t host any precompiled binaries. Fortunately, most major Linux distributions provide such binaries, usually under the name openldap or openldap2 (the current OpenLDAP major version number is 2, hence that digit at the end of some OpenLDAP package names). Because most Linux distributions ship with OpenLDAP packages, the assumption in this chapter is that you’re installing the server in this way. If you compile the server from source code, you may need to adjust some filesystem directory paths in the coming descriptions because OpenLDAP installs in /usr/local by default, compared to /usr for most precompiled Linux OpenLDAP binaries.

Whether you install a binary package or compile OpenLDAP from source code, you may need to install several dependencies. These programs are either required for proper OpenLDAP functioning or are optional tools that OpenLDAP can use to provide improved security or other features:

SSL and TLS: The Secure Sockets Layer and Transport Layer Security are cryptography tools. They’re used to encrypt connections between two computers on a network—a useful feature for a network authentication system. In Linux, OpenSSL (http://www.openssl.org) is the most common implementation of both protocols.
SASL: The Simple Authentication and Security Layer is a tool for mediating between applications and authentication systems. It’s optional if you compile OpenLDAP from source code, but your distribution’s binary packages may require it. The main reasons to include it are if you want to enable Kerberos authentication with OpenLDAP or if you want to use other SASL-enabled applications, such as SASL-enabled SMTP or IMAP mail servers. Check http://asg.web.cmu.edu/sasl/ for more information on SASL.
Kerberos: This tool, described in more detail in Chapter 9, is an encryption and remote login tool. It’s possible to integrate Kerberos with LDAP authentication (in fact, that’s what Microsoft’s AD does), but such integration isn’t necessary. However, binary OpenLDAP distributions may require that you install a Kerberos package as a dependency.
Database backends: LDAP is primarily a tool for computer-to-computer communication. To do any good, though, LDAP requires data to be stored on the server, and OpenLDAP relies on a database backend to do this job. Several database backends are supported, but the most common is the Berkeley DB package (http://www.sleepycat.com). Most Linux distributions provide this software in a package called db.

In addition to these packages, binary distributions are likely to have more mundane dependencies, such as a requirement that glibc be installed. If you’re using a tool such as the Advanced Package Tool’s (APT’s) apt-get (used mainly with Debian but also available for many RPM-based distributions) or Gentoo’s emerge, dependencies should be installed automatically when you install OpenLDAP. If you use a lower-level tool such as rpm or dpkg, however, you may see errors about missing dependencies. To correct them, you need to locate and install the dependencies.

The OpenLDAP package contains several programs. Only one is the actual server program; others are support tools of various types, including:

slapd: This program is the main LDAP server.
slurpd: This server, which helps synchronize LDAP directories on multiple computers, is an advanced LDAP feature that’s beyond the scope of this book.
ldapadd: This program adds entries to an LDAP directory. Normally, you pass it an LDIF file containing one or more account entries, as described in the later Section 8.3.3.
ldapmodify: This program modifies entries in an LDAP directory.
ldapdelete: This program deletes entries from an LDAP directory.
ldapsearch: This program searches an LDAP directory for entries that match criteria you specify.
ldapcompare: This program compares entries in an LDAP directory using criteria you specify.
ldappasswd: This program changes the password attribute in an LDAP entry. It’s similar to the standard Linux passwd command.
ldapwhoami: This program reports your identity as passed to the LDAP server. It can be a useful diagnostic tool when you can’t seem to obtain the results you expect.
slapadd: This local program adds entries to an LDAP directory, using an LDIF original file as input.
slapcat: This local program displays entries in an LDAP directory, displaying them as LDIF files.
slapindex: This local program creates an LDIF index file from the current LDAP directory.
slappasswd: This utility generates a password suitable for inclusion in an LDIF file and subsequent addition to an LDAP directory via slapadd.

You needn’t be too concerned about the details of how these programs work just yet. The upcoming pages describe how to use some of them to help create and maintain your OpenLDAP server and an account directory for it. For more information, consult these programs’ manpages. One point to note, though, is that the utilities whose names begin with slap operate on the directory that’s housed on the local computer; that is, they must be run from the OpenLDAP server computer. The programs whose names begin with ldap, by contrast, are network tools; you can run them on the OpenLDAP server or any of its clients, provided they’ve been properly configured to refer to the LDAP server.

Basic OpenLDAP Configuration

OpenLDAP’s main server configuration file is slapd.conf . It usually resides in /etc/openldap, but it might appear in another location, particularly if you compile from source.

Tip

LDAP client tools, including programs like ldapmodify and ldapsearch, use the ldap.conf file rather than slapd.conf. This file is described in more detail in Section 8.3.4.

The slapd.conf file is a typical Linux text-mode configuration file. Hash marks (#) denote comments; lines beginning with this character are ignored. Parameters are identified by name with one or more values following them; equal signs are not used. One unusual feature of the slapd.conf format is that a line that begins with a space is interpreted as a continuation of the preceding line. This convention is used instead of the more common backslash (\) at the end of the first line to denote a line continuation.

The slapd.conf file begins with a series of lines that specify the server’s overall performance—what schemas it uses, where it stores its PID number, and so on. Following this global configuration are one or more sections, each beginning with the keyword database, that define directories. Each database section continues until the next database section or until the end of the file. These sections include options that specify the backend database type (the database directive itself does this, in fact), where the database is to be stored, the root of the directory tree, and so on.

Consider Example 8-1. This listing is a complete (if simple) slapd.conf file that’s suitable for handling an LDAP server that functions solely as a remote authentication system.

Example 8-1. A Sample slapd.conf file

####
# Global section

# Load schemas for storing user accounts
include /etc/openldap/schema/core.schema
include /etc/openldap/schema/cosine.schema
include /etc/openldap/schema/nis.schema

# Logging options
loglevel 296
pidfile  /var/run/slapd/slapd.pid
argsfile /var/run/slapd/slapd.args

# TLS options
TLSCipherSuite        HIGH
TLSCertificateFile    /etc/openldap/ssl/slapd-cert.crt
TLSCertificateKeyFile /etc/openldap/ssl/slapd-key.pem

# Set high security
security ssf=128

# Miscellaneous security options
password-hash {SSHA}

# Default access level
defaultaccess search

####
# Database section

database bdb

# The root suffix for the directory
suffix "dc=pangaea,dc=edu"

# The root DN for administration
rootdn "cn=Manager,dc=pangaea,dc=edu"

# The password used for administrative access
rootpw {SSHA}vHVUhjRetxArbQCTPOhyXC1a0s9z3Ej1

# Linux directory housing database files
directory /var/lib/ldap/

# Ensure that files may be read ONLY by their owner
mode 0600

## ACLs to control access to the directory

# Allow users to authenticate against and modify their own
# passwords
access to attrs=userPassword
  by self write
  by * auth

# Allow users to read all non-password data
access to *
  by * read

Of course, Example 8-1 is only a starting point; you’ll need to customize several of its entries for your system. The meanings of these options are:

Loading schemas: The first few lines of Example 8-1 load three schema files: core.schema, cosine.schema, and nis.schema. The last of these is the critical one, but it depends on the first two. The nis.schema schema provides a framework for handling all the data an NIS server normally manages. Because this includes Unix-style account information, it’s a common choice for implementing an authentication server. These schema files ship with OpenLDAP, but their location may not be as shown in Example 8-1 on your system; adjust the directory paths as required.
Logging options: The loglevel line sets logging options. These are set using bit flags converted to decimal notation. A value of 296 is reasonable for most production systems. This value logs information on connection statistics, filter processing, and connection management. (Consult the slapd.conf manpage for details.) The pidfile and argsfile options specify files in which slapd stores its PID and the arguments with which it was run. If your OpenLDAP binary includes a sample configuration file that sets these values in a particular way, you should probably leave them as such; it’s possible that your SysV startup scripts or other tools rely on this location.
TLS options: The next three options set TLS features; the assumption in Example 8-1 is that the server will use TLS or SSL encryption, which is a reasonable configuration in most cases. (If you want to use another encryption system, you’ll have to consult OpenLDAP’s documentation.) As with other Linux directory paths, you may need to adjust the path shown in Example 8-1 for your system. Preparing the TLS certificates is described in the next section.
Security level: The security keyword sets security options. Example 8-1 sets security ssf=128, which sets the server’s overall security strength factor (SSF) to 128—a code that stands for a class of encryption algorithms that includes Blowfish, RC4, and others that are fairly strong. If you must use less robust encryption algorithms, you can change 128 to 112 or 56. A value of 0 disables the encryption requirement.
Password hashing: The password-hash option specifies how OpenLDAP hashes passwords it stores. {SSHA} means that OpenLDAP uses the Salted Secure Hash Algorithm (SSHA), which is the preferred means of storing passwords on an LDAP server. Other possible values include {CRYPT} (the method used by the system crypt( ) call), {MD5} (the Message Digest 5 system, which is often used in /etc/passwd or /etc/shadow files), {SHA} (a less-secure variant of SSHA), and {CLEARTEXT} (no encryption). Of these, {CLEARTEXT} is the least secure and should be avoided. Note that individual users’ passwords may be stored using any method; the password-hash option only sets the default.
The database definition: The database bdb line begins the one and only database definition in Example 8-1. This line tells OpenLDAP to use the Berkeley DB (hence, bdb) system for its backend. Other possible backend codes are ldbm (an older variant of bdb that can be handled by the BerkeleyDB software or the GNU Database Manager), passwd (a quick-and-dirty interface to your existing /etc/passwd file), and shell (an interface to other database tools).
The root suffix: The suffix line specifies the DN for the directory. In most cases, this root suffix is built from your network’s domain name. In the case of Example 8-1, OpenLDAP is configured to manage passwords for the http://www.pangaea.edu domain.
The administrative DN: You can specify a root DN for administration with the rootdn parameter. This DN is built from the root suffix’s DN by adding a cn value, typically Manager (as in Example 8-1) or admin. This line and the following rootpw entry are useful mainly for initial OpenLDAP configuration; once the system is working, you may want to remove them to improve the server’s security.
The administrative password: The rootpw line sets an administrative password that’s associated with the rootdn item. You can generate a password with the slappasswd command; type it and enter a password twice, then paste it into the file in place of the password shown in Example 8-1. The password you generate should begin with {SSHA} (or possibly some other value in curly braces); replace everything from {SSHA} on with the output of slappasswd from your system.
The Linux database directory: The directory line refers to a Linux filesystem directory, not an LDAP directory; it’s the location of the database files maintained by the database system specified by the preceding database line. This directory must be specified as an absolute path. You may need to adjust this option for your system.
The database mode: The mode line specifies a Linux file mode for the database files. Normally, 0600 is appropriate: it prevents unauthorized snooping or modifications.
ACLs: Access Control Lists specify who may access particular types of data in the directory and in what way. They’re conceptually similar to filesystem ACLs, but the details differ. The last few lines of Example 8-1 define two ACLs, each of which begins with the keyword access. The first of these sets accesses conditions to the userPassword attribute: users may modify their own passwords (by self write), and all users may access this attribute for authentication (by * auth). The second ACL gives all users read access to all other attributes. ACLs are applied in order, with the earlier ACLs taking precedence over the later ones. In the case of Example 8-1, the more restrictive ACL for the userPassword attribute must precede the read-only ACL for other attributes, lest users be granted the ability to read each other’s passwords.

Once you’ve tweaked Example 8-1 for your system, OpenLDAP is basically configured. You must still prepare the TLS certificates, though. Once that’s done, you can start the slapd server.

Preparing Keys and Certificates

Although it’s possible to run an LDAP server without using encryption, doing so is inadvisable, at least when the LDAP server is functioning as a network authentication tool. Encryption keeps your passwords secure; without it, passwords will be sent over the network in cleartext, which makes them susceptible to sniffing.

Tip

Use of SASL generally includes its own encryption mechanism, so if you use SASL, preparing encryption as described here isn’t necessary. This chapter doesn’t cover LDAP’s SASL capabilities, though.

In Example 8-1, the three lines under the TLS options comment set options related to SSL and TLS encryption, enabling OpenLDAP to engage in encrypted communications. In order for this configuration to work, though, you must first configure the TLS and SSL encryption tool, which is provided by the OpenSSL package (http://www.openssl.org). This package should be a dependency of any binary OpenLDAP package that can use SSL or TLS encryption, and it’s also required to compile OpenLDAP with support for these methods of encryption. (If you compile OpenLDAP yourself, you may need to install a separate OpenSSL development package.)

Tip

As described in Section 8.2.1, LDAP supports encryption methods other than SSL and TLS. In order to keep this chapter manageable, though, and because SSL and TLS are popular and well-respected encryption tools for LDAP, they’re the only ones described here.

SSL and TLS support a set of encryption tools, some of which require one-time manual preparation before they can be used. Most notable among these are keys and certificates . A key is a numeric code that can encrypt or decrypt data. Once data is encrypted with a key, it can only be decrypted with a matching key. Keys can be generated fairly automatically, but certificates require at least minimal input from users. They’re designed to authenticate a site’s identity and are essentially files with information on the owner of a server, signed and encrypted with a key that the other system trusts. One type of certificate is created by Certificate Authorities (CAs), which are organizations founded to create certificates for the sake of e-commerce and the like. web sites that use encrypted transmissions usually employ certificates created for them by CAs; web browsers can then decrypt the certificates sent by web sites and verify that they were signed by a trusted CA. If a certificate’s signature doesn’t check out, the web browser notifies the user that the site might not be trustworthy.

For in-house use, though, you don’t need to go to a CA; you can create a certificate yourself. The OpenSSL package includes the tools necessary to do so. The simplest and most direct way is to call openssl with a series of options that cause it to generate a certificate and a key:

# openssl req -x509 -days 365 -newkey rsa: -nodes \
                   -keyout slapd-key.pem -out slapd-cert.crt
Generating a 1024 bit RSA private key
..........................++++++
.....++++++
writing new private key to 'server.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:RI
Locality Name (eg, city) [  ]:Woonsocket
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Very Old University
Organizational Unit Name (eg, section) [  ]:CS Dept
Common Name (eg, YOUR name) [  ]:ldap.pangaea.edu
Email Address [  ]:johndoe@pangaea.edu

Of course, you should customize the information in the certificate to describe your organization. Pay particular attention to the data you enter at the Common Name (eg, YOUR name) prompt; some clients, including the Windows LDAP authentication client, require this to match the hostname or IP address of the LDAP server. The result of running this command is two files: slapd-key.pem and slapd-cert.crt . These files contain a private key and a public certificate, respectively. Be sure that the private key can be read only by its owner; 600 (rw-------) permissions are appropriate, so type chmod 600 slapd-key.pem to set this file mode. (Some other OpenLDAP files, such as slapd.conf, should be readable to all users, though.) Ordinarily, slapd runs as a specific user (such as ldap, although this username varies from one distribution to another), so you should give ownership of the file to that user. If you run into problems launching the server you should check to see what user is running the server and adjust ownership of this file accordingly. You should now move the sldapd-key.pem and slapd-cert.crt files to the location specified by the TLSCertificateKeyFile and TLSCertificateFile parameters in slapd.conf—/etc/openldap/ssl in Example 8-1.

Running the Server

At this point, it’s time to run the server. You can run slapd on a one-time basis by typing the server’s filename (you may need to include the full path) or by using a SysV startup script. For instance, on a SuSE system, the SysV startup script is /etc/init.d/ldap, so the following command does the trick:

# /etc/init.d/ldap start

As you test the server, you’re likely to start and stop it frequently. Once it’s running the way you want it to run, you’ll probably want to configure your system to launch slapd at startup. You can do this as you would any other server that runs constantly. (Typically, slapd is run from a SysV or local startup script, not from a super server.) Typing chkconfig ldap on will do this on many systems, but some distributions use other commands instead of or in addition to chkconfig. Consult distribution-specific documentation if you need help with this task.

One problem you may encounter is getting the server to bind to appropriate ports, particularly if you intend to use SSL encryption. By default, slapd binds to port 389, which is used for cleartext connections and those that negotiate TLS encryption after making an initial connection. Some clients, though, including the pGina tool that’s described in Section 8.5, must use a dedicated SSL LDAP (that is, LDAPS) encryption port, 636. To force slapd to bind to this port, you must pass an appropriate parameter to the server with the -h option. Passing -h ldap:/// causes slapd to bind to port 389 only, whereas passing -h ldap:/// ldaps:/// causes it to bind to both ports 389 and 636. You may need to modify your slapd SysV startup script to add this option. Some SysV startup scripts, such as the one for SuSE Linux, include a variable in which you can pass these options; in the SuSE script, you edit the SLAPD_URLS variable to include ldaps:///.

Previous Chapter

8. Using LDAP

Next Chapter

Creating a User Directory