Debian GNU: Setting up OpenLDAP

OpenLDAP is an open source implementation of the Lightweight Directory Access Protocol. Directory itself is a tree-structured, read-optimized database. Yellow pages or a phonebook are good associations to have in mind, even though LDAP is much more powerful.

We will use OpenLDAP to provide a central authentication location for user logins anywhere on the network, with their home directories being automatically created on their first access to individual machines.

This guide can be followed standalone to make OpenLDAP both perform authentication and serve user meta data. However, using LDAP for authentication as shown here is not secure due to plain text connections made to the LDAP server and passwords travelling over the wire. It is therefore advised to use LDAP in combination with a superior and secure network authentication mechanism Kerberos, which is explained in another article from the series, the MIT Kerberos 5 Guide.

That said, let's move onto our LDAP setup.

From a technical perspective, LDAP directory consists of a set of hierarchically organized entries. Each entry belongs to certain Object Classes and contains various key=value pairs called attributes.

Each entry is uniquely identified by a Distinguished name ("DN"). DN is formed as a list of components, separated by commas, that provide "full path" to the entry, starting from the top of the tree. For example, company Example, Inc. would have the root of the tree in dc=example,dc=com. A person employed by Example, Inc. would then have a corresponding LDAP entry with DN cn=person,ou=People,dc=example,dc=com.

Which attributes may or must be present in an entry is governed by the entry's objectClasses.

You might notice that the individual components of the DN, such as cn=person above, are also formed as key=value pairs. Those "keys", cn, ou and dc, stand for Common Name, Organizational Unit and Domain Component. They are a part of every-day LDAP terminology that you will get used to.

ObjectClasses, attributes, syntaxes, matching rules and other details of the tree structure are configurable and loaded at LDAP server startup by reading the schema files defined in /etc/ldap/slapd.conf.

Let's quickly identify LDAP-specific elements in our setup:

You can find the complete OpenLDAP documentation at the OpenLDAP website. For an authoritative OpenLDAP book, see Gerald Carter's LDAP System Administration by O'Reilly.

It's quite disappointing when you are not able to follow the instructions found in the documentation. Let's agree on a few points before going down to work:

OpenLDAP's server component is called slapd, and is basically all that we will need.

sudo apt-get install slapd ldap-utils

Debconf answers for reference:

Omit OpenLDAP server configuration? No

DNS domain name: spinlock.hr

Organization name? spinlock.hr

Administrator password: PASSWORD

Confirm password: PASSWORD

Database backend to use: HDB

Do you want the database to be removed when slapd is purged? No

Allow LDAPv2 protocol? No

As soon as the installation is done, the OpenLDAP server (command slapd) will start.

Our OpenLDAP server is already running, so let's first configure /etc/ldap/ldap.conf, a common configuration file for all LDAP clients. This will allow us to run ldapsearch and other commands without having to list all the basic parameters by hand each time.

Enable the following two lines in /etc/ldap/ldap.conf, creating the file if necessary:

BASE  dc=spinlock, dc=hr
URI ldap://192.168.7.12/

Then, let's edit the server's configuration file in /etc/ldap/slapd.conf to tune its behavior.

Make sure all the schema files are enabled:

include         /etc/ldap/schema/core.schema
include         /etc/ldap/schema/cosine.schema
include         /etc/ldap/schema/nis.schema
include         /etc/ldap/schema/inetorgperson.schema

Change the verbosity level from 0 or "none" to 256:

loglevel 256

Search for line "index objectClass eq" and add another search index. In particular combinations, it may be possible to receive no results when the searched entries are not indexed, so this step is important:

index           objectClass eq
index           uid         eq

To make the new index option apply, run the following commands:

sudo invoke-rc.d slapd stop
sudo slapindex
sudo chown -R openldap:openldap /var/lib/ldap
sudo invoke-rc.d slapd start

It's already the time to test the installation. Our OpenLDAP server does not contain much information, but a basic read operation can be performed normally.

In LDAP terms, read operation is called a "search". To perform a search using generic command-line utilities, we have ldapsearch and slapcat available.

Ldapsearch (and other LDAP utilities prefixed "ldap") perform operations "online", using the LDAP protocol.

Slapcat (and other OpenLDAP utilities prefixed "slap") perform operations "offline", directly by opening files on the local filesystem. For this reason, they can only be ran locally on the OpenLDAP server and they require administrator privileges. When they involve writing to the database, the OpenLDAP server usually needs to be stopped first.

In the output of the two search commands, you will notice two LDAP entries, one representing the top level element in the three, and another representing the LDAP administrator's entry. In the slapcat output, notice the extra attributes not printed with ldapsearch. One of those is userPassword, which is not shown to anonymous readers due to the appropriate default access restrictions in /etc/ldap/slapd.conf.

ldapsearch -x

# extended LDIF
#
# LDAPv3
# base <dc=spinlock, dc=hr> (default) with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# spinlock.hr
dn: dc=spinlock,dc=hr
objectClass: top
objectClass: dcObject
objectClass: organization
o: spinlock.hr
dc: spinlock

