Howto Build an OpenLDAP Server

As I have been building and maintaning LDAP servers for some time now, I keep getting asked over and over if I will ever write a document describing how to easily get an OpenLDAP server up, how to get a Linux client to connect to it, and what are some of the pitfalls.  Well everyone, here ya go!

Also, I went through the entire process step-by-step and threw the photos up on Flickr.  The entire photo set should be at the bottom of this page if you need some extra assistance.

Installing the Base Server

As a rule of thumb its preferable to use a distribution of Linux that will support your installation for the life of the system.  Ubuntu 8.04, which we will use in this example, will be supported until 2013.  I personally prefer Ubuntu for a multitude of reasons that I will not delve into here.  This tutorial should work for Debian systems as well.

NOTE: As of Ubuntu 8.10, the LDAP server package is by default using the new method for configuring the database.  Yes it is more flexible.  Yes it is a massive pain in the butt to work with.  Using the slapd.d configuration makes a lot more sense only if you are planning on doing a multi-master configuration in my opinion.  I beleive there is a way to get slapd to use the slapd.conf file on later revisions of Ubuntu, however YMMV.

Download Ubuntu Here: http://www.ubuntu.com/getubuntu/download-server

The installation is pretty straightforward, so I don’t think I need to delve into how to do this.  I would recommend installing the OpenSSH Server and LAMP Server bundles when asked if you want to install additional packages.

Installing OpenLDAP (slapd)

Once the system is installed, we will run the following command:

sudo apt-get install ldaputils slapd

The command will also try to configure a basic LDAP environment.  just keep hitting enter to go through the screens, as we will be reconfiguring the service anyway.  Once you have completed the installation and returned to the prompt, run the following:

sudo dpkg-reconfigure slapd

As soon as you start the reconfiguration, you will be asked a series of questions.  Here are the answers that I have used:

• Omit OpenLDAP server configuration? NO
• DNS Domain Name: Domain suffix of the network (e.g. domain.local)
• Organization Name: Same as the DNS Suffix
• Administrator Password: Whatever you want
• Database backend to use: HDB
• Do you want the Database to be removed when slapd is purged? NO
• Move old database? YES
• Allow LDAPv2 protocol? NO

Installing phpLDAPAdmin

(optional)

Next we will install phpLDAPAdmin.  I know some people have issues with running php applications on their LDAP servers, and typically I will run phpLDAPAdmin somewhere else, however in this example we will install on the same machine for simplicity.

sudo apt-get install phpldapadmin

Once it is installed, we will want to make some modifications to the application to fit our needs.  Open /etc/phpldapadmin/config.php in vi or nano and perform the following steps:

NOTE: if you are using vi, you can search by using /SEARCH CRITERIA in command mode.  This will help invaluably.

