Oct 15 2008
Open Ldap How To
phpLDAPadmin
Web Administrator
Many individuals throughout professional organisations will consider
their list of personal and professional contacts as one of their most
important assets. Similarly at home keeping our contact details of
friends, relatives and professional service providers like physicians
is also equally important, however maintaining that contact list across
several computers can be very time consuming; even frustrating if it is
lost.
Using the Lightweight Directory Access Protocol (LDAP) we can configure
a centrally managed address book that can be shared by all the of
computer workstations throughout the network (for many large
organisations this is a fundamental design concept). A central (or
shared) address book allows easy management of all contact details, it
can be backed up and restored very easily, and it can also be made
available through a secure web interface so it can be accessed remotely
from where ever the user may be.
This chapter will detail the procedures necessary to configure the
OpenLDAP (http://www.openldap.org)
directory service that will provide the basis for our address book and
make it available to our network users. We will also look at populating
the address book and provide security access controls so that only
authenticated users can access the information.
Not all email clients are able to write to the address book (although
reading is fine), this is normally due to the functionality of the
email client and not a problem with the directory service. Therefore,
we will also configure the web server with a web based administration
application which will allow full control of the address book; this
also allows the remote access if needed.
The following list of man pages can provide further information to
assist with configuration or debugging requirements.
| Man Pages: |
||
| ldap | slapd | slapcat |
| ldap.conf | slapd.conf | slapadd |
| ldapadd | slapd.access | slappasswd |
| ldapsearch | slaptest | ldif |
Initial Concepts
The shared address book is being configured using the LDAP directory
services which basically stores different types of information and
objects in a database and these entries are accessible using its own
directory architecture (X.500 standard).
The naming conventions used to
traverse this system can be extremely complex for new users to grasp,
so the following table has been provided as an example of what these
objects are and the names we are going to use in referencing them.
| Description | String Value (DN) |
| Base Domain
|
dc=example,dc=com |
| Admin User
|
cn=Manager,dc=example,dc=com |
| Authorised users located here |
ou=users,dc=example,dc=com |
| Authorised user account (example)
|
uid=alice,ou=users,dc=example,dc=com |
| Address book entries located here Also used by client as “Search Base”
|
ou=addressbook,dc=example,dc=com |
| Address book entry (example)
|
cn=Tom Thumb,ou=addressbook,dc=example,dc=com |
The following table explains some of the basic acronyms used throughout
the directory, there are many more than this that go to make up the
naming conventions, however these are the only ones we will be
concerned with.
| String | Attribute Type |
| dn | Distinguished Name |
| cn | Common Name |
| o | Organisational Name |
| ou | Organisational Unit Name |
| dc | Domain Component |
| uid | User Identification |
 |
Do not confuse the X.500 naming scheme used in LDAP with the email addresses of your contacts, they are totally separate details. This will become clear further on. |
Everything inside the directory has a distinguished name (dn) this is
what makes each entry unique from the others and also provides a means
to easily reference the object. Viewing the top table, the DN for the
manager account is “cn=Manager,dc=example,dc=com”, while all
of the address book entries are contained in the DN of “ou=addressbook,dc=example,dc=com”.
The following table displays valid examples of how domains are
expressed using the X.500 naming scheme.
| Example Domain Names |
String Value |
| home.lan
|
dc=home,dc=lan |
| example.com | dc=example,dc=com |
| example.org | dc=example,dc=org |
| domain.org.au | dc=domain,dc=org,dc=au |
| sub.domain.org.au | dc=sub,dc=domain,dc=org,dc=au |
| more.sub.domain.org.au | dc=more,dc=sub,dc=domain,dc=org,dc=au |
 |
If the LDAP server is simply being configured as a shared address book and not for any real networking requirement, then it is acceptable to use a simple domain similar to “home.lan” |
Basic
Configuration
The OpenLDAP package contains a server and client application. The
client application will be used to query the server and insert/update
information during the configuration, so it is necessary to configure
this as well as the server.
The configuration that we need is very simple, however good house
keeping means making backups before adjusting the configuration file.
| [bash]# cp /etc/openldap/ldap.conf /etc/openldap/ldap.conf.original [bash]# vi /etc/openldap/ldap.conf |
The following entry is really all that is needed for the client. It
identifies where the server is located, and which part of the directory
tree to query.
| URI ldap://galaxy.example.com:389 BASE dc=example,dc=com TLS_REQCERT allow
|
The server can be configured with a built-in administrator account that
has global root privileges, it is necessary to store the password for
the root account inside the server configuration file. The “slappasswd”
application allows passwords to be encrypted (or hashed) which stops
unauthorised users from viewing the password, or intercepting a
plaintext password while it is being transmitted over the network.
Create a suitable password for the root account so it can be placed
into the configuration file.
| [bash]# slappasswd |
| {SSHA}RZmBkCh3WwEMNhdANh/l3OynzHSifPzF |
The LDAP server is called slapd (Stand-Alone LDAP Daemon), lets backup
the configuration file before making adjustments.
| [bash]# cp /etc/openldap/slapd.conf /etc/openldap/slapd.conf.original [bash]# vi /etc/openldap/slapd.conf |
The following slapd.conf file contains the basic configurations
required to establish a shared address book on a secure network,
however there are no access controls yet defined; security is covered
later on. The encrypted root password should be substituted where
necessary.
The five lines that are commented below are not needed to configure our
simple address book. However they be needed if you wish to advance your
LDAP requirements so they have been left as comments only; they
may be removed if need be.
| include /etc/openldap/schema/core.schema include include #include pidfile /var/run/openldap/slapd.pid argsfile /var/run/openldap/slapd.args ############################################################# database suffix rootdn rootpw {SSHA}RZmBkCh3WwEMNhdANh/l3OynzHSifPzF <– insert generated root password here directory index #index #index uidNumber,gidNumber,loginShell #index # DB_CONFIG Settings - For SleepyCat Berkeley DB dbconfig set_lg_regionmax 262144 set_lg_bsize 2097152 |
|
It is possible to run multiple databases using the one OpenLDAP server, however we are only concerned with one for the time being. Consult the documentation for further details if needed. |
After the configuration has been adjusted it can be checked before it
is implemented. Any errors should be fixed before restarting the server.
| [bash]# /etc/init.d/ldap configtest |
The LDAP service should now be set at the appropriate runlevels and
checked to ensure they are set correctly.
| [bash]# chkconfig –level 345 ldap on [bash]# chkconfig –list ldap |
The service can now be started with the following command.
| [bash]# /etc/init.d/ldap restart |
Address
Book Entries
Information can be imported and exported into an LDAP directory service
using the LDAP Data Interchange Format (LDIF) as defined in RFC2849. An LDIF file
specifies the contents of a directory entry in a human readable text
format, this allows quick manipulation of a file to re-import similar
entries into the directory.
Now that the LDAP server has been configured and is running, we can
conduct a simple search of the naming context to see our directory
information before we start to import our entries. The “namingContexts”
should be similar to the example below.
| [bash]# ldapsearch -x -b ” -s base ‘(objectclass=*)’ namingContexts |
| # extended LDIF
# # LDAPv3 # base <> with scope base # filter: (objectclass=*) # requesting: namingContexts dn: namingContexts: # search result search: 2 result: 0 Success # numResponses: 2 # numEntries: 1 |
The following LDIF file will create the hierarchical directory service
structure that we will be using for our address book. The first entry
is that of the base directory and the second entry is for the Manager’s
(administrator) account. The last two entries are the two
organisational units that we will use to store the authorised users
(for adding security later) and the address book entries.
The bolded entries should be changed to suit your configuration
requirements.
| [bash]# vi /etc/openldap/addressbook.ldif |
| dn: dc=example,dc=com
objectclass: dcObject objectclass: organization o: Home LDAP Server dc: example dn: cn=Manager,dc=example,dc=com objectclass: organizationalRole cn: Manager dn: ou=users,dc=example,dc=com ou: users objectClass: top objectClass: organizationalUnit dn: ou=addressbook,dc=example,dc=com ou: addressbook objectClass: top objectClass: organizationalUnit |
Using the “ldapadd” command we can enter the LDIF contents into the
server, creating our initial directory scheme.
| [bash]# ldapadd -x -D ‘cn=Manager,dc=example,dc=com‘ -W -f /etc/openldap/addressbook.ldif |
| Enter LDAP Password:
adding new entry “dc=example,dc=com” adding new entry “cn=Manager,dc=example,dc=com” adding new entry “ou=users,dc=example,dc=com” adding new entry “ou=addressbook,dc=example,dc=com” |
The following LDAP search is requesting a listing of all entries
starting from the base “dc=example,dc=com”. This should return all of
the entries that where added in the previous step.
| [bash]# ldapsearch -x -b ‘dc=example,dc=com‘ ‘(objectclass=*)’ |
| # example.com
dn: dc=example,dc=com objectClass: top objectClass: dcObject objectClass: organization o: Home LDAP Network dc: example # Manager, example.com dn: cn=Manager,dc=example,dc=com objectClass: organizationalRole cn: Manager # users, example.com dn: ou=users,dc=example,dc=com ou: users objectClass: top objectClass: organizationalUnit # addressbook, example.com dn: ou=addressbook,dc=example,dc=com ou: addressbook objectClass: top objectClass: organizationalUnit |
Now that we have defined and imported our directory scheme, we are able
to create user entries to populate the addressbook. The following is a
simple example LDIF entry for a contact.
The first line (dn:) designates where about in the directory the entry
will belong when its imported, this should be changed to suit your
needs.
| [bash]# vi newcontact.ldif |
|
dn:cn=Tom Thumb,ou=addressbook,dc=example,dc=com |
The contents of the LDIF file can be added into the directory service
using the “ldapadd” command below.
The standard access controls for the server defines that everyone can
read the directory entries, but only the manager (administrator) can
write to the directories. To add the LDIF file the manager is
authenicating on the command line with the “-D ‘cn=Manager,dc=example,dc=com‘
-W” string.
| [bash]# ldapadd -x -D ‘cn=Manager,dc=example,dc=com‘ -W -f newcontact.ldif |
| Enter LDAP Password:
adding new entry “cn=Tom Thumb,ou=addressbook,dc=example,dc=com” |
Now that the first entry has been successfully added to the directory
server, the file can be copied so more entries can be added.
Alternatively, extra entries can be added to the same file ensuring
that a blank line is used to separate each different entry.
TLS Link Encryption
The standard security settings for the LDAP server allows everyone to
connect (bind) to the server and read the entire directory contents,
while only the administrative account can make changes or add new
entries. For your small home network you may find this entirely
suitable in its current format, however the following details will
provide some extra security configurations to make it less accessible,
this is also important if you wish to access your home server from
beyond your home network.
The access controls are defined within the servers main configuration
file.
| [bash]# vi /etc/openldap/slapd.conf |
The following details are typical of the security settings that you may
consider implementing. The first section details any link encryption
using TLS/SSL and it also enforces which actions can be done on the
server depending on the level of link security that has been
implemented.
The second section details the access controls based on the users
authentication and basic anonymous access. The default access controls
(below) have been defined to deny everyone access, however people are
allowed to bind to the server to authenticate. All authenticated users
are allowed to change their own details, and all of the entries in the
“ou=addressbook,dc=example,dc=com”
directory; anonymous access it disallowed.
| TLSCACertificateFile /etc/pki/tls/certs/ca-bundle.crt
TLSCertificateFile /etc/pki/tls/certs/slapd.pem TLSCertificateKeyFile /etc/pki/tls/certs/slapd.pem security ssf=1 update_ssf=112 simple_bind=64 disallow bind_anon |
|
The term “users” defines those people that have successfully authenticated with the server. |
You will need to create an SSL certificate for use with your server,
the following code will create a self-signed certificate which is good
enough for our requirements.
| [bash]# cd /etc/pki/tls/certs
[bash]# make slapd.pem |
| Country Name (2 letter code) [GB]:AU
State or Province Name (full name) [Berkshire]:QLD Locality Name (eg, city) [Newbury]:Brisbane Organization Name (eg, company) [My Company Ltd]:Miles Brennan Organizational Unit Name (eg, section) []:Home Linux Server Common Name (eg, your name or your server’s hostname) []:galaxy.example.com Email Address []:sysadmin@example.com |
The ownership and permissions for the self-signed certificate need to
be adjusted slighty so the basic “LDAP” user account can read the
certificate details.
| [bash]# chown root.ldap /etc/pki/tls/certs/slapd.pem
[bash]# chmod 640 /etc/pki/tls/certs/slapd.pem |
Now that the server has been configured for TLS/SSL, the LDAP client
also needs to be configured for TLS/SSL otherwise they will not be able
to communicate.
| [bash]# vi /etc/openldap/ldap.conf |
| URI ldaps://www.example.com:636 BASE dc=example,dc=com TLS_REQCERT demand <– see warning below, may need to be “allow” TLS_CACERTDIR /etc/pki/tls/certs/ TLS_CACERT /etc/pki/tls/certs/ca-bundle.crt TLS_CRLCHECK peer |
 |
Refer to “man ldap.conf” and “man slapd.conf” for the exact meanings of the TLS options. Incorrect settings when working with a “self signed” PEM certificate may prevent your LDAP client from successfully connecting to your SLAPD server. |
An access control list may be prone to user syntax errors and will not
be accepted by the LDAP server, so the configuration should be tested
before it is loaded.
| [bash]# /etc/init.d/ldap configtest |
If the configuration passes integrity testing, the server can be
restarted.
| [bash]# /etc/init.d/ldap restart |
The new security access controls now prevent unauthorised access to the
directory service, so simple user objects must be prepared that will
allow people to authenticate with the server.
The user objects will be imported into the LDAP server using an LDIF
file. Remember that everything in an LDIF file is human readable so
plain text passwords are a VERY BAD idea, especially if you are
following this guide for an organisation; no plain text passwords please.
The slappasswd application can be used to create a hashed value of a
users password, these are saved to store in a text file. This does not
mean they are completely safe, it just means they can not be easily
read. An attacker can still subject the password value to a brute force
attack, but it would take them an awfully long time. Physical security
is still important.
| [bash]# slappasswd |
| {SSHA}RZmBkCh3WwEMNhdANh/l3OynzHSifPzF |
The default algorithm for the hashed password is SSHA, this can be
changed at the command line to other formats; the default type (SSHA)
is recommended.
| [bash]# slappasswd -h {MD5} |
| {MD5}poocSzW4TMBN3fOtmVOQHg== |
The basic user object can now be created and imported into the LDAP
server. This file uses the “UID” (User ID) string to distinguish the object and
the contents are all that we need to create a basic authentication
mechanism.
It should also be noted that this object is stored in the “users”
organisational unit, which is located outside of the address book
directory.
| [bash]# vi useraccount.ldif |
| dn:uid=alice,ou=users,dc=example,dc=com
uid: alice userPassword: {MD5}poocSzW4TMBN3fOtmVOQHg== objectClass: top objectClass: account objectClass: simpleSecurityObject |
The user account can now be entered into the LDAP server.
| [bash]# ldapadd -x -D ‘cn=Manager,dc=example,dc=com‘ -W -f useraccount.ldif |
| Enter LDAP Password:
adding new entry “uid=alice,ou=users,dc=example,dc=com” |
 |
For Alice to authenticate to the server, she needs to pass “uid=alice,ou=users,dc=example,dc=com” as her username along with the the plain text value of her password, the hashed value is only for storage purposes. |
Backing Up The Database
The OpenLDAP server allows for easy importing and exporting of
directory entries using the LDIF format, this makes it extremely easy
to extract the complete contents of the database for backup purposes.
The service should be stopped before extracting or importing the
directory service listing.
| [bash]# /etc/init.d/ldap stop |
|
The LDAP server should be stopped before executing the “slapcat” or “slapadd” commands. This prevents the possibility of data corruption and ensures database integrity is maintained. |
The following “slapcat” command will extract the entire database
contents into the “backup_slapd.ldif” file. This file should be stored
in a save place, particularly if password information is contained in
the file.
| [bash]# slapcat -vl /etc/openldap/backup_slapd.ldif |
The contents of the stored “backup_slapd.ldif” file can be imported
back into the LDAP server using the following command. This is a quick
and easy method to rebuild your entire address book after a system
rebuild.
| [bash]# slapadd -vl /etc/openldap/backup_slapd.ldif |
If an LDIF restore is being done on a new LDAP server, there is a
possibility that the database directory has not been configured
correctly for the ldap user account. If this is the case then the
server may not start correctly because the file permissions are
incorrect.
To restore the file permissions on a newly restored LDAP database, use
the following command to grant user and group ownership to the “ldap”
user account. This may be different for each Linux distribution, please
refer to your configuration details first.
| [bash]# chown ldap.ldap /var/lib/ldap/* |
The service can now be started to access the directory services.
| [bash]# /etc/init.d/ldap restart |
phpLDAPadmin
Web Administrator
There are many different email clients available today that are capable
of using an LDAP server as a central address book, however even less of
these clients are able to write new contacts details to the server or
even make changes to an existing entry (this is not a server problem).
One of the easiest mays to interface and administer the shared address
book is by using a web based application installed on the web server;
this provides easy management and remote access to the address book.
phpLDAPadmin (http://phpldapadmin.sourceforge.net/)
is a PHP based web application designed specifically to allow remote
management of an LDAP server by using a simple web browser. Although
this package is covered under the open source license there is a small
fee for “commercial” users, but its still totally free for home use.
The package firstly needs to be downloaded from the phpLDAPadmin site
and saved somewhere on the server; the package is available for
download as a ‘tarball’ (a .tar.gz file). Use the following commands to
extract the archive into the “/var/www” directory, remember to replace ?.?.?
with the version number you have downloaded.
| [bash]# tar -xzvf phpldapadmin-?.?.?.tar.gz -C /var/www/ [bash]# chown -R root.root /var/www/phpldapadmin-?.?.?/ |
The application has now been extracted and needs to be configured with
the details of the local LDAP server. Normally there is only an example
configuration file available in the package, this should be copied over
as the main configuration file, then adjusted to suit your needs.
When when configured the Apache web server a few chapters ago, we
created an SSL
certificate and used the rewrite module to force SSL connections. It is
recommended that SSL also be forced on the phpLDAPamin application so
that any logon details and database queries are executed
confidentially.
| [bash]# cp /var/www/phpldapadmin-?.?.?/config/config.php.example /var/www/phpldapadmin-?.?.?/config/config.php |
The following details in the configuration file are the basic
requirements needed for simple LDAP access and administration by the
web application. There are further details which can be configured, but
not needed for simple address book management; you may configure these
further options if you would like to use them though.
| [bash]# vi /var/www/phpldapadmin-?.?.?/config.php |
| <?php
//$config->custom->debug['level'] = 255; //$config->custom->debug['file'] = ‘/tmp/pla_debug.log’; /*********************************************/ /* Define your LDAP servers in this section */ /*********************************************/ $i=0; $ldapservers = new LDAPServers; $ldapservers->SetValue($i,’server’,'name’,'My LDAP Server’); $ldapservers->SetValue($i,’server’,'host’,'127.0.0.1′); $ldapservers->SetValue($i,’server’,'port’,'389′); $ldapservers->SetValue($i,’server’,'base’,array(’dc=example,dc=com’)); $ldapservers->SetValue($i,’server’,'auth_type’,'config’); $ldapservers->SetValue($i,’login’,'dn’,'cn=Manager,dc=example,dc=com’); $ldapservers->SetValue($i,’login’,'pass’,’password‘); <– set your Manager password here $ldapservers->SetValue($i,’server’,'tls’,true); <– set to false if not using SSL certs ?> |
The archive for the phpLDAPadmin application was originally extracted
into the “/var/www/phpldapadmin”,
while the Apache web server has its “DocumentRoot”
directive set to “/var/www/html”
which means the
phpLDAPadmin application is located outside of the “DocumentRoot”
and the contents
are not yet accessible to the web server.
We can create a configuration file for the phpLDAPadmin application so
Apache can access the resources that are required. The configuration
below is using the AuthType
directive from Apache, ensuring that the access is restricted to only those users
that have a valid username and password.
| [bash]# vi /etc/httpd/conf.d/phpLDAPadmin.conf |
| Alias /ldap “/var/www/phpldapadmin-?.?.?” <Location “/ldap”> AuthType Basic AuthName “Private Area - LDAP AuthUserFile /etc/httpd/conf/authusers AuthGroupFile /etc/httpd/conf/authgroups Require group ldapusers Require valid-user </Location> |
If SSL certificates where created for the Apache web server, then it
should be configured to force the phpLDAPadmin application into SSL
mode to keep it
secure. This configuration uses the rewrite module configuration we
created in Chapter
13.
| [bash]# vi /etc/httpd/conf.d/mod-rewrite.conf |
| RewriteRule ^/ldap/(.*) https://%{SERVER_NAME}/ldap/$1 [R,L] |
The Apache web server needs to be restarted before the settings will be
implemented.
| [bash]# /etc/init.d/httpd restart |
If everything has gone well you should now be able to access the
phpLDAPadmin application on the local server at: https://localhost/ldap.
Email
Client Settings
The last steps in setting up the shared address book is to configure
the users email clients to access the LDAP server.
The following table contains some of the information needed to
configure the client applications. Note the username will need to be
written as the complete “distinguished name” value so the server knows
which object to authenticate.
Remember, not all clients can write to the address book, so use the
phpLDAPadmin application to add and manage the entries as needed.
| LDAP Server: |
galaxy.example.com:389 |
| Search Base: | ou=addressbook,dc=example,dc=com |
| Login Method: |
use distinguished name (if listed) |
| Username: | uid=alice,ou=users,dc=example,dc=com |
| Password: | As entered in useraccount.ldif file (plain text version) |
| Secure Connection: |
Never (unless encryption has been configured) |
If you configured SquirrelMail on your server during Chapter 13,
you will be pleased to hear that SquirrelMail is able to be configured
to use an LDAP address book.
You can use the following commands to configure SquirrelMail to use your new LDAP address book.
|
[bash]# cd /usr/share/squirrelmail/config [bash]# ./conf.pl |
The following list of client
configurations should be used as a guide only, they may differ between
versions and operating systems.
extra client settings that are not listed below, please send me the
connection details to have them added.
Linux Clients
- Evolution (Ver 2.0):
(can read and write)
1. Press “CTRL+SHIFT+B”, this opens “Add Address
Book”
2. Select “Type: On LDAP Servers”
3. Enter configuration details then save and close
- Thunderbird (Ver 1.5x):
(read only)
1. Press “CTRL+2″, this opens “Add Address
Book”
2. Select “Edit” –> “Preferences” –> “Composition” –> “Addressing”
3. Select “Directory Server” check box, then click “Edit Directories”
4. Enter configuration details then save and close
Microsoft Clients
- Microsoft Outlook 2003:
(read only)
1. Select “Tools” –> “E-mail Accounts” –>
“Add a
new directory or address book” –> “Internet Directory Service
(LDAP)”
2. Enter configuration details then select “More Settings..”
3. Enter the search base then save and close
- Microsoft Outlook Express (Version
6.0):
(read only)
1. Select “Tools” –> “Accounts” –> “Add”
–>
“Directory Service”
2. Enter simple configuration details from wizard
3. Highlight the new address book, select “Properties”
4. Enter login and search base details, save and close
-
Mozilla Thunderbird (Ver 1.0):
(read only)
1. Select “Tools” –> “Options”
–> “Composition”
2. Under “Address Autocompletion”, tick “Directory
Server”, then select “Edit Directories”
3. Select “Add”, enter configuration details then save and
close
Other Clients
??? Anyone ?
| Previous | Home | Next |