Centralized authentication using OpenLDAP

This guide Article description::introduces the basics of LDAP and shows readers how to setup OpenLDAP for authentication purposes between a group of computers.

What is LDAP?
LDAP stands for Lightweight Directory Access Protocol. Based on X.500 it encompasses most of its primary functions, but lacks the more esoteric functions that X.500 has. Now what is this X.500 and why is there an LDAP?

X.500 is a model for Directory Services in the OSI concept. It contains namespace definitions and the protocols for querying and updating the directory. However, X.500 has been found to be overkill in many situations. Enter LDAP. Like X.500 it provides a data/namespace model for the directory and a protocol. However, LDAP is designed to run directly over the TCP/IP stack. See LDAP as a slim-down version of X.500.

What is a directory?
A directory is a specialized database designed for frequent queries but infrequent updates. Unlike general databases they don't contain transaction support or roll-back functionality. Directories are easily replicated to increase availability and reliability. When directories are replicated, temporary inconsistencies are allowed as long as they get synchronised eventually.

How is information structured?
All information inside a directory is structured hierarchically. Even more, to enter data inside a directory, the directory must know how to store this data inside a tree. Let's take a look at a fictional company and an Internet-like tree:

Since data is not fed to the database in this ASCII-art like manner, every node of such a tree must be defined. To name such nodes, LDAP uses a naming scheme. Most LDAP distributions (including OpenLDAP) already contain quite a number of predefined (and general approved) schemas, such as the inetOrgPerson, or a frequently used schema to define users which Unix/Linux boxes can use, called posixAccount. Note there are GUI web based tools to make managing LDAP painless: see Working with OpenLDAP for an non-exhaustive list.

Interested users are encouraged to read the OpenLDAP Admin Guide.

What can it be used for?
LDAP can be used for various things. This document focuses on centralised user management, keeping all user accounts in a single LDAP location (which doesn't mean that it's housed on a single server, LDAP supports high availability and redundancy), yet other goals can be achieved using LDAP as well.


 * Public Key Infrastructure


 * Shared Calendar


 * Shared Addressbook


 * Storage for DHCP, DNS, ...


 * System Class Configuration Directives (keeping track of several server configurations)


 * Centralised Authentication (PosixAccount)



Common notes
The domain genfic.org is an example in this guide. The domain can be renamed as suitable to the readers. However, make sure that the top node is an official top level domain (.net, .com, .cc, .be, etc.). Since LDAP does not provide encryption in transfer it is necessary to create TLS server certificates. It is common practice to relate server DNS, certificate CN and LDAP CN. For this example the server will be reachable by ldap.genfic.org only over ldaps://. The server certificate will be for exactly this host thus CN=ldap.genfic.org. For TLS see Certificates and Certificates/Become your own CA.

Let's first emerge OpenLDAP. Ensure the USE flags,   (disabled) and   are used.

OpenLDAP supports two authentication mechanisms:


 * 1) Standard user-password (in LDAP terms user means binddn) named SIMPLE.
 * 2) Proxying authentication requests to SASL (Simple Authentication and Security Layer, see RFC4422 for details).

Although the OpenLDAP default is to use SASL, the initial version of this article used only password-based authentication. With the OLC add-on the article starts to describe the use of the simplest SASL mechanism called EXTERNAL, which relies on the system authentication. This is only limited to the host the server runs on.

OpenLDAP has a main user called "rootdn" (Root Distinguished Name), which is hard coded in the application. Unlike the classic Unix root user, the rootdn user still needs to be assigned with proper permissions. The rootdn user may be used only in the context of the configuration, but it can also be used in the directory definition. In that case a user can authenticate himself as rootdn with either the configuration used password and the tree (directory-based) password.

User passwords (regardless if it is for rootdn users or others) for verification purposes can be stored as clear text or hashed. Multiple different hash algorithms are available, but usage of weak algorithms (up to MD5) is not recommended. SHA is currently considered sufficiently cryptographically secure.

In the below command, a hashed value is created for a given password; the result of this command can be used in the configuration file, or in the internal directory definition of a user:

Legacy configuration (flat config slapd.conf)
Now edit the LDAP Server configuration in. The provided is from the original OpenLDAP source. Below is a sample configuration file one can use to replace it with to get things started.

For a more detailed analysis of the configuration file see the OpenLDAP Administrator's Guide found on the upstream project's documentation page, although reading may be enough.

If it does not start, the first step is to check the configuration file:

Vary the debug level (the  above) for more info. If all goes well a config file testing succeeded will be displayed. If there's an error, will list the line number to which it applies (of the  file).

By default writes the log events to the local4 syslog facility.

Migration from slapd.conf to OLC
To be able to change OpenLDAP server's configuration, define at least  (or normally  ) access to.

The example below shows how to grant manage access on OLC (cn=config database) to the system administrator (root user) by adding the proper lines at the end of the file:

Then, invoke the utility with the   and   options to convert the  file into a configuration directory.

