OpenLDAP on Linux

OpenLDAP on Linux

Steven Patrick, Key Networks

1  Disclaimer

Use this information at your own risk.

2  Feedback

We welcome any feedback on this documentation. If you would like to enter into communication with us, please use the Contact form at http://keynetworks.com.au/

3  OpenLDAP

3.1  Software to Install

3.1.1  Host name

The package installation utility (at least on Debian/Ubuntu) uses the host domain name to set the LDAP domain components, so you need to edit /etc/hosts to reflect the domain components that you want set up. You can always change /etc/hosts back to what it was after the installation if need be. So, if you want your LDAP domain components to be dc=example,dc=com then make /etc/hosts look something like this:

127.0.0.1               hostname.example.com       hostname

3.1.2  On Debian/Ubuntu

sudo apt-get install slapd ldap-utils

You will be asked for an admin password during the installation of slapd.

3.1.3  Check Installation

Check the internal configuration database with:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=config dn

This should produce the following output:

dn: cn=config
dn: cn=module{0},cn=config
dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config
dn: olcBackend={0}hdb,cn=config
dn: olcDatabase={-1}frontend,cn=config
dn: olcDatabase={0}config,cn=config
dn: olcDatabase={1}hdb,cn=config

Check the dc=example,dc=com Directory Information Tree (DIT) with:

ldapsearch -x -LLL -H ldap:/// -b dc=example,dc=com dn

This should produce the following output:

dn: dc=example,dc=com
dn: cn=admin,dc=example,dc=com

3.2  Populate the LDAP database

Set up the basic structure of your DIT and populate it with some initial entries by generating a file called init.ldif with something like the following contents:

#
# Initialize the AddressBook heirarchy
#
dn: ou=AddressBook,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
description: The Acme Address Book
ou: AddressBook
#
# Initialize the staff heirarchy
#
dn: ou=staff,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
description: Acme Staff
ou: staff
#
# Define individual users
#
dn: cn=matthew,ou=staff,dc=example,dc=com
objectClass: top
objectClass: person
cn: matthew
sn: Smith
description: Matthew Smith
userPassword: secret
dn: cn=mark,ou=staff,dc=example,dc=com
objectClass: top
objectClass: person
cn: mark
sn: Jones
description: Mark Jones
userPassword: secret
dn: cn=luke,ou=staff,dc=example,dc=com
objectClass: top
objectClass: person
cn: luke
sn: Brown
description: Luke Brown
userPassword: secret
dn: cn=john,ou=staff,dc=example,dc=com
objectClass: top
objectClass: person
cn: john
sn: Carpenter
description: John Carpenter
userPassword: secret
#
# Initialize the groups heirarchy
#
dn: ou=groups,dc=example,dc=com
objectClass: top
objectClass: organizationalUnit
description: Acme Groups
ou: groups
#
# Define individual groups
#
dn: cn=addressbook,ou=groups,dc=example,dc=com
objectClass: top
objectClass: groupOfNames
description: Members of the staff who can edit the Address Book
cn: addressbook
member: cn=matthew,ou=staff,dc=example,dc=com
member: cn=mark,ou=staff,dc=example,dc=com
member: cn=luke,ou=staff,dc=example,dc=com
member: cn=john,ou=staff,dc=example,dc=com

Add the content in init.ldif to your LDAP database with:

ldapadd -x -D cn=admin,dc=example,dc=com -W -f add_content.ldif

Which will result in:

Enter LDAP Password: *******
adding new entry ou=AddressBook,dc=example,dc=com
adding new entry ou=staff,dc=example,dc=com
adding new entry cn=matthew,ou=staff,dc=example,dc=com
adding new entry cn=mark,ou=staff,dc=example,dc=com
adding new entry cn=luke,ou=staff,dc=example,dc=com
adding new entry cn=john,ou=staff,dc=example,dc=com
adding new entry ou=groups,dc=example,dc=com
adding new entry cn=addressbook,ou=groups,dc=example,dc=com

You can check with:

ldapsearch -x -LLL -b dc=example,dc=com dn

Which will result in:

dn: dc=example,dc=com
dn: cn=admin,dc=example,dc=com
dn: ou=AddressBook,dc=example,dc=com
dn: ou=staff,dc=example,dc=com
dn: cn=matthew,ou=staff,dc=example,dc=com
dn: cn=mark,ou=staff,dc=example,dc=com
dn: cn=luke,ou=staff,dc=example,dc=com
dn: cn=john,ou=staff,dc=example,dc=com
dn: ou=groups,dc=example,dc=com
dn: cn=addressbook,ou=groups,dc=example,dc=com

3.3  Add the Mozilla LDAP Address Book Schema

You can check the existing schemas with:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn

You should see:

dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config

Copy the Mozilla LDAP Address Book Schema from https://wiki.mozilla.org/MailNews:Mozilla_LDAP_Address_Book_Schema . At the time of writing this document, this schema is published as an alpha version. Copy the text of the schema as published on this page, paste it into a file called mozillaabperson.schema and copy this file to /etc/ldap/schema/ :

sudo cp -v mozillaabperson.schema /etc/ldap/schema/

Warning: Make sure there are no spaces before the words 'attributetype' and 'objectclass' in the schema file, otherwise you will end up with errors when you try to add it with ldapadd below.

Make a file called schema_convert.conf with the following contents:

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

In a temporary area, make a directory called ldif_output .

Determine the index of the mozillaabperson schema:

sudo slapcat -f schema_convert.conf -F ldif_output -n 0 - grep mozillaabperson,cn=schema

You should see something like the following:

dn: cn={5}mozillaabperson,cn=schema,cn=config

The index is contained in the curly braces - in this case it is {5} .

Perform the conversion to LDIF format as follows:

sudo slapcat -f schema_convert.conf -F ldif_output -n0 -H
ldap:///cn={5}mozillaabperson,cn=schema,cn=config -l mozillaabperson.ldif

Edit mozillaabperson.ldif to remove the curly braces and index in the first and third line so that this:

dn: cn={5}mozillaabperson,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: {5}mozillaabperson

ends up as this:

dn: cn=mozillaabperson,cn=schema,cn=config
objectClass: olcSchemaConfig
cn: mozillaabperson

and then remove all the lines from:

structuralObjectClass: olcSchemaConfig

to the end of the file. The lines removed from the end of the file will look similar to this:

structuralObjectClass: olcSchemaConfig
entryUUID: 0c40ddde-af06-1032-83e4-c5dee8932b0b
creatorsName: cn=config
createTimestamp: 20130911081522Z
entryCSN: 20130911081522.075612Z#000000#000#000000
modifiersName: cn=config
modifyTimestamp: 20130911081522Z

Then add this new schema to the slapd-config DIT as follows:

sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f mozillaabperson.ldif

You should see output as follows:

adding new entry cn=mozillaabperson,cn=schema,cn=config

Check that the new schema is added with:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:/// -b cn=schema,cn=config dn

You should see something like the following:

dn: cn=schema,cn=config
dn: cn={0}core,cn=schema,cn=config
dn: cn={1}cosine,cn=schema,cn=config
dn: cn={2}nis,cn=schema,cn=config
dn: cn={3}inetorgperson,cn=schema,cn=config
dn: cn={4}mozillaabperson,cn=schema,cn=config

For good measure, copy mozillaabperson.ldif to /etc/ldap/schema/ :

sudo cp -v mozillaabperson.ldif /etc/ldap/schema/

3.4   Access Control

Check the existing access controls with:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:///
-b cn=config olcDatabase={1}hdb olcAccess

You should see:

dn: olcDatabase={1}hdb,cn=config
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write
by anonymous auth by dn=cn=admin,dc=example,dc=com write by * none
olcAccess: {1}to dn.base= by * read
olcAccess: {2}to * by self write by dn=cn=admin,dc=example,dc=com write
by * read

Delete the last access control by making a file called acl.ldif with the following contents:

dn: olcDatabase={1}hdb,cn=config
delete: olcAccess
olcAccess: to * by self write by dn=cn=admin,dc=example,dc=com write by * read

Then use it to delete the access control with:

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f acl.ldif

Which should give an output like:

SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry olcDatabase={1}hdb,cn=config

Check that the access is now as you expect:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:///
-b cn=config olcDatabase={1}hdb olcAccess

Giving you:

dn: olcDatabase={1}hdb,cn=config
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write
by anonymous auth by dn=cn=admin,dc=example,dc=com write by * none
olcAccess: {1}to dn.base= by * read

Then modify acl.ldif to give rights to the group cn=addressbook,ou=groups,dc=example,dc=com to be able to edit entries in the address book as follows:

