OpenLDAP is enterprise-level software with the great benefit of providing a central point for configuring credentials as well as managing an organisation. By default, OpenLDAP operates on nothing more than a tree structure allowing a manager or administrator to add any type of components: for instance, you can define users, you can define groups, you can define departments, sub-departments and even hardware and equipment if you so desire all with the extra benefit of providing a central point of authentication for various services that the organisation may be running.

This tutorial is rather Debian-centric because Debian provides a lot of the necessary software as packages without having to mess with compiling and manually installing packages although the rough install procedure should apply to any distribution.

On Debian, the required packages can be installed with:

aptitude install slapd libnss-ldapd ca-certificates

where:

• slapd is the standalone OpenLDAP daemon,
• libpam-ldapd and libnss-ldapd will help authentication through Linux PAM.
• ca-certificates are the root CA certificates required by SSL/TLS.

When slapd installs, it will ask for an administrator password - the requested password is not in any way related to the Linux root password but should be equally or if not more important since if other services will use OpenLDAP for authentication, then compromising the LDAP administration password could compromise the entire organization.

However, slapd on Debian will assume the entire local Top-Level Domain (TLD) as the single Domain Component (DC) and it is customary to also include the hostname of the machine running OpenLDAP.

Create the file /etc/ldap/ldap.conf with the following contents:

#
# LDAP Defaults
#

# See ldap.conf(5) for details
# This file should be world readable but not world writable.

BASE    dc=ldap,dc=home
URI     ldap://192.168.0.1

#SIZELIMIT      12
#TIMELIMIT      15
#DEREF          never

# TLS certificates (needed for GnuTLS)
TLS_CACERT      /etc/ssl/certs/ca-certificates.crt

This file assumes that:

• the FQDN hostname/domain name of the machine on the network will be ldap.home - where home is the TLD, in this case, a non-existing domain name with only the internal network as its scope.
• the current LDAP machine has the IP address 192.168.0.1.

Next, issue:

dpkg-reconfigure -plow slapd

and now perform the same configuration when you installed slapd whilst entering ldap.home or equivalent for the domain name and home for the organization.

If all steps have been performed correctly, you can issue:

slapcat

and at the very top you should see:

dn: dc=ldap,dc=home
objectClass: top
objectClass: dcObject
objectClass: organization
o: home
dc: ldap
structuralObjectClass: organization
...

dn: cn=admin,dc=ldap,dc=home
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator

which means that:

• the LDAP base is dc=ldap,dc=home,
• the administrator Distinguished Name (DN) is cn=admin,dc=ldap,dc=home (the Common Name (CN) of the administrator being admin).

The setup of a bare-bones LDAP server based on OpenLDAP is now complete.

Whilst terminal commands are available to configure the LDAP structure, it is convenient to have a graphical interface that can enumerate the contents of LDAP and to add new components without having to write text files. One such tool is phpLDAPAdmin which can be installed by issuing:

aptitude install phpldapadmin

phpLDAPAdmin now has to be configured by editing /etc/phpldapadmin/config.php. In order to tell phpLDAPAdmin where to find the LDAP server, the following configuration has to be made:

$servers->setValue('server','host','192.168.0.1');

Next, the LDAP base has to specified via the following setting:

$servers->setValue('server','base',array('dc=ldap,dc=home'));

Finally, the administrator DN has to be specified:

$servers->setValue('login','bind_id','cn=admin,dc=ldap,dc=home');

The file can now be saved and you can navigate to http://192.168.0.1/phpldapadmin in order to log-in and manage LDAP. phpLDAPAdmin will prompt for the administrator DN which, in this case, will be cn=admin,dc=ldap,dc=home and the password will be the one set when configuring the slapd package.

One of the cool features of LDAP is that LDAP can now be used as an authentication backend and many software packages have extensions that allow them to authenticate via an LDAP server. For instance, you may have a bunch of Linux machines to which a given set of users have access but you do not want to create local accounts for every user. In this case, Pluggable Authentication Modules (PAM) can be used to perform authentication against LDAP.

On Debian, issue:

aptitude install libpam-ldapd

to install the LDAP PAM module.

Debian will prompt to configure libpam-ldapd and the following parameters can be entered:

