Feb 20, 2013: LDAP protocol (for Lightweight Directory Access Protocol) was created 4 decades back to store data that should be accessed over a network. The LDAP protocol was defined as part of the RFC 4511 specification and it was implemented by many different vendors. Taking a look at one of the implementations of the LDAP protocol : OpenLDAP – a free and open-source implementation of LDAP that provides a server (called slapd) as well as utilities and libraries for developers.

It is a simple and configurable stand-alone server that is used in order to read, modify and delete from a LDAP directory. The slapd daemon also comes with many different utilities that can be used in order to create new entries easily, or to modify entries easily : slapadd or slappasswd just to name a few.

apt-get install slapd

slapd configuration comes as text-based interfaces that you need to fill in order to setup the server properly. Provide an administrator password for the LDAP server.

When installing the slapd server, the installation also :

Created a user named “openldap” on your server;
Created an initial configuration that is available at /etc/ldap
Created an initial and empty database that is ready to accept new entries.

To take a first look at the initial configuration of your OpenLDAP server, use the “slapcat” command and watch for the distinguished names created by slapd.

slapcat
slapcat | grep dn

OpenLDAP top DNs should match the DNS names of your domain.

It means that if you are currently working in the “osspl.com” domain, the OpenLDAP server should have the “dc=osspl,dc=com” top distinguished names. There is a way to reconfigure the slapd daemon.

dpkg-reconfigure slapd

First, you are asked if you want to omit the OpenLDAP server configuration. We obviously want to press “No” on this option because we want the initial configuration of the database to be created for us. On the next step, you are asked to provide the base distinguished name of your LDAP server.

As you can see, the slapd daemon describes that the DNS domain name is used to build the base DN of your OpenLDAP directory.

In this case, we are choosing to have “dc=osspl,dc=com” : note that you have to modify this entry to match your current DNS settings.

If you are not sure about the domain that you belong to, simply use the “domainname” command in your terminal.

$ domainname
osspl.com

Next, you are asked to provide the name of your organization. This is exactly the same step as the one done before, simply type your organization name and hit “Ok”.

As in first slapd configuration, you are asked to provide admin credentials for your LDAP server. Choose a strong password as it can be used in order to read and modify every single entry in the LDAP directory.

On the next screen, you are asked to provide the back-end to be used by LDAP.

For this step, you want to keep the default values (meaning a MDB for MariaDB back-end) unless you have a reason to choose another storage backend. Next, you are asked if you want the database to be removed when slapd is purged.

In this case, we will choose “No” : there are many situations where you simply want to update your slapd package or switch to a different LDAP server. If you choose yes, your database will be removed which can be a real problem if you don’t have any backups of your LDAP directory.

Finally, you are prompted with a warning : there are already some files sitting in the “/var/lib” directory of your server.

In this directory, you currently have your old database stored. As you are trying to reconfigure your OpenLDAP server, you will overwrite the content of this folder.

By choosing “Yes”, the slapd utility will backup the content of your existing database to the “/var/backups” folder.

The slapd server is now configured properly to match your current DNS settings. To have a first look at the content of your LDAP database, simply execute the “slapcat” (with sudo privileges if you are not currently logged as root)

slapcat

With this initial setup :

Your configuration files are stored in “/etc/ldap” : they are storing the ldap configuration file, the schemas that you can add to slapd, as well as the slapd.d directory used for server customization;

Your database is stored at “/var/lib/ldap” under the “data.mdb” database : backup this file.

Configuring firewall rules for LDAP

If you are using a firewall, it is very likely that you will need to accept inbound requests to your LDAP server. OpenLDAP runs on port 389.

To make sure that it is running correctly, run the “systemctl status” command on the “slapd” server.

systemctl status slapd
ufw allow 389

Add OpenLDAP entries using LDIF files

When adding new entries to your OpenLDAP server, you could use the “slapadd” utility in order to add a new LDIF file.

However, this is not the utility that we are going to use, instead we are going to use “ldapadd”.
Difference between slapadd and ldapadd

