HomePLDAP
 

PAM PLDAP - Building and Configuration

Requirements

In time, pldap will be compiled and tested against a number of different LDAP servers and operating systems. Currently, the module has only been tested against OpenLDAP in the Linux PAM subsystem. The module has been run within Debian (Sarge) and Redhat Fedora Core 3.

Building

Once you have downloaded the pldap bundle, building is a standard configure/make/make install process. Currently the only pldap specific options to configure is --with-openldap=^lt;dir>, which defines the installation directory for OpenLDAP. You will need to ensure your install prefix (--prefix\) is set correctly for the OS.

Note

If you do not run configure as configure --prefix=... you will find that the pldap module (pam_pldap.so) will be installed into /usr/local/lib/security. For most systems, PAM cannot find a module in this directory - it must be installed in the correct directory for the OS. On Linux this is /lib/security. On FreeBSD it is /usr/lib (which you will have to place by hand, as the current installer doesn't realise this) and NetBSD and Solaris use usr/lib/security (--prefix=/usr).

Configuring PAM

How you configure PAM will depend on your system. PAM files are generally held in /etc/pam.d/, with one file per service that will use PAM (e.g. /etc/pam.d/ssh for the ssh service). Some linux distributions (such as Debian and Redhat) have created common configuration files that other service files can reference, and you can define your pldap configuration options there.

For each element of PAM (Authentication/Authorisation/Session Management/Password Change) that you want to use PLDAP for, you will need to add the appropriate entry in the appropriate configuration file. For example, if you have a configuration for service "myservice", then the file might be configured as : 

# For Authentication, using pldap and fallback to /etc/passwd

auth sufficient pam_pldap.so tls userdn=uid=%s,ou=People,dc=wingsofhermes,dc=org
auth required   pam_unix.so use_first_pass

# For Authorisation
account sufficient pam_pldap.so 
     group_filter=(&(cn=permitted_users)
                    (uniqueMember=%s,ou=People,dc=wingsofhermes,dc=org)) 
     base=dc=wingsofhermes,dc=org 
account required   pam_unix.so

# For Session Management
session sufficient pam_pldap.so
session required   pam_unix.so

# For Password Management
account sufficient pam_pldap.so userdn=uid=%s,ou=People,dc=wingsofhermes,dc=org
account required   pam_unix.so md5

Note

In the above example, some of the text has been wrapped for readability - the PAM configuration requires that everything to do with a particular configuration statement be on the line. In particular, ensure that the "account sufficient pam_pldap.so ..." configuration is not split onto multiple lines.

PLDAP options

There are a number of options available to the pam_pldap.so module. They can be used (without error) for any of the calls to pam_pldap, but they are not always applicable. In addition, options "carry". For example, if you have used pam_pldap for both authentication and authorisation within SSH, an initial logon will first call the authentication processes and then authorisation. Any arguments that you used for the authentication call (such as tls) will also be used for the authorisation call.

Warning

Use this with care!. You are not always guaranteed that a particular application will call one PAM function followed by another. It is always better to duplicate configuration items for all PAM configuration statements!

The pam_pldap.so options are as follows :

Option Useability Description
host=<server name or IP> auth
account
session
password		 Defines the server on which the LDAP server resides. This is only needed if the client libraries cannot find the info via the system configuration files (e.g ldap.conf for the OpenLDAP client libraries).
tls auth
account
session
password		 Activates TLS (Transport Layer Security) for this session. Options for TLS must be set in your ldap.conf file so that the OpenLDAP client libraries will read the correct certificate and use the appropriate cipher specs.

Note This is currently only supported for the OpenLDAP client libraries. Support for SSL/TLS is not yet configured in for the Solaris LDAP libraries.
base=<string> auth
account		 Tells pldap what the base should be for any searches that it needs to perform.

For example :

base=dc=wings,dc=org
userdn=<format string> auth
account
password		 Tells pldap how to map a unix userid (e.g. "fred") to a Distinguished Name (e.g. uid=fred,dc=wings,dc=org).

Any occurences of %u are replaced by the userid, so for the example used, the option would be :

userdn=uid=%u,dc=wings,dc=org
group_filter=<format string> account This option provides a search filter that pldap should use to determine whether the user is permitted to access this system. As with userdn any occurrences of %u are replaced with the user's id.

When attempting to authorise, pldap will first check any shadow information. If this is OK, pldap will then look to see if this option has been defined. If it has, pldap will parse the format string, replacing any occurences of %u with the userid. Finally, pldap will search the directory, using the string determined in the previous steps as the search filter. (The base can be set using the base option.)

If the search returns any results, the user is considered to be authorised.

This is a fairly powerful mechanism. It allows the system administrator to search multiple groups, with different member attributes to determine whether a user is permitted to access the system.

An example of this option, where a user must be a member of the POSIX group permitted would be :

group_filter=(&(cn=permitted)(memberUid=%u))
debug auth
account
session
password		 A standard PAM option that activates debugging output from the module. All debugging messages will be sent to the syslog service.
use_first_pass auth A standard PAM option that requests the module first check a password that might have been entered by a module further up the PAM stack.
md5 auth Requires new passwords be stored in the directory using the crypt MD5 format.