• the URI to your LDAP server (in this case, it would be ldap://192.168.0.1),
• the search base (in this case, it would be dc=ldap,dc=home)

and on the last screen when the configuration tool prompts to update /etc/nsswitch.conf select all the options (this step is not needed just for password authentication but the settings do not hurt regardless).

On Debian, a file must be created that will instruct PAM to add a module to its configuration that will create a home directory for new users that first log-in to the machine. This is necessary because users that are not created locally do not have a home directory by default. In order to add the module, create the file /usr/share/pam-configs/mkhomedir with the following contents:

Name: Create home directory during login
Default: yes
Priority: 0
Session-Interactive-Only: yes
Session-Type: Additional
Session-Final:
        optional        pam_mkhomedir.so

and issue:

pam-auth-update

Finally, issue:

dpkg-reconfigure nslcd

and specify:

• the URI to your LDAP server (in this case, it would be ldap://192.168.0.1),
• the search base (in this case, it would be dc=ldap,dc=home),
• chose simple for authentication,
• enter the administrator DN when prompted for an user to log-in to LDAP (in this case, the administrator DN is cn=admin,dc=ldap,dc=home).

followed the by the administrator password - no StartTLS is necessary.

nslcd scans the entire LDAP registry starting from the search base (dc=ldap,dc=home) and searches for users. It does not matter on what leaf of the tree they are found, nslcd will accept authenticating any defined users.

The next step is to create users:

• users can be created via phpLDAPAdmin installed in the previous sections
• install ldapscripts which are command-line utilities to facilitate managing users via LDAP.

To use ldapscripts, install them via:

aptitude install ldapscripts

Here is a short list of tools included in the ldapscripts package:

• ldapadduser - for adding an user, ex.: ldapadduser system users (add an user system with group name users),
• ldapsetpasswd - for changing the password of an user, ex.: ldapsetpasswd system (change the password for the user system),
• ldapdeleteuser - for deleting an user, ex.: ldapdeleteuser system (delete the user system),
• ldapaddgroup - for adding a group, ex.: ldapaddgroup users (add the group named users),
• ldapaddusertogroup - for adding an user to a group, ex.: ldapaddusertogroup system users (add the user system to group users),
• ldapdeleteuserfromgroup - for deleting an user from a group, ex.: ldapdeleteuserfromgroup system users.

There are more commands available, to see them all, issue:

apt-file list ldapscripts | grep bin

When users or groups are created via LDAP and then used by PAM-LDAP, the users and groups behave as if they exist on the local system. For that reason, if you already have users and group defined, and you happen to pick an UID or GID in LDAP that has the same value as an existing local user or group then the local user and group will take precedence and instead of logging-in as the LDAP user or group, you will end up logging-in as a local user instead. This can be particularly harmful in case some of your users are configured with administrative permissions, say, via /etc/sudoers.

To prevent clashes, before creating users, check out /etc/adduser.conf and look for (Debian defaults):

FIRST_SYSTEM_UID=100
LAST_SYSTEM_UID=999

FIRST_SYSTEM_GID=100
LAST_SYSTEM_GID=999

These settings imply that system users have UIDs and GIDs in the 100 to 999 range. In this case, you probably do not want to create an LDAP user with an UID or GID in that range or you may end up impersonating a system user.

The other settings to look for in /etc/adduser.conf are (Debian defaults):

FIRST_UID=1000
LAST_UID=29999

FIRST_GID=1000
LAST_GID=29999

which means that common users range with UID and GID between 1000 and 29999.

One decision would be to have LDAP users and groups with IDs over 30000 or narrow the settings in /etc/addusers.conf depending on how may users are expected to login to a machine. A different approach is based on the USERS_GID setting:

USERS_GID=100 

which states that if USERGROUPS is not set to yes, then new users are automatically added to the group with GID 100 - which corresponds to the literal users in /etc/groups.

A lot of frustration can arise from nscd which is the caching component of nslcd. In case the authentication fails, attempt to restart nscd via:

systemctl nscd restart

nscd caches credentials such that if you have made a configuration change, the old credentials may have been cached and will not be released until after nscd is restarted.

With an LDAP server installed, on other Linux machines meant to use the LDAP server, only the libpam-ldapd package is needed:

aptitude install libpam-ldapd

which should pull nslcd and nscd as dependencies.

The search base of the LDAP server will have to be configured (in this case dc=ldap,dc=home) followed by selecting the changes to /etc/nsswitch.conf.

Next, create the /usr/share/pam-configs/mkhomedir file with the contents from the Linux Authentication section and then issue:

pam-auth-update

followed by:

dpkg-reconfigure nslcd

where you will have to enter the LDAP address of the server, the LDAP search base and the administrator DN configured in the previous sections.

Finally, restart the services with:

/etc/init.d/nslcd restart
/etc/init.d/nscd restart

and you should be able to log-in with users created on the LDAP server.