dn: olcDatabase={1}hdb,cn=config
add: olcAccess
olcAccess: to dn.subtree=ou=AddressBook,dc=example,dc=com by group=
cn=addressbook,ou=groups,dc=example,dc=com write by * read
olcAccess: to * by self write by anonymous none by * read

Note that each olcAccess entry needs to be on one line - the first one above is broken over two lines to fit on the page.

Then apply with:

sudo ldapmodify -Y EXTERNAL -H ldapi:/// -f acl.ldif

You should see something like:

SASL/EXTERNAL authentication started
SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
SASL SSF: 0
modifying entry olcDatabase={1}hdb,cn=config

Check that the access is now as you expect:

sudo ldapsearch -Q -LLL -Y EXTERNAL -H ldapi:///
-b cn=config olcDatabase={1}hdb olcAccess

Giving you:

dn: olcDatabase={1}hdb,cn=config
olcAccess: {0}to attrs=userPassword,shadowLastChange by self write
by anonymous auth by dn=cn=admin,dc=example,dc=com write by * none
olcAccess: {1}to dn.base= by * read
olcAccess: {2}to dn.subtree="ou=AddressBook,dc=example,dc=com" by group=
"cn=addressbook,ou=groups,dc=example,dc=com" write by * read
olcAccess: {3}to * by self write by anonymous none by * read

3.5  Transferring your Address Book from Thunderbird to LDAP

3.5.1  Export from Thunderbird

Export your Thunderbird address book in LDIF format by going to Tools -> Address Book -> Tools -> Export. Select LDIF format in the drop-down list in the lower right corner and save the file as addressbook.ldif.

3.5.2  Preparing your Address Book

The addressbook.ldif file needs to be edited to conform to the restrictions listed in http://www.sudleyplace.com/LDAP/index.en.html#Editing . The easiest way to do this is to download this script http://www.sudleyplace.com/LDAP/abookconvert.zip and edit the PHP script as follows:

Change the line:

$BaseDN = 'o=Sudleyplace,ou=AddressBooks,dc=Qualitas,dc=com';

to the DN of your address book, e.g.:

$BaseDN = 'ou=AddressBook,dc=example,dc=com';

Change the line:

sort (&$allDNs, SORT_STRING);

to:

sort ($allDNs, SORT_STRING);

Then process your address book with the PHP script as follows:

php abookconvert.php < addressbook.ldif > ab.ldif

If there are any duplicate entries, you will be warned of this and will have to edit ab.ldif to remove the unwanted dulpicates.

If you edit ab.ldif you will see that each DN typically has the form:

cn=Bob Smith+mail=bsmith@example.com,ou=AddressBook,dc=example,dc=com .

If you don't like the +mail=... bit, you can edit ab.ldif to remove this. In vim, you can do this with:

:%s/+mail=.*,ou=/,ou=/

3.5.3  Check Common Names

Check the CN in ab.ldif. If it was not set in Thunderbird, then it comes across as cnX whereis X is a digit, e.g. cn0, cn1, cn2, etc. Remember to correct it in the DN as well.

3.5.4   Loading the Address Book into the LDAP database

Finally, you can import your prepared address book into your LDAP server with:

ldapadd -x -D cn=admin,dc=example,dc=com -W -f ab.ldif

You should see something like the following response:

Enter LDAP Password: *****
adding new entry cn=Bob Smith,ou=AddressBook,dc=example,dc=com
adding new entry cn=Roger Dodger,ou=AddressBook,dc=example,dc=com
adding new entry cn=Alex Jones,ou=AddressBook,dc=example,dc=com
adding new entry cn=Simon Bear,ou=AddressBook,dc=example,dc=com

See Troubleshooting for possible errors and their solutions.

3.6  Configuring Thunderbird to use LDAP

3.6.1   Add a new LDAP Directory to Address Book

In Thunderbird go to Tools -> Address Book. In the Address Book, go to File -> New -> LDAP Directory.

Fill in the appropriate details, e.g.:

General tab  

  • Name: Acme LDAP
  • Hostname: ldap.example.com
  • Base DN: ou=AddressBook,dc=example,dc=com
  • Port number: 389
  • Bind DN: cn=me,ou=staff,dc=example,dc=com

Then click OK and close the Address Book window.

3.6.2   Keeping an offline copy of your LDAP Address Book

It is good practice to keep an offline copy of your LDAP address book on your local machine if you are a mobile user that might not always have access to the LDAP server. To do this, in Thunderbird go to Tools -> Address Book -> righ-click your LDAP directory -> Properties -> Offline tab -> Download Now. You need to repeat this process every so often - maybe once a week or once a day, depending upon how frequently your LDAP address book is updated.

3.6.3   Global use of LDAP Address Book

If you want to use the LDAP address book for all your mail accounts (assuming you have more than one), then, in the Thunderbird main window go to Edit -> Preferences -> Composition -> Addressing. Under "When addressing messages, looking for matching entries in" tick Directory Server and select your LDAP server in the drop-down list.

3.6.4   Per Account use of LDAP Address Book

If you want to use the LDAP address book only for a specific mail account, then go to the settings for that account (Edit -> Account Settings), then click "Composition & Addressing" under that account in the left-hand pane. In the right-hand pane under "Addressing", select "Use a different LDAP server" and select your LDAP server in the drop-down list.

3.7  Using the LDAP address database when composing an email

The first time you try to address someone in an email, Thunderbird will try to connect to the LDAP server and will ask for your password. Enter your password and tick "Use Password Manager to remember this password".

3.7.1  Using the online vs the offline LDAP address database

If you have configured Thunderbird to use an LDAP address book, when you compose a new email and start entering a name in the To: field, it will contact the LDAP server and download appropriate entries to auto-complete the field for you. This is not a problem if you have a reasonably healthy network connection to the LDAP server. But, if you have very poor or no network connectivity to the server, Thunderbird will tend to hang or become unresponsive. There are a couple of ways around this problem. Both ways involve keeping an offline copy of the LDAP address book as per 3.6.2:

  1. Configure a global 3.6.3 or per account 3.6.4 LDAP address book. Then, download an offline copy of the LDAP address book as per 3.6.2. When you have a network connection to the server, it will all work seemlessly. When you lose your network connection to the server, before you compose a new email, switch Thunderbird to offline mode. You can do this by clickling the little "two computers" icon in the bottom left-hand side of the main Thunderbird window. The icon will have a small red cross on it when offline mode is activated. Then, compose your email as normal and your offline copy of the LDAP address book will be searched as you type the recipient's name. To send the email, you will have to click the same icon again to switch to online mode.
  2. Add the new LDAP Directory to Address Book as per 3.6.1, but do not configure a global 3.6.3 or per account 3.6.4 LDAP address book. Download an offline copy of the LDAP address book as per 3.6.2. Then add a new address book called "LDAP Link" (Tools -> Address Book -> File -> New -> Address Book). Then close Thunderbird down completely. Open a shell and go to your Thunderbird profile directory. There you will find four .mab files - abook-1.mab, abook.mab, history.mab and ldap.mab. The file called abook-1.mab is the new "LDAP Link" address book you have just made and ldap.mab is the offline copy of the LDAP address book. Delete abook-1.mab and make a symbolic link from ldap.mab to abook-1.mab. Here follows an example of how to do this (note that the name of your Thunderbird profile directory will be different, but will be of the form ????????.default):
cd /.thunderbird/bzb1xl07.default
ls *.mab
abook-1.mab abook.mab history.mab ldap.mab
rm abook-1.mab
ln -s ldap.mab abook-1.mab
ll *.mab
lrwxrwxrwx. 1 xxx xxx 8 Sep 13 18:00 abook-1.mab -> ldap.mab
-rw-rw-r--. 1 xxx xxx 275061 Sep 12 18:21 abook.mab
-rw-rw-r--. 1 xxx xxx 25908 Sep 13 09:35 history.mab
-rw-rw-r--. 1 xxx xxx 111160 Sep 13 17:35 ldap.mab
With this second method there is no need to switch to offline mode to access the offline copy of the LDAP address book, but be aware that Thunderbird will never have access to the live LDAP server, so you need to update your offline copy frequently as per 3.6.2. Also note that Thunderbird does not seem to see the updates in the offline copy until it has been restarted.

3.8  Editing and maintaining the LDAP database

To edit and maintain the LDAP database and entries in your address book, you need a capable LDAP browser. JXplorer is a cross platform LDAP browser and editor written in Java. JXplorer can be found at http://jxplorer.org/ .

3.8.1  JXplorer