# admin, spinlock.hr
dn: cn=admin,dc=spinlock,dc=hr
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator

# search result
search: 2
result: 0 Success

# numResponses: 3
# numEntries: 2

sudo slapcat

dn: dc=spinlock,dc=hr
objectClass: top
objectClass: dcObject
objectClass: organization
o: spinlock.hr
dc: spinlock
structuralObjectClass: organization
entryUUID: 350a2db6-87d3-102c-8c1c-1ffeac40db98
creatorsName:
modifiersName:
createTimestamp: 20080316183324Z
modifyTimestamp: 20080316183324Z
entryCSN: 20080316183324.797498Z#000000#000#000000

dn: cn=admin,dc=spinlock,dc=hr
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator
userPassword:: e2NyeXB0fVdSZDJjRFdRODluNHM=
structuralObjectClass: organizationalRole
entryUUID: 350b330a-87d3-102c-8c1d-1ffeac40db98
creatorsName:
modifiersName:
createTimestamp: 20080316183324Z
modifyTimestamp: 20080316183324Z
entryCSN: 20080316183324.804398Z#000000#000#000000

As explained, the LDAP database is structured as a tree. The top level element in the tree for your organization is often its domain name. In case of a domain spinlock.hr, the toplevel tree element would be dc=spinlock,dc=hr.

On the next level below, an organization is often divided into "organizational units", such as people, groups, hosts, services, networks, protocols, etc.

Accordingly, to support people's Unix "meta data" in our LDAP directory, we will be interested in creating two of the mentioned organizational units, People and Group. The two will roughly correspond to the Unix /etc/passwd and /etc/group files.

Ldap data is interchanged in a textual format called LDIF. Command-line LDAP utilities receive and produce data in this format. Note that the LDIF stream can also contain commands, such as for adding, modifying or removing LDAP entries.

Knowing this, we'll put together a simple LDIF file, /var/tmp/ou.ldif, that will instruct the server to add the two organizational units. Pay attention to the empty line separating the entries:

dn: ou=People,dc=spinlock,dc=hr
ou: People
objectClass: organizationalUnit

dn: ou=Group,dc=spinlock,dc=hr
ou: Group
objectClass: organizationalUnit

To load the LDIF file into the server, let's show an example using the offline tool, slapadd:

sudo invoke-rc.d slapd stop
sudo slapadd -c -v -l /var/tmp/ou.ldif
sudo invoke-rc.d slapd start

Let's use ldapsearch to verify the entries have been created.

ldapsearch -x ou=people

# extended LDIF
#
# LDAPv3
# base <dc=spinlock, dc=hr> (default) with scope subt
# filter: ou=people
# requesting: ALL
#

# People, spinlock.hr
dn: ou=People,dc=spinlock,dc=hr
ou: People
objectClass: organizationalUnit

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

In the same manner we've created the two organizational units, let's create our first group and a person belonging to it. Again, we approach the problem by constructing and loading an LDIF file, /var/tmp/user1.ldif, paying attention to the empty line separating the entries:

dn: cn=mirko,ou=group,dc=spinlock,dc=hr
cn: mirko
gidNumber: 20000
objectClass: top
objectClass: posixGroup

dn: uid=mirko,ou=people,dc=spinlock,dc=hr
uid: mirko
uidNumber: 20000
gidNumber: 20000
cn: Mirko
sn: Mirko
objectClass: top
objectClass: person
objectClass: posixAccount
objectClass: shadowAccount
loginShell: /bin/bash
homeDirectory: /home/mirko

To load the LDIF file into the server, let's show an example using the online tool, ldapadd. Since, as said previously, ldapadd uses the LDAP protocol, we'll have to bind to the server as system administrator and type in the correct admin password (defined during slapd installation):

ldapadd -c -x -D cn=admin,dc=spinlock,dc=hr -W -f /var/tmp/user1.ldif

Enter LDAP Password: PASSWORD

adding new entry "cn=mirko,ou=group,dc=spinlock,dc=hr"

adding new entry "uid=mirko,ou=people,dc=spinlock,dc=hr"

Now to define the new user's password, let's run an online tool ldappasswd. (This step is not needed if you plan to use LDAP in combination with Kerberos as explained in MIT Kerberos 5 Guide.)

ldappasswd -x -D cn=admin,dc=spinlock,dc=hr -W -S uid=mirko,ou=people,dc=spinlock,dc=hr

New password: NEW USER PASSWORD

Re-enter new password: NEW USER PASSWORD

Enter LDAP Password:  ADMIN PASSWORD

Result: Success (0)

Now let's use ldapsearch to verify the user entry has been created. Note that the password field, userPassword, will not be shown even if we created it, due to the default access restrictions in /etc/ldap/slapd.conf.

ldapsearch -x uid=mirko

