http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.

pdf

LDAP Implementation HOWTO

2. LDAP authentication using pam_ldap
andnss_ldap
This section focuses on how to use LDAP as a NIS substitutefor user accounts management.
Having a lot of user accounts on several hostsoften causes misalignments in the accounts
configuration. LDAP can be used tobuild a centralized authentication system thus avoiding
data replication andincreasing data consistency.
At the moment the most used method to distribute users account data andother information
through a network is the Network Information Service (NIS).Like LDAP, NIS is a distributed
service that allows to have a central serverwhere configuration files such as passwd,
shadow, groups, services, hosts etc.are kept. The NIS server is queried by NIS clients to
retrieve this information.
LDAP can offer the same functionality of NIS, moreover there are severaladvantages on
using LDAP:
* Information on the LDAP server can be easily used for severalpurposes. As outlined in
this HOWTO, the same users entries on the LDAP databasecan be used for other
applications like phone directories, mail routing, staffdatabases etc., thus avoiding data
replication and inconsistency.
* LDAP allows complex access control lists to be applied on thedatabase. This allows for a
fine grain tuning of permissions on the databaseentries.
* A secure transmission channel between the LDAP server and the clientscan be
implemented through the Secure Socket Layer (SSL).
* A fault tolerant service can be implemented using slapdreplication [1]and DNS round
robin queries(this is not covered in this document).
* Having a single instance of users on the network helps tomaintain users on many hosts
from a single management point (i.e. you cancreate and delete accounts in the LDAP
server and this changes are availableimmediately to LDAP clients).
Herein I'll focus on how an LDAP server can be used for authenticationand authorization on
systems providing the Pluggable Authentication Module(PAM) and the Name Service Switch
(NSS) technologies, in particular I'll referto the Linux operating system even if this
instructions can be applied to otheroperating systems.
The environment proposed consists of an LDAP server where users accountdata is stored in
a convenient format and a set of Un*x clients using thisinformation to authenticate and
authorize users on resources in a standard Un*xfashion.
A secure channel is also required in client/server communications sincecritical information
such as user account data, should not be sent in clearover the network, this channel will be
provided by the Secure Socket Layer.
On the client side a caching mechanism, needed for performance issues,can be provided by
the Name Service Caching Daemon.
All (almost) the software used to build this system is Open Source.
2.1. The components of the framework

page 1 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

This section outlines the various components that are used to build theauthentication system.
For each component is given a brief description.
2.1.1. Authentication: PAM and pam_ldap.so
The Pluggable Authentication Module allows integration of variousauthentication
technologies such as standard UNIX, RSA, DCE, LDAP etc. intosystem services such as
login, passwd, rlogin, su, ftp, ssh etc. withoutchanging any of these services.
First implemented by Sun Solaris, PAM is now the standard authenticationframework of
many Linux distributions, including RedHat and Debian. It providesan API through which
authentication requests are mapped into technologyspecific actions (implemented in the so
called pam modules). This mapping isdone by PAM configuration files, in which, for each
service are basically giventhe authentication mechanisms to use.
In our case, the pam_ldap module, implemented in the shared librarypam_ldap.so, allows
user and group authentication using an LDAP service.
Each service that needs an authentication facility, can be configuredthrough the PAM
configuration files to use different authentication methods.This means that it is possible,
using the PAM configuration files, to write acustom list of requirements that an user must
satisfy to obtain access to aresource.

2.1.2. The Name Service Switch and nss_ldap.so

Once an user is authenticated, many applications still need access touser information. This
information is traditionally contained in text files( /etc/passwd, /etc/shadow, and /etc/group)
but can also be provided by othername services.
As a new name service (such as LDAP) is introduced it can be implementedeither in the C
library (as it was for NIS and DNS) or in the application thatwants to use the new
nameservice.
Anyway, this can be avoided using a common, general purpose, nameservice API and by
demanding to a set of libraries the task of retrieving thisinformation performing technology
based operations.
This solution was adopted in the GNU C Library that implements theName Service Switch, a
method originated from the Sun Clibrary that permits to obtain information from various name
services through acommon API.
NSS uses a common API and a configuration file( /etc/nsswitch.conf) in which the
nameservice providers for every supported database are specified.
The databases currently supported by NSS[2] are:
* aliases: Mail aliases.
* ethers: Ethernet numbers.
* group: Groups of users.
* hosts: Host names and numbers.
* netgroup: Network wide list of host and users.
* network: Network names and numbers.
* protocols: Network protocols.

page 2 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

* passwd: User passwords.