Running this command will transfer and translate the configuration. After that you are expected to update the configuration using specially prepared ldif files. And only if you aren't enough familiar with them, you can first edit and after that re-translate the  into. Don't forget to check the directory's permissions.

For more instructions read the in-line comments of the generated files.

The below line will enable the configuration method.

Finally, create the structure:

Initial setup with OLC
An initial configuration is shipped as a standard LDAP database dump, available as or.

This initial configuration can be loaded (and only loaded, unlike ordinary LDAP databases) by the utility:

When using a root account, be sure to correct ownership of the files created by root, as described below in migrate section.

For the right to change the configuration database, proper permissions must be provided. The next example shows how these privileges are granted to the system user:

See for more details.

When using OLC, never manually edit the configuration files. The directory files can be used to check the consistency of the configuration through:

Maintaining the directory
Start  now that the configuration steps have been completed:

Most users will also want the OpenLDAP daemon to start automatically:

It is now possible to use the directory server to authenticate users in apache/proftpd/qmail/samba.

The directory server can be managed with tools such as, and  from the Gentoo ebuild repository, or  from the poly-c overlay available through Layman or eselect repository.

Server management with OLC
Some examples of updates on the OLC-style configuration are mentioned below.

For instance, to change the location of the OLC configuration directory (needed after switching from a config file to config directory style):

To change the log level used by the OpenLDAP instance:

In order to apply the changes, run the following command:

OpenLDAP logging
OpenLDAP produces numerous log events, which might not be obvious to interpret, but are necessary for debugging purposes.

As OpenLDAP by default writes the log events into the system log, it is advisable to reconfigure the system logger to direct OpenLDAP log events into a dedicated log file.

It is advisable to use the  log level in OpenLDAP standalone server and   in OpenLDAP cluster. In such case query results logs session-related information such as the following:

Most common errors in server log are :

Which means «invalid credentials» (i.e. wrong password).

And :

Which means «No such object». Usually this error appears when binddn (user) has no permissions on requested object. So either try to do something wrong, or there is a mistake in the set ACLs.

Access management (ACLs)
The authorizations and access control mechanism used in OpenLDAP is described in the manual page. Its base syntax is as follows:

The following table shows the access levels available in OpenLDAP:

For details about the exact privilege settings, see the manual pages and official OpenLDAP documentation.

Config file
ACLs are parsed in the order they are set in the configuration, and are applied based on the specificity (meaning that, when an ACL rule is considered, the remainder of ACL rules is no longer checked). As such, more specific definitions should go first, before more generic ones are listed. For more information, see Access Control Evaluation.

For example:

Config directory
ACLs are parsed in the order they are set in the configuration, and are applied based on the specificity (meaning that, when an ACL rule is considered, the remainder of ACL rules is no longer checked). As such, more specific definitions should go first, before more generic ones are listed. This order, when using OLC, is handled through the  directives.

For example:

The following example inserts a new ACL on top, making the existing  entries to shift by one:

To delete an ACL:

High availability
A common high availability setup with OpenLDAP is to use replication of changes across multiple LDAP systems.

Replication within OpenLDAP is, in this guide, set up using a specific replication account which has read rights on the primary LDAP server and which pulls in changes from the primary LDAP server to the secondary.

This setup is then mirrored, allowing the secondary LDAP server to act as a primary. Thanks to OpenLDAP's internal structure, changes are not re-applied if they are already in the LDAP structure.

Setting up replication
To setup replication, first setup a second OpenLDAP server, similarly as above. However take care that, in the configuration file:


 * The sync replication provider is pointing to the other system


 * The serverID of each OpenLDAP system is different

Synchronisation account
Next, create the synchronisation account. We will create an LDIF file (the format used as data input for LDAP servers) and add it to each LDAP server:

Enabling syncprov overlay
Overlay can be linked statically and dynamically. When it is built dynamically, you'll need to load module. For now in Gentoo it's usually built statically. To ensure type:

Load syncprov module (optional)
To load syncprov module, use the following ldif file:

Setting up replication for database
Next step, mandatory for everybody, is to setup replication for database (must be done on both nodes):

Final configuration
Finally, add replication's definition.

On node 1:

traditionally means the password string.

On node 2:

The only difference is in server's ident (rid) and provider uri.

If LDAP master (mirror node with initially loaded database) is unavailable (slapd daemon not started, or 389/tcp port is blocked by a packet filter) slapd daemon on secondary node fails to start with the following error message:

Almost certainly the database will not fit into default limits. So, you will need to increase 's limits. For example:

Performance tuning
Default daemon settings significantly limits LDAP server performance.

Symptoms
When server load fits system limit client applications fails with different kind of timeout errors.

In server log this produces error messages like following:

Increasing OS limits
First, read system user limits:

The first parameter, you need to increase, is the open files limit.

Maximum available value is described in Documentation/sysctl/fs.txt file of kernel documentation:

PAM system limits are stored in /etc/security/limits.conf file or, optionally, in /etc/security/limits.d/ directory. Daemons, started with init system use these parameters (see  for details), so you need just to put in the file:

And restart daemon.