# extended LDIF
#
# LDAPv3
# base <dc=spinlock, dc=hr> (default) with scope subtree
# filter: uid=mirko
# requesting: ALL
#

# mirko, people, spinlock.hr
dn: uid=mirko,ou=people,dc=spinlock,dc=hr
uid: mirko
uidNumber: 20000
gidNumber: 20000
cn: Mirko
sn: Mirko
objectClass: top
objectClass: person
objectClass: posixAccount
loginShell: /bin/bash
homeDirectory: /home/mirko

# search result
search: 2
result: 0 Success

# numResponses: 2
# numEntries: 1

Congratulations! You now have a working LDAP setup.

Now that we have a new user created in LDAP, we should allow the system to see it. For example, let's test for existence of users root and mirko. The administrator will be present, while mirko will not:

id root
uid=0(root) gid=0(root) groups=0(root)

id mirko
id: mirko: No such user

To enable the system see LDAP accounts, we need to install libnss-ldap (which may automatically install libpam-ldap as well) and nscd:

sudo apt-get install libnss-ldap nscd

All debconf answers for reference:

LDAP server URI: ldap://192.168.7.12/ (Note the "ldap://", NOT "ldapi://"!)

Distinguished name of the search base: dc=spinlock,dc=hr

LDAP version to use: 3

Does the LDAP database require login? No

Special LDAP privileges for root? No

Make the configuration file readable/writeable by its owner only? No

Allow LDAP admin account to behave like local root? Yes

Make local root Database admin. No

Does the LDAP database require login? No

LDAP administrative account: cn=admin,dc=h15,dc=ri

LDAP administrative password: PASSWORD

Local crypt to use when changing passwords. md5

PAM profiles to enable: select all

To configure the NSS module further, open /etc/libnss-ldap.conf. Locate and adjust the configuration lines as shown:

base dc=spinlock,dc=hr
uri ldap://192.168.7.12/

Finally, to activate the LDAP NSS module, edit /etc/nsswitch.conf by replacing the two lines mentioning passwd and group with the following:

passwd:         files ldap
group:          files ldap

Nscd (the Name Service Caching Daemon) is used to cache metadata locally, instead of querying the LDAP server each time. It is a very efficient service in the long run, but we will stop it for for the moment, during testing, to always retrieve the data directly from the LDAP server:

sudo invoke-rc.d nscd stop

Now we can verify that LDAP users have become visible:

id mirko

uid=20000(mirko) gid=20000(mirko) groups=20000(mirko)

The final step in this article pertains to integrating LDAP into the system authentication procedure.

Let's install and configure libpam-ldap. (You might have already done this step automatically, during libnss-ldap installation — in that case Debian will just report the package is already installed).

sudo apt-get install libpam-ldap

Debconf answers for reference:

Make local root Database admin. No

Does the LDAP database require login? No

Local crypt to use when changing passwords. md5

To configure the PAM module, open /etc/pam_ldap.conf. Locate and adjust the configuration lines as shown:

base dc=spinlock,dc=hr
uri ldap://192.168.7.12/

Now let's configure Linux-PAM itself. PAM configuration is quite fragile, so use the provided examples that have been verified to work. For any modifications, you will want to look at PAM Configuration File Syntax and pay special attention to seemingly insignificant variations — with PAM, they often make a whole world of difference.

PAM will require the user to be present either in the local password file or in LDAP and to know the correct password, for the authentication process to continue.

Note that authentication through LDAP, as shown here, is not secure, due to connections to the LDAP server being made in plain text and passwords travelling over the wire.

Instead of encrypting the connection to the LDAP server, the PAM files shown below also support Kerberos for authentication, if you've installed Kerberos as explained in MIT Kerberos 5 Guide. In that case, modify the PAM lines as noted in file comments and the authentication will be performed in a completely secure and superior manner using Kerberos.

account sufficient      pam_unix.so
account required        pam_ldap.so

# Enable if using Kerberos:
#account required        pam_krb5.so

# Disable the three lines if using Kerberos:
auth [success=1 default=ignore] pam_unix.so nullok_secure
auth required pam_ldap.so use_first_pass
auth required pam_permit.so

# Enable the three lines if using Kerberos:
#auth    sufficient        pam_unix.so nullok_secure
#auth    sufficient        pam_krb5.so use_first_pass
#auth    required          pam_deny.so

password sufficient   pam_unix.so nullok obscure md5

# Disable if using Kerberos:
password required     pam_ldap.so use_first_pass 

# Enable if using Kerberos:
#password required pam_krb5.so use_first_pass

session required        pam_unix.so
session required        pam_mkhomedir.so skel=/etc/skel/ umask=0022

# Enable if using Kerberos:
#session  optional  pam_krb5.so minimum_uid=1000

Having everything adjusted as shown, login to the system should succeed as user mirko:

Login: mirko
Password: PASSWORD

Debian GNU/Linux tty5

Creating directory '/home/mirko'.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
mirko@host:~$