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.
Note that if you are using Debian, you should be able to just install the libnss-ldapd and libpam-ldapd packages, answer the configuration questions and have it just work. Also see the Debian wiki for more information.
This guide covers the most common configurations but nss-pam-ldapd also supports TLS encryption, Kerberos authentication, using Active Directory and much more. See the sample configuration, manual pages and other sources 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. to import existing information into an LDAP server look into MigrationTools.
This document also assumes that the information may be queried from the system you want to install nss-pam-ldapd on. You can use tools such as ldapsearch to verify that information can be retrieved.
Step 1: Installing nss-pam-ldapd
Note that 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.
% 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
(if you're using Debian this will be done at installation time and you will be prompted for the correct values for the configuration)/etc/nslcd.conf
The source package includes an annotated template configuration file for the nslcd daemon. Also, a manual page for the /etc/nslcd.conf file is available.
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. Also set the uid and gid options as descibed in step 1. For most other options the defaults should be fine in most set-ups. A minimal configuration would contain:
base dc=example,dc=com
uid nslcd
gid nslcd
After modifying /etc/nslcd.conf you should (re)start nslcd.
/etc/nsswitch.conf
Modify /etc/nsswitch.conf to include ldap for 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 (files or in some cases compat). Your /etc/nsswitch.conf will contain something like:
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 pam_ldap.so minimum_uid=1000 use_first_pass
auth required pam_deny.so
account required pam_unix.so
account sufficient pam_ldap.so minimum_uid=1000
account required pam_permit.so
session required pam_unix.so
session optional pam_ldap.so minimum_uid=1000
password sufficient pam_unix.so nullok md5 shadow use_authtok
password sufficient pam_ldap.so minimum_uid=1000 try_first_pass
password required pam_deny.so
Note that are a lot of 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 LDAP entries.
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 (the connection daemon) in debugging mode (remember to stop nscd when debugging). Debugging mode should return a lot of information about the LDAP queries that are performed and errors that may rise.
# /etc/init.d/nslcd stop
# nslcd -d
Miscellaneous notes
- For most configurations it is recommended to run nscd. 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.
I don't consider this to be a good idea because:
- it is a lot less flexible since that limits you to the password schemes that are supported by pam_unix instead of that in the server and
- the authentication is done on the client instead of on the server which exposes the 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.