The next limitation is 's  parameter.

During run time, this value can be updated via:

After verifying new value do not forget to fix it:

And, possibly, some other application-specific parameters.

Configuring the OpenLDAP client tools
Edit the LDAP Client configuration file. This file is read by ldapsearch and other ldap command line tools.

Test the running server with the following command:

If errors are received, try adding  to increase the verbosity and solve the issue.

Client configuration for centralized authentication
There are numerous methods/tools that can be used for remote authentication. Some distributions also have their own easy to use configuration tool. Below there are some in no particular order. It is possible to combine local users and centrally authorized accounts at the same time. This is important because, for instance, if the LDAP server cannot be accessed one can still login as root.


 * SSSD (Single Sign-on Services Daemon). Its primary function is to provide access to identity and authentication remote resource through a common framework that can provide caching and offline support to the system. It provides PAM and NSS modules, and in the future will support D-Bus interfaces for extended user information. It also provides a better database to store local users as well as extended user data.


 * Use  to login to the LDAP server and authenticate. Passwords are not sent over the network in clear text.


 * NSLCD (Name Service Look up Daemon). Similar to SSSD, but older.


 * NSS (Name Service Switch) using the traditional  module to fetch password hashes over the network. To permit users to update their password this has to be combined with the   method.

The first two are demonstrated below with the minimum necessary configuration options to get working.

Client PAM configuration SSSD Method
Here is the more direct method. The three files that are required to be edited are mentioned below.

Add sss to the end as shown below to enable the lookup to be handed to the sssd system service. Once you have finished editing start the sssd daemon.

The last file is the most critical. Open an extra root terminal as a fallback before editing this. The lines that end with  have been added to enable remote authentication. Note the use of to support creating the user home directories.

Now try logging in from another box.

Client PAM configuration the pam_ldap module method
Before starting any change to the client side authentication configuration, make sure that the LDAP server can be reached and presents the correct information. The following steps assume a user Bert Ram was created in the LDAP with login name bertram. Exchange accordingly with a user from the LDAP instance. Use the manager role with caution. But at least check with the LDAP read user role and a user that will logon to the client(s) to be configured:

First, configure PAM to allow LDAP authorization. Install so that PAM supports LDAP authorization. Then edit and include the relevant lines so that local login is checked first. This gives safety with at least a local root login and a local user – created during Gentoo installation. Third must be edited to check LDAP in addition to local database and files option. Finally check login on one of the terminals before restarting the client/ logging out root and/ or current user.

Backup this file first. Copy to a safe place (outside ) in case you made changes. Make the copy read only, e.g. . Insert one statement for pam_ldap.so in each of the blocks for auth, account, password and session.

In each line for passwd, group, shadow and initgroups needs to be prepended with ldap:

Now change. It should contain


 * URI to contact LDAP server, use TLS/ ldaps:// by any means, otherwise passwords are transferred unencrypted
 * Base (general) to lookup DNs
 * Bind-DN (and secret) since anonymous binds are bad
 * Base per group, passwd and/ or shadow in case your LDAP tree deviates from defaults (as mentioned in the file's comments)
 * optional client certificates if you use mutual TLS
 * mapping for group membership to memberUid if you use primary group with additional groups expressed by membership

This is just a note and needs distinction between systemd and OpenRC, start nlscd:

If the daemon started successfully, change to one of the console terminals. Return to the graphical session by pressing. Switch to one of the 6 login consoles by pressing. At the login prompt, try user bertram.

Convert file userbase to LDAP
Configuring OpenLDAP for centralized administration and management of common Linux/Unix items isn't easy, but thanks to some tools and scripts available on the Internet, migrating a system from a single-system administrative point-of-view towards an OpenLDAP-based, centralized managed system isn't hard either.

Go to https://www.padl.com/OSS/MigrationTools.html and fetch the scripts there. You'll need the migration tools and the script.

Next, extract the tools and copy the script inside the extracted location:

The next step now is to migrate the information of the system to OpenLDAP. The script will do this, after it has been provided with the information regarding the LDAP structure and environment.

At the time of writing, the tools require the following input:

The tool will also ask which accounts and settings to migrate.

Emerge errors after conversion to LDAP
If for any reasons local user accounts (i.e. /etc/passwd /etc/shadow) or groups (i.e. /etc/group) are deleted after converting the file userbase to LDAP, errors may be encountered relating to missing user (or group) while emerging certain packages.

Example of error while emerging due to missing "apache" local user account: Installing build system files make[1]: Leaving directory '/var/tmp/portage/www-servers/apache-2.4.41/work/httpd-2.4.41'              [ ok ] chown: invalid user: ?apache:apache? * ERROR: www-servers/apache-2.4.41::gentoo failed (install phase): *  fowners failed In such cases, a workaround involves emerging the package using FEATURES=-network-sandbox. Doing so has potential security consequences so system users should remain in local files.

Acknowledgements
We would like to thank Matt Heler for lending us his box for the purpose of this guide. Thanks also go to the cool guys in on the Libera Chat IRC network.