HOWTO/Tutorial: Installing an LDAP addressbook

I will describe here the installation of an addressbook for use with e-mail clients, and a web-interface for modifying it (as very few ldap clients seem to support ldap write access)

Installing OpenLDAP from ports
Configuring and Starting OpenLDAP
Adding initial entries
Change Passwords
Configure Access Control
Installing phpLDAPadmin
Changing password using the web interface
Adding entries using the web interface
Configuring Outlook to use the LDAP address book


The procedure described in this document worked for me but of course I can't guarrantee that it will for you, and that you won't lose data and be fired by your boss after following it.


I am using the following base configuration:

We will be installing the following:

I am not aware of any practical alternative to LDAP/OpenLDAP for this use, and of all those I have tried, phpLDAPadmin was by far the best LDAP client application I have seen.

I used the following sources for writing this document (please refer to them in case something goes wrong):

Installing OpenLDAP from ports

$ cd /usr/ports/databases/openldap
$ su
# env FLAVOR="bdb" SUBPACKAGE="-server" make install 

We'll be using the (default) bdb backend, and the -server subpackage indicates we want the server part (slapd, ...) in addition to the client part (ldapadd, ...)

I got a report that the bdb backend is not available (at least not directly) in older versions of OpenBSD. In this case you can use the ldbm backend. Just don't put the FLAVOR assignment in the above statement, AND replace "database bdb" by "database ldbm" in the slapd.conf configuration file

Configuring and Starting OpenLDAP

We first copy the default configuration files and create the data directory

# cp /usr/local/share/examples/openldap/slapd.conf /etc/openldap
# mkdir /var/openldap-data
# chmod 700 /var/openldap-data

Use your favourite editor on /etc/openldap/slapd.conf, and do the following changes:

inetorgperson is the type that we will use for addressbook entries, and these include lines make that type available.

rootdn is the "root" user, i.e. a user that is always allowed to read and write anything

A sample "bootstrap" slapd.conf can be found here. Once the basic database structure has been built, we will do final changes to this file

Note that it does not hurt if access control directives are already there. So if you want to save some time you can directly download the final file below BUT make sure you have rootpw set to secret otherwise you won't be able to do anything.

We can now start the LDAP server:

# /usr/local/libexec/slapd

Adding initial entries

Because the LDAP users themselves are stored in the LDAP database itself we have that chicken-and-egg problem as we need to have a user that we can use for creating users.

This is solved by that rootpw line in slapd.conf.
Unlike with other users, you can bind to the LDAP database as rootdn even if there is no corresponding entry in the database. The rootpw directive specifies the cleartext password of that user, which defaults to "secret".
We shall deactivate this cleartext passsword once having created the LDAP directory

In order to create an ldap entry (or a set of entries) one has to create an LDIF file, then do the actual creation with the ldapadd command.

Our initial database will be structured as follows:

You can download the definition of this initial structure here.

You should of course feel free to modify names, structure etc. The structure can also be altered later though not very easily.

Add these entries

$ ldapadd -x -D "uid=Manager,ou=Users,dc=example,dc=com" -w secret -f initial.ldif

The -D option specifies the user through which the adding has to be performed, which matches the rootdn line in slapd.conf.
The -w option specifies the password to use. When the system runs, you will want to use -W instead, which prompts for a password instead of expecting in on the command line

Change Passwords

The ldif file given above initialised each user's password to the user name itself, lowercased (ie AbkMgr's password is abkmgr)

You may modify these passwords now if you want, or later using the web interface (in which case you may skip this section, though you should at least read it as it explains the way passwords are handled in LDAP.)
The command for updating AbkMgr's password is:

ldappasswd -x -D 'uid=AbkMgr,ou=Users,dc=example,dc=com' -W -S

Replacing AbkMgr by Manager or Visitor will of course let you change their passwords as well. You will be prompted twice for the new password and once for the old one. Usual guidelines about passwords apply.