* rpc: Remote procedure call names and numbers.
* services: Network services.
* shadow: Shadow user passwords.
Using the nss_ldap shared library it is possible to implement the mapsabove using LDAP,
anyway here I'll focus only on the LDAP implementation ofshadow, passwd and group
database tough all the maps above can be implemented.For most of the other maps it is
even unadvisable to store them in ldap, as theytend not to change too often, so it is not a
problem to have them locally as files,and storing them in ldap would cause some minor
performance loss.

2.1.3. The Lightweight Directory Access Protocol

For our application LDAP is used to provide clients with informationabout user accounts and
user groups. The standard objectclasses that are usedto represent users and groups are:
top, posixAccount, shadowAccount andposixGroup.
Users entries on the database must belong at least[3] to the top,posixAccount and
shadowAccount objectclasses. Group entries must belong to thetop and posixGroup
objectclasses.
The implementation of pam_ldap and nss_ldap that we use refers to this objectclasses,
thatare described in RFC 2307.
Note: Actually LDAP NSS recognize other objectclasses
2.1.4. The Name Service Caching Daemon
The Name Service Caching Daemon (NSCD) is used to cache name servicelookups and can
improve performance with the services provided by the NSS.
It must be tuned with a large cache for passwd entries in order to haveacceptable
performance on the client side.
It has some disadvantages however, like the introduction of cache inconsistencies,so you
would want to be sure you need this before you use it. We have succesfully runningsome
systems without it, and personally i think that it isn't really neccesary onrelatively small
systems.

2.1.5. The Secure Socket Layer

<!--
For details on SSL refer to Section 10.
-->
SSL is needed in the communication between the LDAP server and theclients libraries
(pam_ldap.so and nss_ldap.so), since sensible data, such aspassword entries, needs to be
encrypted between the client and the server. SLLalso permits the client to uniquely identify
the server, thus avoiding toobtain authentication informations from an untrusted source.
Client authentication (the server identifies the client) is not supportedin the current
implementation of pam_ldap and nss_ldap modules tough it may beuseful.

2.2. Building the authentication system

page 3 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

This section describes the steps needed to build the authentication system using the
components described in the previous section.
Figure 1. PAM Layout
image:The relationships among the pieces of the authentication system from the PAM point
of view / /data/11/PAMlayout.gif (null)
Figure 2. NSS Layout
image:The relationships among the pieces of the authentication system from the NSS
perspective / /data/11/NSSlayout.gif (null)
Though this layout may seem quite complex to implement, most of thecomponents are
already in place in a Linux system.
2.2.1. Server side
On the server side an LDAP server must be installed and configured. TheLDAP server used
is OpenLDAP, an open source LDAP toolkit including an LDAPserver (slapd), library and
utilities.
At the moment OpenLDAP comes with two implementation of LDAP: a V2implementation
(OpenLDAP 1.2.x) ad a V3 (OpenLDAP 2.0.x) implementation
The V3 implementation provides native SSL, the V2 doesn't. Anyway it ispossible to use an
SSL wrapper to add SSL capabilities to the server.
2.2.1.1. Installing and configuring OpenLDAP
You can refer to the LDAP-HOWTO for instruction on installation andconfiguration of LDAP
Once slapd is properly configured we need to insert some data for theinitial creation of the
database. Therefore an LDIF (LDAP Data interchangeformat) file must be created. This is a
text file that can be imported in theLDAP database with the command:
#ldif2ldbm -i your_file.ldif

Note: ldif2ldbm is provided with the OpenLDAP 1.2.x package, if you useOpenLDAP 2.0.x,
you should use the ldapadd command(after the server is started).
If you use OpenLDAP 2.0.x (LDAPv3) you can find the standard nis schemain the file
etc/openldap/schema/nis.schema, includeit in your slapd.conf with the include directive, to
have schemaenforcement.
Here is an example of a minimal LDIF file. Each entry isseparated by a blank line.

dn:dc=yourorg, dc=com
objectclass: top
objectclass: organizationalUnit

dn:ou=groups, dc=yourorg, dc=com

objectclass: top
objectclass: organizationalUnit
ou: groups

dn:ou=people, dc=yourorg, dc=com

objectclass: top
objectclass: organizationalUnit
ou: people

dn: cn=Giuseppe LoBiondo, ou=people, dc=yourorg, dc=com

cn: Giuseppe Lo Biondo
sn: Lo Biondo page 4 of 11
objectclass: top
objectclass: person
objectclass: posixAccount
objectclass: shadowAccount
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