Before adding new entries, it is important for you to know the difference between slap utilities and ldap utilities. Both utilities take LDIF formatted files as an argument and they had the content to the database. However, when using slapadd, you will have to restart your LDAP server for the changes to be applied. This is not the case when using ldap utilities such as “ldapadd” : modifications are directly performed on the directory tree.

In order to be able to use “ldapadd”, “ldapsearch” and other LDAP utilities, you need to install the “ldap-utils” package on your system.

apt-get install ldap-utils

Creating your first LDIF file

As explained earlier, if you are using the console line, you will need to create LDIF files and add them to your current LDAP configuration or database.

The LDIF format is a format used in order to add or modify existing entries in a LDAP directory.

Using LDIF, you specify the distinguished name of the node that you want to modify and you describe the modifications to be performed.

As an example, let’s say that you want to create a new node in your LDAP directory named “users”.
Adding a users group

To achieve that, create a new LDIF file named “users.ldif” and add the following content in it.

/etc/ldap/schema/users.ldif
nano /etc/ldap/schema/users.ldif
dn: ou=People,dc=osspl,dc=com
objectClass: organizationalUnit
ou: People

As you can see, we are provided the complete DN of the node to be added, we specify the object class and the name of the node to be created.

In order to add this entry to your LDAP directory, you have to use the “ldapadd” command and specify the LDIF file to be used.

ldapadd -D "cn=admin,dc=osspl,dc=com" -W -H ldapi:/// -f users.ldif

Enter LDAP Password:
added new entry “ou=People,dc=osspl,dc=com”

If you are not familiar with ldap utility options, here is a description of the options provided :

-D : used to specify a node to bind to. When adding new entries to a LDAP server, you can choose your authentication mechanism but you usually want to bind to the admin node in order to gain all privileges on the tree;
-W : used in order to specify that we want the password to be prompted when connecting;
-H : used in order to specify the LDAP server to connect to. In this case, we are connecting to a LDAP server available at localhost;
-f : to specify the LDIF file to be added to the LDAP server.

Note that you can not use an external authentication in order to add new entries to LDAP by default : ACL are not configured to do that.

Now that your node is added to your tree, you can try to find it using the “ldapsearch” command.

ldapsearch -x -b "dc=osspl,dc=com" ou

Now that the “People” organizational unit was added, let’s add some users to your LDAP tree.

Adding new users to LDAP

In order to add new users, we are going to follow the same logic : creating a LDIF file containing individual entries for users. As described before, OpenLDAP uses schemas in order to define “objects” that can be added to the directory.

In this case, we are going to use the “posixAccount” schema which is already added to your database configuration by default.

The “posixAccount” object has several fields that can be used to describe a Linux user account such as the username, the surname but most importantly the user password.

Create a new LDIF file and add the following content in it :

touch /etc/ldap/new_users.ldif

# Content of new_users LDIF file

dn: cn=shiv,ou=People,dc=osspl,dc=com
objectClass: top
objectClass: account
objectClass: posixAccount
objectClass: shadowAccount
cn: shiv
uid: shiv
uidNumber: 10001
gidNumber: 10001
homeDirectory: /home/shiv
userPassword: <password>
loginShell: /bin/bash

When you are done, save your file and use the ldapadd command in order to add your entry to the LDAP directory tree.

ldapadd -D "cn=admin,dc=osspl,dc=com" -W -H ldapi:/// -f new_users.ldif

Enter LDAP Password:
added new entry “cn=shiv,ou=People,dc=osspl,dc=com”

Congratulations, you now have your first user stored in OpenLDAP.

You can read the user information by issuing a LDAP search command. Note that you won’t be able to read the user password as you are restricted by ACLs.

ldapsearch -x -b "ou=People,dc=osspl,dc=com"

Awesome, now that your LDAP server is configured, let’s configure a client in order to configure central authentication.

Configuring LDAP clients for centralized authentication

In the last section of this OpenLDAP server setup, we are going to see how you can configure LDAP clients (i.e your host machines) in order for them to connect using LDAP information.