Download JXplorer by going to http://jxplorer.org/downloads/users.html -> Base JXplorer -> Full Buildable Project. The project file will look like jxplorer-n.n.nn-project.zip (where n.n.nn is the version number). Expand this in /opt :

cd /opt
sudo unzip /Downloads/jxplorer-3.3.02-project.zip

Make a shell script called jxp in your home bin directory (/bin/jxp) with the following contents:

#!/bin/sh
cd /opt/jxplorer
/bin/sh /opt/jxplorer/jxplorer.sh

Make jxp executable with:

chmod 750 /bin/jxp

Make a System Tools menu entry for JXplorer by making a file called /.local/share/applications/jxplorer.desktop with the following contents:

[Desktop Entry]
Encoding=UTF-8
Name=JXplorer
Comment=LDAP browser and editor
Exec=jxp
NoDisplay=false
Type=Application
Icon=/opt/jxplorer/jxplorer.ico
Categories=System;

You should then see the JXplorer icon under System Tools in your desktop menu. If not, then log out and back in again and you should see it.

3.8.2  Connecting to the LDAP server from JXplorer

In JXplorer, go to File -> Connect. Enter the Host, Base DN, Security Level, User DN and Password. For example:

Host: 192.168.1.10       Port: 389 (default)
Protocol: LDAP v3 (default)
DSML Service: (leave blank)
Base DN: dc=example,dc=com
Level: User + Password
User DN: cn=john,ou=staff,dc=example,dc=com
Password: *********

You can then save these details under "Use a Template" so that they can be easily recalled when connecting in future.

When you click OK you will be able to browse the DIT.

You should able to change your own password when you browse to your user name under the staff OU.

3.8.3  Editing the Address Book

As long as you are a member of the cn=addressbook,ou=groups,dc=example,dc=com group, then according to the access control rights assigned under 3.4 you should be able to edit and add new entries to the AddressBook OU.

Editing is pretty straight forward. Just expand the AddresBook OU by clicking the circular symbol next to the AddresBook OU. Then select the entry you wish to modify, change the details in the pane on the right and then click the Submit button at the bottom of the right-hand pane.

To add new entry to the address book, right-click the AddressBook OU in the left-hand pane, then select New. The Parent DN should already be set to ou=AddressBook,dc=example,dc=com . There should be two columns - on the left Available Classes and on the right Selected Classes. Under Selected Classes you should see:

top
person
organizationalPerson
inetOrgPerson
mozillaAbPersonAlpha

If the column under Selected Classes is blank, then un-tick Suggest Classes and tick it again. The above list should then appear under Selected Classes.

Then enter the RDN, e.g.:

cn=John Smith

and click OK.

The Table Editor will then appear for the new entry. Enter at least the sn (surname), givenName and mail along with any other details you wish to record:

attribute type value
cn John Smith
objectClass inetOrgPerson
objectClass organizationalPerson
objectClass person
objectClass mozillaAbPersonAlpha
objectClass top
sn Smith
givenName John
mail john@example.com

Then click the Submit button below the Editor Table.

To remove an entry from the address book, just right-click the entry and select Delete.

3.9   Troubleshooting

3.9.1  ldap_add: Undefined attribute type (17)

You may end up with this error message from 3.5.4 with something like the following additional information:

additional info: birthday: attribute type undefined

To resolve this you need to edit ab.ldif and place a hash (#) before the offending attribute and then run ldapadd again as per 3.5.4.

3.9.2  ldap_add: Already exists (68)

You will need to remove all the entries from ab.ldif that have already been added before running ldapadd again.

3.9.3  ldap_add: Invalid syntax (21)

additional info: facsimiletelephonenumber: value #0 invalid per syntax

In this case there was an extraneous hash after the phone number. Removing the hash resolved the problem.

3.9.4  ldap_add: Object class violation (65)

In this case the offending object class was:

objectclass: groupOfNames

This entry appeared to be for a group with very little extra information, so it was deleted.

3.10  Glossary

DIT - Directory Information Tree

3.11  References

https://help.ubuntu.com/13.04/serverguide/openldap-server.html

http://www.sudleyplace.com/LDAP/index.en.html

http://www.openldap.org/doc/admin24/access-control.html

OpenLDAP man pages


File translated from TEX by TTH, version 4.03.
On 5 Nov 2013, 10:18.