Contents
Configuring LDAP Authentication
This page describes the steps needed to get user names, groups and other information that is usually stored in flat files in /etc or NIS from an LDAP server. This information is exposed through NSS (Name Services Switch) as configured in /etc/nsswitch.conf.
The following databases can be served from LDAP:
passwd (users)
aliases (mail aliases, ignored by most mail daemons)
ethers (ethernet numbers)
group (groups of users)
hosts (host names and numbers)
netgroup (host and user groups used for access controls)
networks (network names and numbers)
protocols (network protocols)
rpc (remote procedure call names and numbers)
services (network service names and numbers)
shadow (shadow user passwords).
Up to Debian 11 there were two packages available to configure NSS lookups through LDAP:
libnss-ldap (available up through Debian 11 'bullseye')
Which one to use depends on the needs. In general libnss-ldapd is simpler but newer and libnss-ldap is more mature but more complex. Also libnss-ldap has some known issues with serving host information and lookups during boot which should be addressed in libnss-ldapd. In addition, libnss-ldap breaks setuid programs (su, sudo) when using LDAP+SSL (see 579647).
NSS Setup with libnss-ldapd
libnss-ldapd was developed to fix some of the shortcomings of libnss-ldap, see the nss-ldapd homepage for more details.
Install the libnss-ldapd package.
Most of the configuration for common setups is performed during installation.
nslcd installation will ask the following questions (these settings will be stored in /etc/nslcd.conf - the service should be restarted if any changes are made to it):
the URI of the LDAP server - you should specify ldap://10.0.0.1 or whatever the IP address of your LDAP server is (it's better to avoid host names because of potential problems with DNS or other NSS modules)
the base DN of your LDAP database - eg. dc=example,dc=org
(optional) enable SSL/TLS features - eg. ssl start_tls and tls_cacertfile /etc/ssl/certs/ca-certificates.crt
- (optional) name and credentials to use to bind to the LDAP database
libnss-ldapd will ask for which services to enable LDAP lookups (you should probably select passwd, shadow and group and maybe others if you need them). These settings are stored in /etc/nsswitch.conf:
libnss-ldapd and nslcd provide reasonable defaults for most values (looking at environment and possibly existing configurations). This should be enough to enable NSS lookups through LDAP in most common cases. If you have a more unusual setup or require more configuration (e.g. SSL/TLS certificates, SASL/Kerberos configuration, etc) see #External_links
NSS Setup with libnss-ldap
Caution -- libnss-ldap is not available in Debian 12 'bookworm', given lack of maintenance upstream. See 1032123 libpam-ldap and 1024140 libnss-ldap.
Install the libnss-ldap package.
Be sure to read the docs that are installed in /usr/share/doc/libnss-ldap/
If you plan to do hostname lookups through LDAP you should add the hostname of your LDAP server in /etc/hosts (even if you use an IP address to configure the connection to the server). Without this nasty things happen on bootup as things attempt to use LDAP which recurses on itself looking up the hostname.
Edit /etc/libnss-ldap.conf to include al least the following (replace the values with options that are specific to your environment):
# Your LDAP server. Must be resolvable without using LDAP. uri ldap://10.0.0.1 # The distinguished name of the search base. base dc=<your>,dc=<domain>
If you specified rootbinddn you need to put the LDAP admin password in /etc/ldap.secret with mode 600 (rw-------).
Edit /etc/nsswitch.conf to use add LDAP to the services you want to have enabled (be careful to put LDAP *after* "files").
passwd: files ldap group: files ldap shadow: files ldap hosts: files dns ldap networks: files ldap protocols: db files services: db files ethers: db files rpc: db files netgroup: nis
Verify that NSS is operational
Check that NSS is seeing things from LDAP using getent:
# getent passwd
should show you accounts from LDAP that are not in the /etc/passwd file. Similar tests can be done with the group, shadow and other in /etc/nsswitch.conf configured databases.
Be sure to also run some tests as non-root users. Also try rebooting to see if NSS lookups are performed correctly during boot.
Note that getent shadow should only return data for root users. Also, passwords are generally not returned unless the LDAP server has been configured to return this data and are in a supported format. If pam_ldap is used (see LDAP/PAM) it is not needed to expose passwords from the LDAP server.
When using the libnss-ldapd package debugging can be done by starting nslcd (the connection daemon) in debugging mode (remember to stop nscd when debugging):
systemctl stop nscd systemctl stop nslcd nslcd -d
Further debugging can be done with the ldapsearch utility from the ldap-utils package. You can search for all the information that is available for a single user:
% ldapsearch -h <ldapserver> -b dc=<your>,dc=<domain> -x uid=<username>
Specify the -D and -W options to log in if the binddn or rootbinddn options are used.
Offline caching of NSS with nscd
While continuous LDAP connectivity can be assumed for workstations and servers in a LAN, laptop users often do not have network connectivity. From a system administrators point of view it is tempting to create local users on the laptop but this causes trouble when these laptops have to access domain resources like network shares (NFS, sshfs, Samba, etc.) back in the office (with a stable network connection). Many of these network shares rely on a central name service database like LDAP because of user and group information and permissions on the share.
nscd] is often used to cache NSS information, so that the LDAP server does not have to be queried for every request (which has also an impact on the speed of the answer). NSCD can also be used to serve these requests while there is no network connectivity. In short: NSCD is configured to cache the information much longer than the default values from Debian (Lenny)
For debugging it is recommended to not to run nscd (the Name Service Caching Daemon) because nscd can mask problems by serving entries from it's cache. Don't install nscd, or stop the service until it is clear that everything is functional:
systemctl stop nscd
However, running nscd is required when using libnss-ldap and permissions of /etc/libnss-ldap.conf do not allow normal users to read the file (e.g. when using the bindpw option). Certain versions of libnss-ldap have been known to set restrictive permissions on this file. Note that not all NSS lookups will go through nscd (only passwd, group and host) so this may not work in all circumstances.
For production use it is recommended to run nscd as it saves on doing lookups to the LDAP server.
NSCD has a configuration file /etc/nscd.conf There are two configuration options which have to be altered in order to use the pseudo-offline capability:
reload-count unlimited positive-time-to-live <service> #number of second
The positive-time-to-live has to be configured for at least the passwd and group service. To cache user and group information for 30 days, you would use:
positive-time-to-live passwd 2592000 positive-time-to-live group 2592000
You may consider decreasing the time-to-live values of the cache if you need to pick up changes in the LDAP directory quickly (though the defaults are fine in most circumstances).
Caveat: When configured for offline mode, NSCS's NSS information is not updated for a long period of time. This can be troublesome depending on the time-to-live setting, because changes in the LDAP database are not known to the system because it uses the cached information. To force a refresh of LDAP information when online, reload the service:
systemctl reload nscd
See also
nss-updatedb - alternative to nscd to maintain local caches of user and group directories
sssd - programs to manage access to remote directories and authentication, providing NSS and PAM interfaces
PAM can also be configured for offline caching of credentials, see LDAP/PAM
External links
/usr/share/doc/libnss-ldapd
CategorySoftware | CategoryNetwork | CategorySystemAdministration | CategorySystemSecurity