How LDAP client authentication works

Before issuing any commands, it is important for you to have a global understanding of what we are actually building.

Before LDAP (and NIS), if you wanted to configure users and group permissions over multiple computers of a network, you would have to connect to them one by one and change their settings. LDAP comes as a great solution for this : LDAP will centralize user information in one single place on your network.

When a client connects to any machine of your domain, the host will first contact the LDAP server and verify that the user password provided is correct. The client library will bind (or authenticate) to the remote LDAP server using the admin account and retrieve the information associated with the user trying to connect.

Next, it will retrieve the password associated with the account and compare it with the password you typed when you logged in.

If the passwords match, you will be logged in your account, otherwise you will be denied.

Setup Client LDAP authentication on Debian

In order to setup client LDAP authentication, you will need to install the “libnss-ldap” package on your client.

apt-get install libnss-ldap

When installing this package, you will be prompted with many different questions in order to configure client centralized authentication.

First, you are asked to provide the URL of your LDAP server : it is recommended to setup an IP address (configured as static obviously) in order to avoid problems in DNS resolutions. On the server, identify your IP address with the ip command and fill the corresponding field on the client.

# On the server
ip a

Note : make sure that you are using the LDAP protocol and not the LDAPI protocol. For some reason, your server won’t be reachable if you use the LDAPI protocol. Next, you are asked to provide the root distinguished name of your LDAP server. If you are not sure, you should run a ldapsearch command on the server to get this information.

On the next screen, you are asked the LDAP version that you want to use : choose the LDAP version 3 for now. Next, you are asked if you want to make the local root the database admin. Type “Yes” to this option as you want to change the user password directly from the host machine. With this option, you will be able to run the “passwd” and have the password modified directly in the LDAP directory, which is pretty useful.

By default, the LDAP database does not require a login, so you can type “No” on this option.

Note: the LDAP database has no login but you have an admin account at the top of your LDAP directory. Those are two different concepts that are very different one from another. Next, type the LDAP administrator account to be used for bindinds. As a reminder, this is the account that will be used in order to get the user password information from the server. Type the password associated with the admin account on the LDAP server.

Done, you should now be able to query your LDAP server.

Linking client information to LDAP

In order to link your client information (such as username and password) to the LDAP directory, you need to modify the nsswitch file.

As a reminder, the nsswitch file is used in order to link some information on your system (such as users, groups or hosts) to various different sources (local, LDAP, NIS or others).

Edit the /etc/nsswitch.conf file and add a “ldap” entry to the first four sections : passwd, group, shadow, gshadow.

nano /etc/nsswitch.conf

Save your file and you should now be able to list users from the LDAP server.

getent passwd

Now that your user can be retrieved via LDAP, you will be able to log to this account by using the user password you have specified in the LDAP directory.

su - shiv
Type password specified in LDAP;
shiv@client:/home/shiv

Setup TLS SSL encryption so passwords are not transmitted over the network in clear text.

nano /etc/default/slapd
SLAPD_SERVICES="ldap:/// ldapi:/// ldaps:///"

nano olcSSL.ldif
dn: cn=config
changetype: modify
add: olcTLSCACertificateFile
olcTLSCACertificateFile: /etc/ssl/certs/ca-certificates.crt
add: olcTLSCertificateKeyFile
olcTLSCertificateKeyFile: /etc/ldap/ssl/ldap.osspl.com.key
add: olcTLSCertificateFile
olcTLSCertificateFile: /etc/ldap/ssl/ldap.osspl.com.crt
EOF
Some common LDAP commands are:
ldaprenamemachine
ldapadduser
ldapdeleteuserfromgroup
ldapfinger
ldapid
ldapgid
ldapmodifyuser
ldaprenameuser
lsldap
ldapaddusertogroup
ldapsetpasswd
ldapinit
ldapaddgroup
ldapdeletegroup
ldapmodifygroup
ldapdeletemachine
ldaprenamegroup
ldapaddmachine
ldapmodifymachine
ldapsetprimarygroup
ldapdeleteuser