Introduction
User authentication is the basis for modern, secure computing. Access to resources and services on a host or network depends on the authenticity of a user. The number of available services is constantly increasing as technology advances and traditional services are being connected to computer networks. Resources should be shared based on agreed policies with minimal overhead but in order to guarantee uninterrupted access a set of restrictions might be needed. Managing resources and services efficiently in an always evolving environment calls for centralized and integrated solutions that enable cost effective administration while still allowing for expansion in the future.
Traditional authentication systems on Linux environments have been largely based on either NIS or flat file databases. While these solutions have worked rather well to some degree, their administration and integration to wide range of applications in use today has been suboptimal. LDAP enables a centrally managed source for authentication and access policies and makes integration with applications easier to implement and maintain. This document provides a comprehensive configuration guide to migrate a Linux intranet to a fully LDAP enabled environment where also the applications are seamlessly integrated with LDAP.
LDAP Setup Overview
Reader is expected to be familiar with basic terms and concepts of networked Linux/Unix environments and LDAP terminology. Our Linux Intranet Configuration guide describes a commonly used Linux intranet configuration and it can be thought as a starting point for this guide. Wikipedia article on LDAP provides a good introduction to basics of the protocol and directories and it also describes other essential concepts such as operations, schemas, and naming. Fully understanding terms like bind domain and search base will be very valuable when debugging possible configuration issues.
OpenLDAP is one of the most widely deployed LDAP implementations and it is available for every major computing platform. Thus, components from OpenLDAP will be used to create the LDAP enabled environment. Some parts of the environment are actually implementation independent so those configurations can be used with any LDAP implementation. All configuration files and paths are valid on Red Hat compatible distributions, such as Red Hat Enterprise Linux, CentOS, and Fedora. However, just by using corresponding paths on other distributions the configuration files should be valid also with them. Configuration files that are not mentioned in this guide are suitable in their default form on Red Hat compatible distributions.
Configuration will begin by migrating existing authentication information from a legacy system for the LDAP enabled environment. Server setup using the migrated data will be carried out next. Client configurations can be made then, gradually adding LDAP enabled components in the network. Finally, also server replication for redundancy and integrated application examples will be configured. All the configurations are made in a non-disruptive manner, allowing the legacy system to be used until the LDAP setup is production ready. Pointers to additional documents for further customization are also provided.
It must be emphasized that setting up an LDAP environment is different compared to a usual service configuration on a Linux/Unix network. Configuring the LDAP server or an application are just enabling acts but the use of LDAP in real life deeply involves specifying local needs, policies, processes, and other such aspects that no general guide can definitely provide for any particular case. However, having an initial LDAP environment in place allows for basic use and provides a path for future enhancements.
Data Migration
Existing users, groups, hosts, and other related information in a system can be easily migrated for use by the LDAP server. Migration is done by using a set of migration scripts that are part of the original OpenLDAP package. The migration scripts will generate standard LDIF files both from flat files or from a NIS server. The LDIF standard defines a format for representing and modifying LDAP directory content and the format can be used with most LDAP server implementations. As LDIF files are regular text files they can be also viewed or edited with any text editor.
Below are all the needed commands to migrate user, group, and host data
from traditional flat files for an intranet using the domain name
intra and mail domain dom.ain. The below
mentioned directories (the other is for older distributions and the
other is for newer distributions) also contain several other migration
scripts that could be used to migrate additional data from flat files or
to migrate from a NIS
server.
When running the migration commands or using any of the provided
configuration files, obviously you must use domain names and IP addresses to match your local
environment. The commands should be run as root so that the file
/etc/shadow can be read during the migration.
export LDAP_EXTENDED_SCHEMA=1 export LDAP_BASEDN="dc=intra" export LDAP_DEFAULT_MAIL_DOMAIN="dom.ain" test -d /usr/share/openldap/migration && \ cd /usr/share/openldap/migration || \ cd /usr/share/migrationtools ./migrate_base.pl > /tmp/base.ldif ./migrate_passwd.pl /etc/passwd > /tmp/passwd.ldif ./migrate_group.pl /etc/group > /tmp/group.ldif ./migrate_hosts.pl /etc/hosts > /tmp/hosts.ldif
The generated LDIF files should be checked so that they look sane and contain expected information. They will be later imported into the LDAP server and the data will be used for testing the setup so integrity of the migrated data is essential.
It should be mentioned that few of the additional migration scripts may
fail because some newer distributions include multiple definitions for
certain rarely used protocols in their /etc/services file.
These definitions cannot be represented in the standard LDAP schema for
services. The workaround for these kinds of errors is to temporarily
remove the problematic definitions from the file
/etc/services while running the affected migration scripts.
Related RPMs:
openldap-servers (older distributions) or
migrationtools (newer distributions).
Server Configuration
The LDAP server needs to communicate in a secure manner with its clients when transferring sensitive information such as user names or password hashes. To secure all the traffic between the server and a client TLS encryption is used. To achieve this, a certificate needs to be created for the server. During the testing phase and in some cases also in production a self-signed certificate is suitable as such a certificate is enough for the purposes of communication encryption. A properly signed certificate would be needed when peer verification is a requirement. There is external comprehensive documentation available that explains certificate management in more detail as well as a very compact quick guide.
Many distributions provide a Makefile to ease the creation of a
self-signed certificate, otherwise command line utilities such as
openssl(1) can be used. The following commands utilize the
Makefile provided by your distribution. You should back up a possibly
existing certificate before creating a new certificate and then provide
some meaningful answers to the questions asked. The most important
question is about Common Name for which you must
provide the server IP address or
its fully qualified domain name. This is needed in order to properly
establish secure TLS
connections between the server and clients.
cd /etc/pki/tls/certs make slapd.pem
After the certificate has been successfully created with the correct
Common Name its owner and permissions must be adjusted so
that only the system administrator and the server process are able to
access it:
chown root:ldap slapd.pem chmod 0640 slapd.pem
Actual LDAP
server setup begins by creating an internal database directory for the
server to store its data and adjusting two configuration files. First a
database directory for the domain intra is created and a
database configuration file is placed there. Although the database
configuration file is not mandatory it provides good default values for
a small or medium-sized intranet and of course it can be tuned later on,
if needed. To initialize the needed directory and server's internal
database configuration, download this database configuration and execute the
following commands:
mkdir -p /var/lib/ldap/intra/db mkdir -p /var/lib/ldap/intra/logs mv DB_CONFIG /var/lib/ldap/intra/DB_CONFIG chown -R ldap:ldap /var/lib/ldap/intra chmod -R 0700 /var/lib/ldap/intra chmod 0600 /var/lib/ldap/intra/DB_CONFIG
That is all what is needed for the server internal database setup. Basic
configuration of the actual server parameters is also a straightforward
task. After placing this server
configuration file as /etc/openldap/slapd.conf,
removing unneeded additional default configuration files, and adjusting
the main configuration file owner and permissions the server is ready
for testing. At this stage it is best just to try to start up the server
and inspect its debugging messages:
chown root:ldap /etc/openldap/slapd.conf chmod 0640 /etc/openldap/slapd.conf /bin/rm -rf /etc/openldap/slapd.d /usr/sbin/slapd -h "ldap:///" -u ldap -d 255
You should see no errors in the output. If there are any errors you should double check file permissions and owners and also make sure that you have created the needed directory structure for the internal database. The path to the previously created certificate should also be correctly defined in the configuration file. Possible error messages usually give hints where a problem might be. However, if the instructions above have been carefully followed no errors will be printed meaning that the server configuration is correct.
Now that the server is correctly configured, the migrated data can be imported. Stop the server by pressing Ctrl-C in order to allow direct database access by the slapadd(8) command. Then execute the following commands to import the migrated data and clean up the LDIF files:
/usr/sbin/slapadd -v -l /tmp/base.ldif /usr/sbin/slapadd -v -l /tmp/passwd.ldif /usr/sbin/slapadd -v -l /tmp/group.ldif /usr/sbin/slapadd -v -l /tmp/hosts.ldif rm -f /tmp/base.ldif /tmp/passwd.ldif rm -f /tmp/group.ldif /tmp/hosts.ldif
Again, no errors should be printed when importing the data, only
messages indicating that data has been added to the database. The server
configuration is in essence now done but one final tweak missing. Since
the data in the LDAP server database is now the same as in the flat
files it makes testing a bit difficult as there are no, e.g., LDAP only user
account available for testing. So, for testing purposes, it is
recommended to add a testuser
entry into the server database. The entry contains information for a
user account testuser in the domain intra with
the password usertest. The entry can be added just like the
migrated data was added earlier:
/usr/sbin/slapadd -v -l testuser.ldif
You can use the command slappasswd(8) to create a new
password hash and replace the example password in the file before adding
the account. When the server configuration seems to be complete and data
for testing has been imported into the server you can finally configure
the server to be started during system boot up and then start the
server. File owners need to be also adjusted again as when directly
modifying the database files their ownership has changed. Please note
that the service name has changed in newest distributions and is called
slapd instead of ldap.
chown -R ldap:ldap /var/lib/ldap/intra /sbin/chkconfig ldap on /sbin/service ldap start
If there are any problems during the testing phase or at any later stage it is usually a good idea to start the server from command line with proper debugging level as shown a bit earlier. The server configuration will be tested in the next section.
Server configuration files: /var/lib/ldap/intra/DB_CONFIG, /etc/openldap/slapd.conf.
Required services to be started: ldap at the server.
Related RPMs:
openldap-servers.
Client Configuration
The client configuration instructions presented here are divided in two parts. First the command line client utilities from the OpenLDAP package are configured. Once the client utilities are working properly against the server it is time to configure system level user information and authentication mechanisms to use LDAP. Note that client configuration can be done initially either on the server host or on a client host. After verifying that all the configurations work correctly they should enabled on all hosts in the environment.
The OpenLDAP command line client utilities and client applications using
the OpenLDAP libraries use a pleasantly simple configuration file. To
test OpenLDAP command line client utilities, place this OpenLDAP client configuration
file as /etc/openldap/ldap.conf. Then, testing both the
server and the simplest command line client utility is done simple as
shown below. See the ldapwhoami(1) manual page for
explanation about the given parameters.
ldapwhoami -x -ZZ
The command should print out anonymous
to indicate that the
binding to the server was anonymous, i.e., no user credentials were
used. If an error occurred then either the command output or the server
debug log output probably contain information about the cause of the
issue. Before proceeding any further make sure that this simplest
command works, otherwise errors are likely to appear in other cases,
too.
The next test is a bit more sophisticated. It uses the command
ldapsearch(1), one of the most useful testing commands, to
bind as user testuser and search for user id
nobody. You may also experiment with other users, groups,
or hosts that have been added to the server database by adjusting the
search filter (the last parameter). The password prompted for is always
for the user used to bind to the server. It is worthwhile to check the
ldapsearch(1) manual page for additional information about
the command and its usage. It is also recommended that you experiment
with utilities like ldapadd(1) and ldapdelete(1)
that will surely be useful later on.
ldapsearch -x -ZZ -D "uid=testuser,ou=People,dc=intra" \ -W "(uid=nobody)"
It should be noted that the system wide configuration for the OpenLDAP
command line clients is /etc/openldap/ldap.conf but users
may also use command line parameters or create an optional personal
configuration file to override the system wide default file or to use
personal certificates. See the ldap.conf(5) manual page for
more information about these configuration files.
Now that the LDAP server and OpenLDAP clients have been tested and
confirmed to work it is time to wire up system level user information
and authentication mechanisms to use LDAP. Information to map user and group ids to
user and group names is requested when, e.g., the ls(1)
command lists files and their owners. User authentication is carried out
when a user is logging in to the system, for example. User information
service is provided by the NSS
functionality in the C standard library and the user authentication
infrastructure used in Linux distributions is PAM.
Once PAM is
configured to use LDAP as one of its authentication sources, all
applications with their PAM support enabled, such as sshd, are then
automatically using LDAP, too.
Needless to say, when wiring up system level authentication to use LDAP it is crucial
that the configuration is correct and all components are working as
expected. After making sure one more time that the LDAP server and
OpenLDAP clients are working, place this NSS/PAM LDAP configuration file as
/etc/ldap.conf. Both NSS and PAM will use this configuration file. The provided file
itself is long but in most setups all the commented out configuration
directives can be safely ignored. After making sure the file is adjusted
for your local environment NSS
can be wired up by copying this NSS
configuration file as /etc/nsswitch.conf. Now NSS configuration can be easily
tested:
getent passwd | grep ^nobody:
If everything has been set up correctly, the command will return two
identical entries, one from the flat file and the other from the LDAP server. If the
server is not running or the configuration is incorrect, then only the
flat file entry is returned as the LDAP server is not providing the additional
entry. In case of errors, double check the configuration file
/etc/ldap.conf and inspect the server debugging output, if
necessary.
Finally, after all the previous steps have succeeded, PAM can be configured to
enable system level authentication to use LDAP. You should backup the existing
PAM configuration
file /etc/pam.d/system-auth and only then use this PAM configuration file to
enable LDAP
based authentication. If you have made any earlier local customizations
to your PAM
configuration you might want to manually merge the LDAP related
directives to your local PAM configuration. To test the configuration by
utilizing the previously created testuser account you can
log in to the system or use the su(1) command:
su - testuser
If the previous command succeeds then the basic LDAP configuration is complete! You
may now experiment with additional command line utilities, user account
creation and modifications, and maybe also take one more look into all
configuration files to fully understand how all parts were made to work
in concert. Should you also want to enable LDAP logins via different graphical
display managers (like GDM),
then corresponding changes to /etc/pam.d/password-auth are
needed as were done for /etc/pam.d/system-auth. This is
also the time to decide whether you want to leave LDAP based
authentication enabled now or do you want to perhaps disable it by
reverting the previous changes until you have migrated more data or
experimented with server replication and some
additional configurations. You may also want
to read some detailed LDAP documentation
to really deepen your knowledge about LDAP.
Common configuration files: /etc/openldap/ldap.conf, /etc/ldap.conf, /etc/nsswitch.conf.
Related RPMs:
nss_ldap, openldap-clients.
Server Replication
LDAP server replication is recommended even in small scale networks to prevent service breaks when a single server fails. Replication with OpenLDAP using a master and a slave server is achieved with few simple steps. First, a replicator user account is added to the LDAP server with the command ldapadd(1). Then, an LDIF database dump with the slapcat(8) utility is created:
ldapadd -x -ZZ -D "cn=Manager,dc=intra" \ -W -f ./Replicator.ldif /sbin/service ldap stop /usr/sbin/slapcat -v -l ./master.ldif
At this stage this server can be made the master server simply by
uncommenting the related master side directives at the end of the server configuration file that has
been used all the time. Also, a directory needs to be created for some
versions of the replication daemon, slurpd:
mkdir -p /var/openldap-slurp/replica chown -R ldap:ldap /var/openldap-slurp chmod -R 0700 /var/openldap-slurp
Next time the server is started with its init script, in addition to
slapd, also the replication daemon is automatically started
if the master side replication directives are defined. During the
testing phase slurpd(8) can of course be started also from
command line. When both the server and the replication daemon are
running it is time to set up the slave LDAP server. On the slave server, use
the same procedure to set up the slave server as was described earlier but instead of importing any
migrated data you must add the master server dump to the slave server:
/usr/sbin/slapadd -v -l ./master.ldif
Finally, on the slave server again, uncomment the two separate instances
of slave server related configuration that are clearly marked in the server configuration file. When done,
just start the slave server and LDAP server replication is enabled! To test that
the slave server is properly running use, e.g., ldapsearch(1)
with the command line option -H using a URI pointing to the slave
server. To test the actual replication just modify the contents of the
master server with, e.g., ldapadd(1) or
ldapdelete(1), and then verify that the change has been
propagated to the slave server, too. If that is not the case the servers
and the replication daemon should be run in debug mode to see why the
changes are not being propagated. As usual, common issues include file
owners and permissions, file paths in the configuration files, and the
validity of the certificates. When replication is working properly it is
then easy to set up additional slave servers, if needed.
Clients can be configured to use both the servers by listing the slave server in the client configuration alongside with the master server. It depends on your local environment whether the clients should be using the master or the slave server as their first option but in many cases the slave should be preferred. Client testing can be carried out by first testing a client with both servers running and then temporarily shutting down one server at a time to see how clients will use the running server instead.
It could be mentioned that for testing purposes the slave LDAP server can also be set up to run on the same host where the master LDAP is running. In that case the slave must configured to use different database directory, different port, and different configuration file than the master server and it must be started from command line.
Required services to be started: ldap at the servers.
Related RPMs:
openldap-servers.
Additional Configurations
This section provides quick instructions on how to set up some rather useful related additional configurations for your environment. Although these steps are not absolutely required they are very beneficial in some cases and probably needed when going into production.
nscd is a daemon that
caches the most common name service requests and greatly helps to reduce
load on LDAP
servers. Configuration is simple and can be done by copying this file as
/etc/nscd.conf. nscd can be then started with the following commands. In
general, there are only benefits in using it.
/sbin/chkconfig nscd on /sbin/service nscd restart
Required services to be started: nscd at the server and the
clients. Related RPMs:
nscd.
Apache HTTP
server and PHP
configuration shows how easily applications not using PAM can still be made
LDAP aware.
For Apache, use this .htaccess
file in an Apache served directory where AllowOverride
directive includes AuthConfig. Then, users accessing the
directory will be authenticated against the LDAP server. A PHP code to query an LDAP server is also
self-explaining and trivial to use. As these two small examples
demonstrate, connecting applications to LDAP is most of the time easy, making
migration from legacy authentication systems yet more appealing.
Related RPMs:
httpd, mod_authz_ldap, php,
php-ldap for above mentioned application configurations.
SASL
is an authentication and security framework for application layer
protocols such as SMTP
and IMAP.
If SASL is
needed in your environment the following tips might be helpful. To
enable SASL for testing in the setup presented here, copy this file as
/etc/saslauthd.conf on the server for the SASL
authentication daemon and place this saslauthd system configuration file as
/etc/sysconfig/saslauthd. Finally, this LDAP server SASL configuration file
must be copied as /etc/sasl2/slapd.conf. Then, restart
the LDAP
server and also start the SASL authentication daemon:
/sbin/service ldap restart /sbin/chkconfig saslauthd on /sbin/service saslauthd start
An example user authentication
proxy account entry includes the needed authzTo regular
expression mapping which works with the directives included in the
server configuration file used earlier. SASL configuration is
notoriously difficult so if there is no need to enable it then surely
the best thing to do is just ignore it. Otherwise, if it is really
needed, now OpenLDAP clients should be able to connect the LDAP server using
SASL:
ldapwhoami -ZZ -Y PLAIN -U testuser
And after adding the authentication proxy user SASL proxy authorization should also work:
ldapwhoami -ZZ -Y PLAIN -U AuthProxy -X u:testuser
As said, SASL might be a bit hard to configure correctly so you should be prepared to spend some time with SASL documentation if you intend to use it in a production environment.
Related RPMs:
cyrus-sasl, cyrus-sasl-plain,
cyrus-sasl-ldap.
Conclusion
This document provided a guide to set up, configure, and migrate to LDAP in a Linux intranet providing all essential configurations as well as examples of integrating applications and reliability enhancements. The presented configuration is suitable for small and medium-sized networks and many individual configuration files can also be utilized in larger networks or at a standalone host. There are numerous enhancements and customizations that could be made depending on local needs, policies, and processes on a particular environment. List of possible enhancements and improvements could include some of the following: Kerberos support, cached credentials during network outages, better laptop and mobility support, graphical tools for administration, performance improvements, policy and auditing management, and especially creation of policies and processes for local needs. These kinds of configurations are, however, outside of scope of this document.
All the configuration files mentioned are browsable and available for download.
Comments and feedback can be sent to oss(at)segetech.com. We would kindly like to note that we cannot promise a personal reply to all e-mails received, especially to those asking for help in some unrelated configuration problems. Inquiries about possible cooperation should be done via addresses listed at our Contact page.
This document was last updated on 2009-03-10.