Note: Note that lines that are too long are continued on the followingline started by a tab or a
space, this in true too for LDIF format files
Here we defined the base DN for the orgazationdc=yourorg,dc=comunder which are
contained two sub organizational units: peopleand groups. Then is described a user that
belongs to the people organizationalunit and a group (which the users belongs to) under the
groups organizationalunit.
Note: Useful tools to convert existing databases into ldif format areprovided by PADL and
can be found at the addressftp://ftp.padl.com/pub/MigrationTools.tar.gz.
The LDIF file must be imported in the server while it is not runningsince the ldif2ldbm
command builds the database directly, bypassing the LDAPserver. Once the LDIF file is
imported into the database, the server can bestarted.
2.2.2. Client side
On the client side pam_ldap.so and nss_ldap.so are required and theymust be compiled
using the Netscape LDAP Library (Mozilla) since it providesthe required LDAPS (LDAP over
SSL) API. The library is distributed in a binarypackage under Netscape One license and is
not open source (it is public domainanyway).
The package can be extracted, for example, in the directory /usr/local/ldapsdk.
Client libraries must also have access to a certificate databasecontaining the LDAP (stunnel)
server certificate and the CA certificate of theCA that signed the server certificate (marked as
trusted).
The certificate database must be in Netscape format since the MozillaLDAP API used to
compile pam_ldap and nss_ldap uses certificate databases inNetscape format.
To deal with such certificate databases it is convenient to use thecertutil utility found in the
PKCS#11 package provided by Netscape [4].
The main configuration file for LDAP clients is /etc/ldap.conf.
Note that if you use nss_ldap, you don't strictly need to use pam_ldap.
You can use the pam_unix_auth module instead, since nss_ldap maps allgetpw* and getsh*
calls into LDAP lookups and pam_unix_auth uses this calls toauthenticate users.
2.2.2.1. PAM LDAP Installation and Configuration
To compile and install pam_ldap, do the following:

$ ./configure --with-ldap-lib=netscape4 \
--with-ldap-dir=/usr/local/ldapsdk
$ make
# make install

The configure switch --with-ldap-lib tells which LDAP library you aregoing to use.
The switch --with-ldap-dir tells where you have installed your Netscapeldapsdk toolkit.
This will install /lib/security/pam_ldap.so.1 and thevarious symlinks.
PAM has to be properly configured in order to access the new authenticationsystem. PAM
configuration files are located in the directory /etc/pam.dand are named after the service for
whichauthentication is provided.
For example this is the PAM configuration file for the login service (in afile named login).

page 5 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

#%PAM-1.0
auth required /lib/security/pam_securetty.so
auth required /lib/security/pam_nologin.so
auth sufficient /lib/security/pam_ldap.so
auth required /lib/security/pam_unix_auth.so use_first_pass
account sufficient /lib/security/pam_ldap.so
account required /lib/security/pam_unix_acct.so
password required /lib/security/pam_cracklib.so
password sufficient /lib/security/pam_ldap.so
password required /lib/security/pam_unix_passwd.so use_first_pass md5 shadow
session required /lib/security/pam_unix_session.so

Standard PAM configuration files for use with PAM can be found in thepam_ldap source
distribution, in the directory pam_ldap-version/pam.d.
This files can be copied in the /etc/pam.ddirectory.Caution must be given when performing
this operation, since if something goeswrong you probably will not be able to login again. It is
suggested to make abackup copy of /etc/pam.dbefore installing new files thereand to leave
an open privileged shell.
Note: In the example pam.ddirectory,a sshd file is not present, so unless youcreate one, you
will be unable to login via ssh, if it uses pam (OpenSSH doesuse PAM).
2.2.2.2. NSS LDAP installation and configuration
After you've unpacked the sources, check the makefile. For mostconfigurations, it doesn't
need to be edited. Anyway, if you want to use SSLyou must link against an SSL aware LDAP
library, such as the Netscape one.
Assuming that the ldap sdk is in /usr/local/ldapsdkyou have to modify the Makefile to enable
SSL. Look for NSFLAGS in Makefile.linux.mozillaand uncomment -DSSL.
Also check the LIBS definition to see if the ldapssl library specifiedin the file is the same that
you have installed (ldap_nss.so compiles with bothlibldapssl40 and libldapssl30).
Then you can install the library:

$ make -f Makefile.linux.mozilla
# make -f Makefile.linux.mozilla install
#ldconfig

this installs /lib/libnss_ldap.so,which is the nss_ldap library, and a set of example

configuration files, /etc/nsswitch.ldap and /etc/ldap.conf, in case they do not existalready.
Once you have installed it you must edit the NSS configuration file /etc/nsswitch.conf. Tough
LDAP can be used for all theservices we use it only for passwd, group and shadow therefore
we should havesomething like:

passwd: files ldap

group: files ldap
shadow: files ldap

in the first lines of the configuration file. With this configuration,entries are first looked in the
system files and, if no value is returned, theLDAP server is queried.

page 6 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

Note: Beware when using ldap as backup for your dns lookups. If dns cannotresolve the
hostname, we're in infinite recursion, because libldap callsgethostbyname(). [ from the
nsswitch.ldap]
2.2.2.3. NSCD configuration
NSCD is already available in many Linux distributions, anyway it can befound within the GNU
C library package.
The NSCD configuration file is /etc/nscd.conf. Eachline specifies either an attribute and a
value, or an attribute, cachename, and avalue. Fields are separated either by SPACE or TAB
characters. cachename can behosts, passwd, or groups (in our case we won't cache hosts).

enable-cache passwd yes

positive-time-to-live passwd 600
negative-time-to-live passwd 20
suggested-size passwd 211
keep-hot-count passwd 20
check-files passwd yes
enable-cache group yes
positive-time-to-live group 3600
negative-time-to-live group 60
suggested-size group 211
keep-hot-count group 20
check-files group yes

Keep in mind that the nscd program caches passwd entries obtained fromLDAP.
This means that when an user is modified on the ldap server, the nscdcache remains valid.
This is avoided when using flat unix files by thecheck-files directive that invalidates the cache
when the corresponding file ismodified. Such a mechanism should be generalized, at the
moment anyway does notapply to LDAP. A way to avoid possible misalignments between the
LDAP serverand the cache is to invalidate the cache manually when updating passwd
entrieswith the command:

#nscd --invalidate=TABLE

Where TABLE can be passwd, groups or hosts.

To avoid confusion when testing, do not use nscd.
Moreover using nss and nscd will produce a lot of open filedescriptors,so is easy to run out of
available filedescriptors on the system (this can hangyour system).
You can increase the maximum number of filedescriptors in a Linux box(Kernel 2.2.x) with
something like:

#echo 16384 &#62; /proc/sys/fs/file-max

The maximum number of filedescriptors suggested for a system dependsanyway from the
configuration of your system.
2.2.2.4. LDAP client configuration file
The LDAP client configuration file /etc/ldap.confis read by pam_ldap and nss_ldap as well as
other LDAP clients. The following is anexample of how it should look like in our environment.

page 7 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

#
# $Id: section-pamnss.sgml,v 1.2 2001/03/26 16:57:07 rolek Exp $
# This is the configuration file for the LDAP nameservice
# switch library and the LDAP PAM module.
# PADL Software
# http://www.padl.com
#
# If the host and base aren't here, then the DNS RR
# _ldap._tcp.[defaultdomain]. will be resolved. [defaultdomain]
# will be mapped to a distinguished name and the target host
# will be used as the server.
#
# Your LDAP server. Must be resolvable without using LDAP.
host 192.111.111.111
#
# The distinguished name of the search base.
base dc=yourorg, dc=com
#
# The LDAP version to use (defaults to 2,
# use 3 if you are using OpenLDAP 2.0.x or Netscape Directory Server)
# ldap_version 3
#
# The distinguished name to bind to the server with.
# Optional: default is to bind anonymously.
# binddn cn=manager,dc=padl,dc=com
#
# The credentials to bind with.
# Optional: default is no credential.
#bindpw secret
#
# The port.
# Optional: default is 389. 636 is for ldaps
port 636
#
# The search scope.
#scope sub
#scope one
#scope base
#
# The following options are specific to nss_ldap.
#
# The hashing algorithm your libc uses.
# Optional: default is des
#crypt md5
#crypt sha
#crypt des
#
# The following options are specific to pam_ldap.
#
# Filter to AND with uid=%s
pam_filter objectclass=posixAccount
#
# The user ID attribute (defaults to uid)
pam_login_attribute uid
#
# Search the root DSE for the password policy (works
# with Netscape Directory Server)
#pam_lookup_policy yes
#
# Group to enforce membership of
#
#pam_groupdn cn=PAM,ou=Groups,dc=padl,dc=com
#
page 8 of 11
# Group member attribute
pam_member_attribute memberuid
# Template login attribute, default template user
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

Note: To avoid problems with the various applications that may read this fileit is suggested
not to use tabs between parameters and values, only a singlespace.
The pam_groupdn directive is useful when an LDAP server providesauthentication
information to a pool of clients, but the user should beauthorized only on a set of clients. This
directive can provide the samefunctionality of NIS netgroups.
The SSL configuration directives are not documented in the package, butthey tell to enable
SSL and where the file containing the LDAP servercertificate and the CA certificate is stored.
A Netscape certificate database named cert7.db is searched in sslpath.This file must contain
the server certificate and the CA certificate (unlessthe server certificate is self signed). There
are two ways to generate thisfile: using the Netscape PKCS#11 tools or using the Netscape
browser.
With the Netscape browser, after you have started slapd and stunnel on theserver you can
use Netscape Navigator to connect to the URLhttps://your.ldap.server:636/, you will be
prompted to insert the servercertificate in your database. Also the CA certificate (provided by
your CA) mustbe loaded in the database (unless you are using a self signed certificate).
Atthis point you can copy the $HOME/.netscape/cert7.dbin sslpath. It is preferred that you
use a scratch account witha default cert7.db file since other server certificates,that may be
present in your personal certificate database, will be considered byyour LDAP client as
trusted authentication servers. Once the browser has importedthe server certificate it can be
used to debug SSL since it will behave like thepam and nss libraries.

2.3. Starting up
On the server side you have to start slapd (the LDAP daemon process)with a command like:

# slapd

If you use stunnel, it has to be started on the LDAPS port 636:

# /usr/local/sbin/stunnel -r ldap -d 636 \

-p /usr/local/ssl/certs/stunnel.pem

If you use OpenLDAP 2.0.x, compiled with TLS (OpenSSL), you can start theserver using the
command

# slapd -h "ldap:/// ldaps:///"

On the client nscd can be started with the a startup script, usuallyfound in many Linux
distributions:

# /etc/rc.d/init.d/nscd start

If PAM and NSS are correctly configured this should be enough.

2.4. Accounts maintenance
At this point account creation and maintenance should be done using LDAPclient tools.

page 9 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

Unfortunately these general purpose tools are not intended for Un*xaccounts maintenance.
The one that seems to be enough versatile is the LDAPBrowser/Editor
(http://www-unix.mcs.anl.gov/~gawor/ldap)that allows to set passwords in various formats
and can use SSL to connect to theserver.

2.5. Known limits

As it is for NIS with a single master server (no slave servers), LDAPwithout a replication
mechanism represents a single point of failure for theauthentication system. For
authentication purposes it is rather important toimplement LDAP replication. The server that
cames with OpenLDAP (slapd) providesreplication capabilities.

2.6. File permissions

The following are the file permissions that should be applied to some ofthe files used by the
authentication system.

-rw-r--r-- root.root /etc/ldap.conf

-rw------- root.root /usr/local/etc/openldap/slapd.conf
-rwxr-xr-x root.root /lib/security/pam_ldap.so.1
-rw-r--r-- root.root /lib/libnss_ldap-2.1.2.so
-rw-r--r-- root.root /usr/local/ssl/certs/cert7.db
-rw------- root.root /usr/local/ssl/certs/stunnel.pem

Notes
[1]
A mechanism that permits LDAP database replication between servers.

[2]
It is not a case that these are the maps provided by NIS.

[3]
An entry can belong to several objectclasses.

[4]
In a tricky way, it is also possible to use the Netscape Communicator certificate database.
rate this article:
current rating:
Your rating:
Support this site

image:rdf newsfeed / //static.linuxhowtos.org/data/rdf.png (null)

|
image:rss newsfeed / //static.linuxhowtos.org/data/rss.png (null)
|
image:Atom newsfeed / //static.linuxhowtos.org/data/atom.png (null)
- Powered by
image:LeopardCMS / //static.linuxhowtos.org/data/leopardcms.png (null)
- Running on
image:Gentoo / //static.linuxhowtos.org/data/gentoo.png (null)

page 10 of 11
 http://www.linuxhowtos.org/LDAP/LDAP Implementation HOWTO.pdf

-
Copyright 2004-2020 Sascha Nitsch Unternehmensberatung GmbH
image:Valid XHTML1.1 / //static.linuxhowtos.org/data/xhtml.png (null)
:
image:Valid CSS / //static.linuxhowtos.org/data/css.png (null)
:
image:buttonmaker / //static.linuxhowtos.org/data/buttonmaker.png (null)
- Level Triple-A Conformance to Web Content Accessibility Guidelines 1.0 -
- Copyright and legal notices -
Time to create this page: ms
<!--
image:system status display / /status/output.jpg (null)
-->
bodyloaded();

page 11 of 11