LDAP Authentication, Part Three

Managing users on a network is a whole lot simpler with LDAP. Part Three: Configuring LDAP clients.

This month is the last part of a three-part series on using the Lightweight Directory Access Protocol (LDAP) to manage accounts for a network of users. (See Part One and Part Two.) The previous two columns covered basic LDAP configuration, migrating an existing Linux account database to LDAP, and managing accounts in an LDAP directory. This time, let’s look at how to configure LDAP clients. This process involves setting up the Name Service Switch (NSS) and Pluggable Authentication Modules (PAM) to use LDAP in addition to the local Linux authentication tools. (In theory, you could use LDAP exclusively; however, in most cases it’s best to have at least some accounts defined locally.)

You should review the previous two columns in this series to refamiliarize yourself with the terminology and procedures before proceeding with this month’s column. Ensure that your LDAP server is running; this month’s column requires that the LDAP server be operational. You will, however, be performing most of the actions described this month on other computers. (You can, if you like, configure the LDAP server computer as described here, simply to gain access to the LDAP account directory.)

The Roles of NSS and PAM

Most people give little thought to the details of how Linux accounts are structured. In fact, there are several characteristics of accounts, such as usernames, passwords, home directories, default shells, and so on. These features are managed by two Linux tools:

PAM is a security tool; it tells login tools, such as the text-mode login process or the GUI GNOME Display Manager (GDM) or KDE Display Manager (KDM), that the password a user types is (or is not) correct for the specified username. PAM also handles some additional tasks, such as changing passwords when a user runs the passwd utility.

NSS handles less sensitive account data, such as the path to a user’s home directory, his or her default shell, and so on.

If you configure PAM but not NSS to use LDAP, only users who have local account data stored in /etc/passwd and /etc/shadow will be able to log in. These files could lack passwords, but they’d have to host the normal NSS data.

If you configure NSS but not PAM to use LDAP, then Linux will believe it has accounts for the users defined on the LDAP server, but those users won’t be able to log in. Thus, to use an LDAP server for authentication, you must normally reconfigure both PAM and NSS to use LDAP. Either alone could be useful in some limited circumstances, but in most cases you must configure both to use LDAP.

Setting Basic LDAP Client Options

Before proceeding with NSS and PAM configuration, you must set a few client-wide LDAP options. To do so, you should first ensure that the PAM and NSS LDAP libraries are installed on your client computer. These tools are usually stored in packages called pam_ldap and nss_ldap, although some distributions use other names, such as libpam-ldap and libnss-ldap. Some distributions combine both packages into one — nss_ldap in the case of Fedora Core 6, for instance.

In most cases, the LDAP client tools for NSS and PAM both rely on the /etc/ldap.conf file. Debian and its derivative distributions use two files, /etc/nss_ldap.conf and /etc/pam_ldap.conf. If your distribution uses two files, you must make similar changes to both. Be sure not to confuse this file with the /etc/openldap/ldap.conf, which is the configuration file for the LDAP tools described last month.

To proceed, load your /etc/ldap.conf file into an editor and change the host and base lines:

base dc=luna,dc=edu

The host line specifies the LDAP server’s IP address or hostname, so modify it to suit your network’s neeeds. The base line points to the base directory used by your LDAP account directory. As described two months ago, this is often related to your domain name, but it need not be.

You may want to peruse additional options in the /etc/ldap.conf file. Many default files include commented-out options related to port numbers, encryption, and other features. In a high-security environment, you may want to enable some of these options. Doing so can improve security, but these features can be difficult to debug.

Setting NSS Options

Telling NSS to use LDAP is fairly straightforward. The main NSS configuration file is /etc/nsswitch.conf, and you must edit three lines to have NSS use LDAP. These lines begin with the words passwd, shadow, and group, and you should add the string ldap to each of these lines:

passwd:  files  ldap
shadow:  files  ldap
group:   files  ldap

In practice, NSS uses each of the named subsystems in the order in which they’re listed for the duties specified by the leading keyword. You may have noticed that each of these lines begins with the name of a file that’s used in Linux account management: /etc/passwd, /etc/shadow, and /etc/group. This is because NSS ordinarily accesses these files (hence the files keyword). By adding ldap to the end of the line, you direct NSS to use the local files first and then to call on LDAP. Thus, when reconfigured in this way, your system will include all the locally-defined accounts and groups, plus whatever accounts or groups are defined in the LDAP directory.

It’s possible that your configuration will include other keywords, in addition to or instead of the files keyword that’s common to the lines in this example. For instance, many systems use compat rather than files. If so, the safest approach is usually to add ldap to the end of each line.

Setting PAM Options

PAM is a more complex subsystem than NSS to configure as an LDAP authentication client. As noted earlier, PAM stands for Pluggable Authentication Modules. The modules referred to in the name are pieces of code, similar to libraries or kernel modules, that extend PAM to handle new authentication methods. The PAM LDAP package you installed earlier provides an LDAP module for PAM; this module” talks” to the LDAP server, providing an interface between the LDAP server and the local computer’s authentication system.

The main PAM configuration file is /etc/pam.conf; however, all common Linux distributions place the bulk of the PAM configuration in files within the /etc/pam.d directory. Each file in this directory controls one authentication tool.

For instance, /etc/pam.d/login controls the login process, /etc/pam.d/gdm controls the GDM GUI login tool, and /etc/pam.d/su controls the su command’s authentication. In theory, to configure PAM to use LDAP, you must modify the files for each subsystem that should use LDAP. Precisely which files and subsystems this should be can vary greatly from one computer to another; for instance, you might need to modify files for a Post Office Protocol (POP) email server on one computer, but for GDM on another computer.

Fortunately, many Linux distributions provide a shortcut: /etc/pam.d/system-auth. Not all distributions use this file, but if yours does, you can modify just this one file rather than modifying all the relevant authentication programs’ files. Whether you need to modify the system-auth file or multiple files, though, the procedure is similar.

PAM authentication files consist of stacks, which are sets of external modules that provide authentication services. These stacks are broken into four management groups: auth, account, password, and session. Each management group’s stack defines the rules that PAM uses to perform a specific action, such as authenticate a user (auth) or manage a login session (session). A typical authentication stack resembles Listing One, which is based on a Gentoo PAM stack. (Some lines have been broken for publication.)

Listing One: A typical PAM authentication stack


auth required pam_env.so
auth sufficient pam_unix.so likeauth \
auth required pam_deny.so

account required pam_unix.so

password required pam_cracklib.so retry=3
password sufficient pam_unix.so nullok md5 \
shadow use_authtok
password required pam_deny.so

session required pam_limits.so
session required pam_unix.so

To add LDAP authentication to the mix, you must add a reference to the LDAP authentication module (pam_ldap.so) to each of the management groups. To do so, though, you must first understand a bit about how PAM processes its stacks.

When it’s called upon to perform an action, such as authenticate a user or change a password, PAM calls each of the modules (in the third column of Listing One) for the associated management group in turn. Ultimately, the action will succeed or fail, and which happens depends on the successful completion of each module in conjunction with the control flag in the second column of Listing One. Of most importance are the requisite, required, and sufficient flags:

  • A requisite flag means that the module must succeed if the stack is to succeed. If the module fails, stack execution terminates immediately.

  • A required flag is much like a requisite flag, but if the module fails, execution continues until the end.

  • A sufficient flag causes stack execution to immediately terminate with a successful outcome if the associated module succeeds, provided no previous required module failed. If a sufficient module fails, the stack as a whole could still succeed, if other modules cause it to succeed — that is, a module failure causes the stack to work as if the sufficient module has not been present in the stack.

The default stacks provided with most Linux distributions rely heavily on requisite or required flags, with an occasional sufficient flag thrown in; Listing One is a typical example. To add LDAP authentication while keeping local authentication working, you must add references to the pam_ldap.so module as sufficient. You must also usually change some of the requisite or required modules to be sufficient. The result might resemble Listing Two.

Listing Two: A PAM authentication stack that uses LDAP


auth required pam_env.so
auth sufficient pam_unix.so likeauth \
auth sufficient pam_ldap.so \
auth required pam_deny.so

account sufficient pam_unix.so
account sufficient pam_ldap.so

password required pam_cracklib.so retry=3
password sufficient pam_unix.so nullok md5 \
shadow use_authtok
password sufficient pam_ldap.so use_authtok \
password required pam_deny.so

session required pam_limits.so
session sufficient pam_unix.so
session sufficient pam_ldap.so use_first_pass

session required pam_mkhomedir.so \
skel=/etc/skel umask=0027

