Arthur de Jong

Open Source / Free Software developer

LDAP authentication with nss-pam-ldapd

This document describes how users and groups that are defined in an LDAP server can log in to your system. Whether a user is known to the system is managed through an NSS module and the authentication is done with a PAM module.

If you are using Debian you should be able to skip these steps, install the libnss-ldapd and libpam-ldapd packages, answer the configuration questions and have it just work. See the Debian wiki for more information. Other distributors may also provide helper tools for configuring nss-pam-ldapd.

This guide covers the most common configurations but nss-pam-ldapd also supports TLS encryption, authenticating to the LDAP server using Kerberos, using Active Directory and much more. See the sample configuration, manual pages and included README for more details.

Before you begin

This guide assumes that you have an LDAP server set up and working and have the relevant data available in there (searchable with ldapsearch). You need the following information:

  • ldap server URI (e.g. ldap://
  • ldap server search base (e.g. dc=example,dc=com)

To import existing data into LDAP look into MigrationTools.

Step 1: Installing nss-pam-ldapd

If your distribution comes with a packaged version of nss-pam-ldapd you should probably use that instead of compiling by hand. Compiling from source follows the usual procedure. You can pass --help to configure for more options.

% ./configure
% make
% make install

Create a dedicated user and group for running nslcd and configure those in /etc/nslcd.conf (uid and gid options). Also set up an init script to start nslcd at boot.

Step 2: Configuration


The source package includes an annotated template configuration file for the nslcd daemon. Also, a nslcd.conf(5) manual page is available that lists all the options.

At the very least the uri (the location of the LDAP server) option should be set. It is recommended to also set the base option to the LDAP search base of the server. Set the uid and gid options to the created user and group. For other options the defaults should be fine in most set-ups.
A minimal configuration would contain:

uri ldap://
base dc=example,dc=com
uid nslcd
gid nslcd

After making any modifications to /etc/nslcd.conf the nslcd daemon should be (re)started.


Add ldap to at least the passwd, group and shadow maps. Whether you should also change the other maps depends on the information in your LDAP directory. You should include ldap after local lookups.

It is better to use files than compat unless you use the special +/- syntax in /etc/passwd or are also using NIS. Your /etc/nsswitch.conf will contain something like:

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

/etc/pam.conf or /etc/pam.d/*

To enable logins using both LDAP and local users (e.g. you want to keep root logins) you should edit files under /etc/pam.d (or /etc/pam.conf if your system uses that). Everywhere that pam_unix is called you should also call pam_ldap. A very basic snippet is included below.

auth      sufficient
auth      sufficient minimum_uid=1000 use_first_pass
auth      required

account   required
account   sufficient minimum_uid=1000
account   required

session   required
session   optional minimum_uid=1000

password  sufficient nullok md5 shadow use_authtok
password  sufficient minimum_uid=1000 try_first_pass
password  required

There are many different ways to configure PAM and the above is only a suggestion.

Step 3: Test and troubleshoot

To ensure that everything is working correctly you can run getent passwd. This should return users from LDAP. As root, getent shadow should also return information from LDAP.

To test authentication log in with an LDAP user. One way to do that is to run su - USER as a normal user (where USER is an LDAP user) or su - nobody -c 'su - USER' as root.

To troubleshoot problems you can run nslcd in debug mode (remember to stop nscd when debugging). Debug mode should return a lot of information about the LDAP queries that are performed and errors that may arise.

# /etc/init.d/nscd stop
# /etc/init.d/nslcd stop
# nslcd -d

Miscellaneous notes

  • For most configurations it is recommended to run nscd (or unscd). This should reduce the load on the LDAP server. However, for debugging it is recommended to stop nscd because it may return cached entries instead of actual data.
  • An alternative to using an LDAP PAM module is to expose the userPassword attribute through LDAP in shadow entries. This is in general a bad idea because:
    1. it limits you to the password hashing schemes that are supported by pam_unix
    2. the authentication is done on the client instead of on the server and exposes hashed password to the client (and possibly over the network).
  • You may need to set "UsePAM yes" in /etc/ssh/sshd_config for PAM authentication in sshd to work.

Manual pages and more information