Connect Linux Servers to LDAP Directory

This guide walks you through connecting Linux servers to an LDAP directory for centralized user authentication and authorization. You’ll configure the system to authenticate users against an LDAP server (like OpenLDAP or Active Directory), enabling single sign-on and centralized account management. Before starting, ensure you have root or sudo access on the Linux server, the LDAP server’s hostname or IP address, the base DN (distinguished name) of your directory, and credentials for a read-only bind account (or the admin DN if you need to configure TLS).

What You’ll Need

A Linux server (Ubuntu/Debian or RHEL/CentOS/Fedora) with internet access or local repositories configured.
The LDAP server address (e.g., ldap.example.com or 192.168.1.10) and port (default 389 for LDAP, 636 for LDAPS).
The Base DN of your directory (e.g., dc=example,dc=com).
Bind DN and password for a read-only account (e.g., cn=readonly,dc=example,dc=com).
If using TLS, the CA certificate of your LDAP server (or the server’s certificate if self-signed).
Root or sudo access on the Linux server.

Step-by-Step

Update your system and install required packages.
- On Debian/Ubuntu: sudo apt update && sudo apt install -y libnss-ldap libpam-ldap ldap-utils
- On RHEL/CentOS/Fedora: sudo dnf install -y openldap-clients nss-pam-ldapd (or yum on older versions).
Configure LDAP client settings.
- Edit /etc/ldap/ldap.conf (or /etc/openldap/ldap.conf on RHEL) to set the base and URI. Add or uncomment lines:
```
BASE dc=example,dc=com
URI ldap://ldap.example.com
```
  If using LDAPS, use ldaps://ldap.example.com and optionally set TLS_CACERT /etc/ssl/certs/ca-certificates.crt (or the path to your CA).
Configure NSS (Name Service Switch) to use LDAP.
- Edit /etc/nsswitch.conf. Look for lines starting with passwd, group, and shadow. Add ldap to the list. For example:
```
passwd: files ldap
group: files ldap
shadow: files ldap
```
Configure PAM (Pluggable Authentication Modules) to authenticate against LDAP.
- On Debian/Ubuntu, run sudo pam-auth-update and check the box for “LDAP Authentication” (and optionally “LDAP Profile” for home directory creation).
- On RHEL/CentOS, edit /etc/pam.d/system-auth (or password-auth) and add pam_ldap.so lines. Typically, add after the pam_unix.so lines:
```
auth        sufficient    pam_ldap.so use_first_pass
account     sufficient    pam_ldap.so
password    sufficient    pam_ldap.so use_authtok
session     optional      pam_ldap.so
```
Set LDAP server details for NSS and PAM.
- On Debian/Ubuntu, the installer may ask for LDAP URI, base DN, and bind credentials. If not, edit /etc/ldap/nss-ldap.conf (or /etc/ldap/ldap.conf for PAM). Set:
```
uri ldap://ldap.example.com
base dc=example,dc=com
binddn cn=readonly,dc=example,dc=com
bindpw your_password
```
- On RHEL/CentOS, edit /etc/nslcd.conf (if using nslcd) or /etc/ldap.conf. Set similar parameters.
Enable and start the nslcd service (if installed).
- On Debian/Ubuntu with nslcd: sudo systemctl enable nslcd && sudo systemctl start nslcd
- On RHEL/CentOS with nslcd: sudo systemctl enable nslcd && sudo systemctl start nslcd
Test LDAP connectivity.
- Use ldapsearch to verify you can query the directory: ldapsearch -x -H ldap://ldap.example.com -b dc=example,dc=com -D cn=readonly,dc=example,dc=com -w your_password. You should see entries returned.
Test user authentication.
- Try to log in as an LDAP user via SSH or su. For example: ssh ldapuser@localhost (if SSH is configured to allow password auth). You can also use getent passwd ldapuser to see if the user is resolved.
Optional: Configure TLS for secure LDAP.
- Copy the CA certificate to /etc/ssl/certs/ and update ldap.conf to use ldaps:// or ldap:// with TLS_REQCERT allow (or demand for strict verification).
Optional: Enable automatic home directory creation.
- Install libpam-mkhomedir (Debian/Ubuntu) or oddjob-mkhomedir (RHEL). Then add session required pam_mkhomedir.so skel=/etc/skel umask=0022 to the session section of your PAM configuration (e.g., /etc/pam.d/common-session on Debian).