In this example, Listing One uses the pam_unix.so module to perform the key tasks for each of the four management groups; however, some distributions use other modules instead of pam_unix.so, so you may need to do some research on your distribution’s PAM defaults.

To add LDAP to the mix, you add its line after the pam_unix.so line and, if pam_unix.so is set to be requisite or required, change it to sufficient. Alternatively, you could add pam_ldap.so to the stack before the requisite or required module; pam_ldap.so, if successful, will then bypass the requisite or required module. You may also need to add a reference to pam_deny.so to the auth and password stacks; if you don’t, the stack may incorrectly indicate success even when an incorrect password is entered. (You may need to test both ways, as described shortly.)

The pam_ldap.so lines in Listing Two include parameters that vary from one management group to another. These parameters tweak the module’s behavior. For instance, the try_first_pass and use_first_pass options tell the module to try the password collected on behalf of the first authentication tool. Without these options, users may be prompted for their passwords twice when they have only LDAP accounts.

Listing Two’s final line is a new one that’s unrelated to LDAP, but that’s very useful for network logins: The pam_mkhomedir.so module automatically creates a new home directory for a user if one doesn’t already exist. You can call this module as part of the session management group, using options as shown in Listing Two to specify template files and permissions. Of course, this tool is most useful on workstations or computers that should have home directories. You might not need it for all systems.

Remember to make changes either to the /etc/pam.d/system-auth file or to the configuration files for all of the authentication tools you want to use LDAP. Note that if you modify individual configuration files, not all files use all of the management groups shown in Listing One and Listing Two, so you might not need to make all of the changes shown in Listing Two.

Testing Proper Functioning

Once you’ve made your changes, you should test them. Try using each authentication tool to log in using several different types of accounts and procedures:

  • Use a real local account with a correct password

  • Use a real local account with an incorrect password

  • Use a real LDAP account with a correct password

  • Use a real LDAP account with an incorrect password

  • Use an account that exists in neither the local account database nor LDAP

You should see the correct login behavior in each of these cases. If you see authentication failures when you type the correct password or, worse in some ways, authentication successes when you use an incorrect password or a non-existent account, you should review your configuration. Unfortunately, there’s little standardization between Linux distributions concerning their default PAM configurations, so the changes that work for one distribution might not work for another. You may need to experiment or look for distribution-specific documentation to help fill in the gaps.

Be sure to test every authentication tool, or at least every one you’ve altered to use LDAP. The passwd utility deserves special mention: If you change the /etc/pam.d/passwd configuration file, or if it uses the system-auth stack, users who use the passwd command to change their passwords should change their passwords in the local database, in the LDAP directory, or in both, depending on precisely how you’ve configured PAM. Check both the local database and LDAP to be sure that the changes have been made as you expect.

Comments on "LDAP Authentication, Part Three"


Great writeup!

Thank you for putting PAM and NSS into layman’s terms. The ldap books I’ve read never made it that clear.

Keep ‘em coming!


I see a lot of guide how to configure LDAP client and no one do it so clear so simple like this article.


Great articles!

One thought, though: What if the network is down? (or if you’re on a notebook)

Can the PAM/LDAP solution hold some kind of local password cache or do you need to define all “off-line” accounts locally on the computer?


Thank you for the auspicious writeup. It in fact was a amusement account it. Look advanced to more added agreeable from you! By the way, how can we communicate?


I will immediately grasp your rss as I can’t find your e-mail subscription link or newsletter service. Do you’ve any? Please allow me recognize in order that I could subscribe. Thanks.


Every once in a when we select blogs that we read. Listed beneath would be the most recent web pages that we pick out.


Always a significant fan of linking to bloggers that I adore but don?t get a whole lot of link appreciate from.


Here are a number of the web-sites we suggest for our visitors.


Perfect answer! That really gets to the heart of it! You nailed it!


Articles like these put the consumer in the driver seat-very important. Help avoid purchasing a dangerous used vehicle!


You’ve really helped me understand the used car buying process. Buying a vehicle report is important!


Calling all cars, calling all cars, we’re ready to make a deal.


God help me, I put aside a whole afternoon to figure this out.


This does look promising. I’ll keep coming back for more.


This is the ideal answer. Everyone should read this. Do not buy a salvage car, run a vehicle report!


Leave a Reply

Your email address will not be published. Required fields are marked *


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>