You may now wonder if Manager's password is "secret" or "manager". The answer is: both!
The rootpw line allows to login using that password so until you change that line in slapd.conf, the "secret" password will be usable for getting rootdn access. Additionally, the userPassword attribute of the Manager entry holds the "manager" password, and allows to get the same rootdn access. ldappasswd is modifying the userPassword attribute, so whatever you type at ldappasswd's prompt will be changing the password "manager", not "secret".

Configure Access Control

Now that we have a rootdn password in the database we can deactivate the password secret in the configuration file. In OpenLDAP, an empty password is considered inactive, so the rootpw directive is made inactive by putting two double quotes "" as its parameter.

We will now set up access control rules so that

has read/write access everywhere (as it is the rootdn user)
has read access everywhere and write access in the address book everywhere
has read access everywhere
anonymous users
Only have (read) access to the list of users

We'll also put a rule to prevent a user from seeing other users' passwords. Even if passwords are scrambled that won't hurt.

Add these lines before the database line:

access to dn.base="" by * read
access to dn.base="dc=example,dc=com" by * read
access to dn.base="ou=Users,dc=example,dc=com" by * read

# abkmgr can read/write the address book, visitor can read, others nothing
access to dn.subtree="ou=ABook,dc=example,dc=com"
        by dn.base="uid=AbkMgr,ou=Users,dc=example,dc=com" write
        by dn.base="uid=Visitor,ou=Users,dc=example,dc=com" read

# let everyone know the list of users (but not their passwords etc)
access to dn.children="ou=Users,dc=example,dc=com" attr=userPassword
        by self write
        by anonymous auth
        by * none

access to dn.children="ou=Users,dc=example,dc=com"
        by self write
        by * read

This final slapd.conf file can be found here.

The official OpenLDAP documentation has quite a good explanation about access control so I advise you to read some of it there if you want to understand in more details the meaning of the above.

Now restart the ldap server to take these settings into account (SIGHUP doesn't seem to work)

# kill `cat /var/run/`
# /usr/local/libexec/slapd

Installing phpLDAPadmin

Download the archive
$ cd /var/www/htdocs/
$ tar xvzf /path/to/downloaded/archive/phpldapadmin-0.9.4b.tar.gz
$ cp config.php.example config.php

Now we need to configure config.php for our setup.

Changing password using the web interface

You are now ready to start using the web interface. Point your browser to http://localhost/path/to/phpldapadmin/, maybe changing localhost to something else if you're doing this remotely.

rootdn (uid=Manager) can change everybody's password, and everybody can change its own password.

At login prompt, put the user name (like AbkMgr, ie no uid= or whatever) and the password you have set for that account.

The password is stored in the userPassword attribute. To change a user's password, browse to it using the + boxes and clicking on the name. Then type the new password, being careful with typos (as you aren't asked to type it twice for checking.) If you change a user's password through that user itself, you will be required to login again.

Adding entries using the web interface

To add/modify an entry in the addressbook, open the ABook node in the tree on the left and either click on the item you want to modify or on the Create link.

When creating you should select the Address Book Entry item. The create form doesn't let you put more than one email address immediately, but you can do this later.

You can use the import feature if you want to put many items at once. You will need to have these items in LDIF format to do that, though.

If you want to import entries from another LDAP server, add the specifications of that server in your config.php file and use the copy feature.

Configuring Outlook to use the LDAP address book

From inside Outlook, open Tools->Email Accounts

Select the Add a new directory or address book and click Next

Select Internet Directory Service (LDAP)

Set Server Name to the hostname of the server where OpenLDAP is running

Check the logon required box and put as User Name uid=Visitor,ou=Users,dc=example,dc=com. Put the visitor's password that you have set previously

Click More Settings and select the Search tab

Set the Search Base to dc=example,dc=com.

Click OK, Next and Finish.

Maxime Gamboni -