Common Mistakes

Incorrect Base DN – Using the wrong base DN (e.g., missing the dc= parts) will result in no users being found.
Wrong NSS order – If files comes before ldap and a local user has the same name as an LDAP user, the local one takes precedence. Ensure ldap is included and in the desired order.
Binding with a non-existent account – If the bind DN or password is wrong, authentication will fail silently. Double-check credentials.
Firewall blocking port 389/636 – Ensure the LDAP port is open on both server and client.
Ignoring TLS certificate errors – If you don’t configure TLS properly, some clients may fail to connect. Use TLS_REQCERT allow for testing, but switch to demand in production.

Tips

Use a dedicated read-only bind account instead of the admin DN to minimize security risks.
Test with a single user before rolling out to all servers.
Keep your LDAP client configuration in a version-controlled file (e.g., using Ansible or Puppet) for consistency across servers.
If you use Active Directory, consider using SSSD (System Security Services Daemon) instead of nslcd for better performance and features like caching.
Enable caching (e.g., nscd) to reduce LDAP load and speed up lookups.

Troubleshooting

No users found with getent passwd – Check nsswitch.conf for the ldap entry. Test with ldapsearch to ensure the server is reachable and the base DN is correct. Check nslcd status: systemctl status nslcd.
Authentication fails even though ldapsearch works – Verify PAM configuration. Check logs in /var/log/auth.log (Debian) or /var/log/secure (RHEL). Look for errors like “LDAP connection failed” or “invalid credentials”. Ensure the bind DN has permission to read user passwords (usually not needed if using PAM’s binddn).
SSH login hangs – This often indicates a network issue or LDAP server not responding. Check if the server is reachable and if DNS resolution works. Also, ensure that the SSH server allows password authentication (or keyboard-interactive).
Home directory not created – If you enabled mkhomedir, ensure the PAM session line is in the correct file (e.g., common-session on Debian) and that the module is installed.
LDAP connection refused – Check if the LDAP server is listening on the expected port. Use telnet ldap.example.com 389 or nc -vz ldap.example.com 389. Also check firewall rules.

Frequently Asked Questions

Can I use Active Directory as the LDAP server?

Yes, Active Directory supports LDAP. You’ll need to set the base DN to your domain (e.g., dc=example,dc=com) and use a user account that can read directory information. For better integration, consider using SSSD with the AD provider.

Do I need to configure TLS?

It’s strongly recommended, especially if LDAP traffic traverses untrusted networks. Without TLS, credentials are sent in plaintext. You can use LDAPS (port 636) or STARTTLS on port 389.

How do I allow LDAP users to log in via SSH?

By default, SSH uses PAM, so if PAM is configured correctly, LDAP users should be able to log in. Ensure that PasswordAuthentication is set to yes in /etc/ssh/sshd_config (or use public key authentication).

What if a local user has the same username as an LDAP user?

The NSS order determines which one is used. If files comes first, the local user takes precedence. You can change the order to put ldap first, but be careful: this could lock you out if the LDAP server is down.

Can I cache LDAP credentials to allow offline logins?

Yes, using SSSD with the cache_credentials = True option allows users to log in even when the LDAP server is unreachable, as long as they have logged in before.

How do I troubleshoot LDAP authentication issues?

Check the system logs (/var/log/auth.log or /var/log/secure), run ldapsearch manually, and test with getent passwd. Use strace on the login process if needed, but usually logs are sufficient.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →