LDAP authentication

Introduction and Concepts

This is a guide on how to configure an Arch Linux installation to authenticate against an LDAP directory. This LDAP directory can be either local (installed on the same computer) or network (e.g. in a lab environment where central authentication is desired).

The guide will be divided in two parts. The first part deals with how to setup an OpenLDAP server that hosts the authentication directory. The second part deals with how to setup the NSS and PAM modules that are required for the authentication scheme to work on the client computers. If you just want to configure Arch to authenticated against an already existing LDAP server then you can skip to the second part.

NSS and PAM

NSS (which stands for Name Service Switch) is a system mechanism to configure different sources for common configuration databases. For example, /etc/passwd is a file type source for the passwd database.

PAM (which stands for Pluggable Authentication Module) is a mechanism used by Linux (and most *nixes) to extend its authentication schemes based on different plugins.

So to summarize, we need to configure NSS to use the OpenLDAP server as a source for the passwd, shadow and other configuration databases and then configure PAM to use these sources to authenticate it's users.

LDAP Server Setup

Installation

You can read about installation and basic configuration in the OpenLDAP article. After you have completed that, return here.

Populate LDAP Tree with Base Data

Create a file called base.ldif with the following text:

base.ldif

# example.org
dn: dc=example,dc=org
objectClass: dcObject
objectClass: organization
o: Example Organization
dc: example

# Manager, example.org
dn: cn=Manager,dc=example,dc=org
cn: Manager
description: LDAP administrator
roleOccupant: dc=example,dc=org
objectClass: organizationalRole
objectClass: top

# People, example.org
dn: ou=People,dc=example,dc=org
ou: People
objectClass: top
objectClass: organizationalUnit

# Group, example.org
dn: ou=Group,dc=example,dc=org
ou: Group
objectClass: top
objectClass: organizationalUnit

Add it to your OpenLDAP Tree:

$ ldapadd -D "cn=Manager,dc=example,dc=org" -W -f base.ldif

Test to make sure the data was imported:

$ ldapsearch -x -b 'dc=example,dc=org' '(objectclass=*)'

Adding users

To manually add a user, create an .ldif file like this:

example.ldif

dn: uid=johndoe,ou=People,dc=example,dc=org
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: shadowAccount
uid: johndoe
cn: John Doe
sn: Doe
givenName: John
title: Guinea Pig
telephoneNumber: +0 000 000 0000
mobile: +0 000 000 0000
postalAddress: AddressLine1$AddressLine2$AddressLine3
userPassword: {CRYPT}xxxxxxxxxx
labeledURI: https://archlinux.org/
loginShell: /bin/bash
uidNumber: 9999
gidNumber: 9999
homeDirectory: /home/johndoe/
description: This is an example user

the xxxxxxxxxx in the userPassword entry should be replaced with the value in /etc/shadow.

You can automatically migrate all of your local accounts (and groups, etc.) to the LDAP directory using PADL Software's Migration Tools.

Client Setup

Install the OpenLDAP client as described in OpenLDAP. Make sure you can query the server with ldapsearch.

Next, install nss-pam-ldapd^AUR from the official repositories.

NSS Configuration

NSS is a system facility which manages different sources as configuration databases. For example, /etc/passwd is a file type source for the passwd database, which stores the user accounts.

Edit /etc/nsswitch.conf which is the central configuration file for NSS. It tells NSS which sources to use for which system databases. We need to add the ldap directive to the passwd, group and shadow databases, so be sure your file looks like this:

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

Edit /etc/nslcd.conf and change the base and uri lines to fit your ldap server setup.

Restart nslcd.service.

You now should see your LDAP users when running getent passwd on the client.

Name Service Cache Daemon

You can optionally run NSCD. This is a daemon that NSS uses to cache lookups and queries for network backends. This way you can login when the LDAP server is down, it will also reduce load on the LDAP server.

Start nscd.service using systemd.

Note: It is recommended to stop the NSCD when troubleshooting because it may mask problems by serving cached queries.

PAM Configuration

The basic rule of thumb for PAM configuration is to include pam_ldap.so wherever pam_unix.so is included. If pam_unix.so is marked required, it will sometimes need to be changed to sufficient. Arch moving to pambase has helped decrease the amount of edits required.

Tip: If you want to prevent UID clashes with local users on your system, you might want to include minimum_uid=10000 or similar on the end of the pam_ldap.so lines. You'll have to make sure the ldap server returns uidNumber fields that match the restriction.

Note: Each facility (auth, session, password, account) forms a separate chain and the order matters. Rule of thumb is sufficient lines before required lines and optional lines at the end. When adding your pam_ldap.so lines, don't change the relative order of the other lines without good reason! Simply insert ldap within the chain.

Edit /etc/pam.d/system-auth.
This file is included in most of the other files in pam.d, so changes here propagate nicely. Make pam_ldap.so sufficient at the top of each section, except session which we make optional. Updates to pambase may change this file:

 auth      sufficient pam_ldap.so
 auth      required  pam_unix.so     try_first_pass nullok
 auth      optional  pam_permit.so
 auth      required  pam_env.so
 
 account   sufficient pam_ldap.so
 account   required  pam_unix.so
 account   optional  pam_permit.so
 account   required  pam_time.so
 
 password  sufficient pam_ldap.so
 password  required pam_unix.so     try_first_pass nullok sha512 shadow
 password  optional  pam_permit.so
 
 session   required  pam_limits.so
 session   required  pam_unix.so
 session   optional  pam_ldap.so
 session   optional  pam_permit.so

Edit both /etc/pam.d/su and /etc/pam.d/su-l identically.
the su-l file is used when the user runs su --login.

use_first_pass is added to pam_unix in the auth section. sufficient pam_ldap.so is added to the top of each section:

 #%PAM-1.0
 auth		sufficient	pam_ldap.so
 auth		sufficient	pam_rootok.so
 # Uncomment the following line to implicitly trust users in the "wheel" group.
 #auth		sufficient	pam_wheel.so trust use_uid
 # Uncomment the following line to require a user to be in the "wheel" group.
 #auth		required	pam_wheel.so use_uid
 auth		required	pam_unix.so use_first_pass
 account	sufficient	pam_ldap.so
 account	required	pam_unix.so
 session	sufficient	pam_ldap.so
 session	required	pam_unix.so

Resources

The official page of the nss-pam-ldapd packet

The PAM and NSS page at the Debian Wiki 1 2

Using LDAP for single authentication

Heterogeneous Network Authentication Introduction

Discussion on suse's mailing lists about nss-pam-ldapd