• Locate and change $ldapservers to
  $ldapservers->SetValue($i,’server’,'base’,array(‘dc=domain,dc=local’));
• Comment out the admin login and uncomment the blank entry:
  $ldapservers->SetValue($i,’login’,'dn’,”);
• Uncomment (and change) the fallback_dn value:
  $ldapservers->SetValue($i,’login’,'fallback_dn’,true);
• Uncomment and change the auto_number starting point from 1000 to 10000:
  $ldapservers->SetValue($i,’auto_number’,'min’,'10000′);

Once all of this is completed, you will have to up the memory in the php.ini file.  By default php is only allocated 16MB, which is not enough.  We will need to up it to 32MB.

From this point you should be able to open a web browser and goto http://SERVER/phpldapadmin, replacing SERVER with your system IP or DNS name.

Building the Directory

There are several tools that can help you from this point.  Apache Directory Studio is a wonderful fat client that you can install on you desktop to perform some of the heavy-lifting work.  I personally prefer Apache Directory Studio for doing batch changes and things that would be more infeasible with other means.  PhpLDAPAdmin (what we installed above) is an excellent tool for adding and modifying single entries quickly.  It also has some niceties in that it has a set of templates for various objects pre-build for you.  If you ware a new user to LDAP, I highly recommend it.  Lastly, there are some low-level commandline applications that work wonderfully for performing any low-level work on the database.  I recommend the commandline applications only to someone familiar and comfortable with how LDAP is built and has a good understanding of how the objects are built.

Now for a little terminology before we go any further:

• Base DN (Domain Name): Refers to the base context that we are working with.  in our case dc=domain,dc=local.  Some applications however may only need to see a subset of the directory, and therefore may have a Base DN deeper in the directory.
• OU (Organizational Units): Think of this as like a folder where information is stored.  OUs are typically used to segment data into a coherent structure in the directory.
• Tree: This can be used synonymously with directory.  Tree is directly referring to the directory structure.  The base of the tree would be the dc objects, and the branches extend from there.
• CN (Common Name): You will see these a lot.  Group objects and User objects both use CNs to identify their location within the tree for example.

Ok, your properly confused.  Now to show you the basic structure that we will be creating:

• Base DN: dc=local,dc=domain
• Users: dc=local,dc=domain,ou=People
• Groups: dc=local,dc=domain,ou=Groups

Also we want to use a defined range for users and groups.  Here is a common standard:

• Users UID Range: 10000-10999
• Group GID Range: 11000-11999

There are multiple ways we can get this structure started. below is the structure we will be creating to graft our users and groups onto:

dn: ou=Groups,dc=domain,dc=local
objectClass: organizationalUnit
objectClass: top
ou: Groups

dn: ou=People,dc=domain,dc=local
objectClass: organizationalUnit
objectClass: top
ou: People

If your properly stumped, don’t worry.  To create this structure in phpLDAPAdmin just follow the following steps:

Login to web application using cn=admin,dc=domain,dc=local and the password you supplied.  Note: Securing Apache with SSL certificates is not covered as part of this walkthrough.  there is extensive documentation on how to perform this online, I would recommend you start with this walkthrough.

Creating the base structure:

• Click on the dc=domain,dc=local line on the left sidebar.
• Click Create new entry here.
• Click Organisational Role.
• Type in People and click Create Object.
• Repeat for the Groups object.

Creating a Group

• Click ou=Groups entry on the sidebar.
• Click Create a child entry in the main pane (it is under the Rename option).
• Click the Posix Group option
• Type in Users for the group and leave the Users feild blank.  Click Create Object.
• Change the gidNumber to 11000 and click Save Changes.
• Click Commit.
• Repeat this for all the groups you need.  Just make sure to iterate the GID number every time

Creating a User

• Click ou=People from the sidebar on the left.
• Click Create a child entry in the main pane (it is under the Rename option).
• Click the User Account option.
• Fill out the form and click Create Object.
• Repeat as needed.

Adding a User to more than One Group

Typically out of habit.  I prefer to keep all of the users with the same primary group if possible.  Then as groups are needed I will make secondary groups and add the users to them.  I have noticed that this method provides a single, unified group that everyone is a member of (in my case “Users”) and then more granular groups as needed.

• Click on the [+] symbol next to the ou=Groups item in the sidebar.
• Click on the Group you want to modify (or create a new group by clicking Create new entry here).
• If creating a new Group, add the usernames in the Users field seperated by a comma.  Thats all you need to do.
• If modifying a Group that already has members, just add the usernames to the memberUid field and click Save Changes and then Commit.
• If modifying an existing group (with no members associated with it) perform the following:
• Click Add new attribute.
• Select memberUid and add the list of usernames seperated by a comma.  Then click Add.

Connecting Clients

For the purpose of consistency, we will be using an Ubuntu 9.04 client.  Getting this working is fairly simple and can be laid out into 3 steps.

sudo apt-get install ldap-auth-client

The following questions may or may not be asked:

• Should debconf manage LDAP configuration: YES
• LDAP server Uniform Resource Identifier: ldap://SERVERIP
• Distinguished name of the search base: dc=domain,dc=local
• LDAP version to use: 3
• Make local root Database admin: NO
• Does the LDAP database require login: NO
• Local crypt to use when changing passwords: md5

You should now be at a prompt.  The next step is to enable LDAP logins:

• open /etc/nsswitch.conf in vi or nano
• at the end of the passwd, group, and shadow entries add ldap.  The end result should look like below:

passwd:         compat ldap
group:          compat ldap
shadow:         compat ldap

session required pam_mkhomedir.so skel=/etc/skel umask=0077

To Be Continued:

In part 2 we will be covering the following:

• Securing slapd with TLS.
• Adding in ACLs to restrict user logins to specific hosts or groups of hosts.
• Common Gotchas when adding complexity to your LDAP Tree.

Click Here for Part 2

PhotoStream of Installation