14.10. Using PAM for Pass-Through Authentication

Pass-through authentication is when any authentication request is forwarded from one server to another service.
Many systems already have authentication mechanisms in place for Unix and Linux users. One of the most common authentication frameworks is Pluggable Authentication Modules (PAM). Since many networks already existing authentication services available, administrators may want to continue using those services. A PAM module can be configured to tell Directory Server to use an existing authentication store for LDAP clients.
PAM pass-through authentication in Red Hat Directory Server uses the PAM Pass-Through Authentication Plug-in, which enables the Directory Server to talk to the PAM service to authenticate LDAP clients.
PAM Pass-Through Authentication Process

Figure 14.3. PAM Pass-Through Authentication Process

Note

PAM pass-through authentication works together with account inactivation when authenticating users, assuming that the appropriate mapping method (ENTRY) is used. However, PAM pass-through authentication does not validate passwords against password policies set either globally or locally, because the passwords are set and stored in the PAM module, not in the Directory Server.

14.10.1. PAM Pass-Through Authentication Configuration Options

PAM pass-through authentication is configured in child entries beneath the PAM Pass-Through Authentication plug-in container entry. There can be multiple PAM pass-through authentication policies, applied to different suffixes or to different entries within suffixes.
There are several different areas that can be configured for PAM pass-through:
  • The suffixes that are controlled by the PAM pass-through authentication plug-in. This covers suffixes to exclude, suffixes to include, and how to handle a missing suffix.
  • Individual entries within the configured suffixes which are the target of the authentication configuration. By default, all entries within a suffix are included in the authentication scope, but it is possible to configure multiple, different PAM Pass-Through Auth plug-in instances and then apply different plug-in configuration to different users.
  • The PAM attribute mapping. The credentials that are offered to the Directory Server have to be mapped in some way to an LDAP entry and then, back to the credentials in the PAM service. This is done by defining a mapping method and then, optionally, which LDAP attribute to use to match the credentials.
  • General configuration such as using SSL connections, the PAM service to use, and whether to fallback to LDAP authentication if PAM authentication fails.

Note

There can be multiple configuration instances of the PAM Pass-Through Authentication plug-in. An instance of the PAM Pass-Through Authentication plug-in can be applied to a subset of user entries by using the pamFilter attribute to set an LDAP filter to search for the specific entries to use with the plug-in.

Table 14.8. PAM Pass-Through Auth Plug-in Attributes

Attribute Definition
pamExcludeSuffix Identifies suffixes to exclude from PAM authentication.
pamIncludeSuffix Identifies suffixes to include for PAM authentication.
pamMissingSuffix Identifies how to handle missing include or exclude suffixes. The options are ERROR (which causes the bind operation to fail); ALLOW, which logs an error but allows the operation to proceed; and IGNORE, which allows the operation and does not log any errors.
pamFilter Sets an LDAP filter to use to identify specific entries within the included suffixes for which to use PAM pass-through authentication. If not set, all entries within the suffix are targeted by the configuration entry.
pamIDAttr Sets the name of the attribute holding the PAM ID.
pamIDMapMethod Gives the method to use to map the LDAP bind DN to a PAM identity.

Note

Directory Server user account inactivation is only validated using the ENTRY mapping method. With RDN or DN, a Directory Server user whose account is inactivated can still bind to the server successfully.
pamFallback Sets whether to fallback to regular LDAP authentication if PAM authentication fails.
pamSecure Requires secure (TLS/SSL) connection for PAM authentication.
pamService Contains the service name to pass to PAM. This assumes that the service specified has a configuration file in /etc/pam.d.

Important

The pam_fprintd.so module cannot be in the configuration file referenced by the pamService attribute of the PAM Pass-Through Authentication Plug-in configuration. Using the PAM fprintd module causes the Directory Server to hit the max file descriptor limit and can cause the Directory Server process to abort.
nsslapd-pluginConfigArea Specifies a different container entry to use as the parent for PAM pass-through authentication child entries. By default, the PAM Pass-Through Auth Plug-in entry is used as the parent entry for the configuration entries. This is set in the PAM Pass-Through Auth Plug-in entry.
If a different container entry is used, then all PAM pass-through authentication child entries must be located beneath that container entry.
All child entries in the specified location must belong to the pamConfig object class, but neither the container entry nor the PAM Pass-Through Auth Plug-in entry must belong to the pamConfig object class in that case.

14.10.1.1. Specifying the Suffixes to Target for PAM PTA

The PAM PTA plug-in is applied globally, to all suffixes, by default unless they are explicitly excluded. Excluding and including suffixes can help target what areas in the directory use PAM authentication instead of LDAP authentication.

Note

The target of a PAM pass-through authentication entry must be a suffix, not an arbitrary subtree. As described in Section 2.1, “Creating and Maintaining Suffixes”, a suffix is a subtree which is associated with a specific back end database, such as cn=config which is associated with NetscapeRoot or the root suffix dc=example,dc=com which is associated with userRoot.
The pamExcludeSuffix attribute excludes a suffix. By default, only the configuration subtree (cn=config) is excluded. Alternatively, the PAM PTA plug-in can be applied to a suffix with the pamIncludeSuffix attribute. Both of these attributes are multi-valued.
If the include attribute is set, for example, all other suffixes are automatically excluded. Likewise, if an exclude attribute is set, all other suffixes are automatically included. 
pamExcludeSuffix: cn=config
pamExcludeSuffix: o=NetscapeRoot
With pamIncludeSuffix, only the given suffix is included and all others are automatically excluded. Since this attribute is multi-valued, more than one suffix can be included in the PAM evaluation by explicitly listing the suffixes. 
pamIncludeSuffix: ou=Engineering,dc=example,dc=com
pamIncludeSuffix: ou=QE,dc=example,dc=com
The pamMissingSuffix attribute tells the server how to handle a failure if the specified suffix (include or exclude) does not exist. If it is set to IGNORE, then if the suffix does not exist, the plug-in simply skips that suffix and tries the next. 
pamMissingSuffix: IGNORE
pamIncludeSuffix: ou=Engineering,dc=example,dc=com
pamIncludeSuffix: ou=Not Real,dc=example,dc=com

14.10.1.2. Applying Different PAM Pass-Through Authentication Configurations to Different Entries

By default, a PAM pass-through authentication policy applies to all entries within the designated suffixes. However, it is possible to specify an LDAP filter in the pamFilter attribute which identifies specific entries within the suffix to which to apply the PAM pass-through authentication policy.
This is useful for applying different PAM configurations or mapping methods to different user types, using multiple PAM pass-through authentication policies.

14.10.1.3. Setting PAM PTA Mappings

There has to be a way to connect the LDAP identity to the PAM identity. The first thing to define is the method to use to map the entries. There are three options: DN, RDN, and ENTRY. ENTRY uses a user-defined attribute in the entry.
Multiple mapping methods can be supplied in an ordered, space-separated list. The plug-in attempts to use each mapping method in the order listed until authentication succeeds or until it reaches the end of the list.
For example, this mapping method first maps the RDN method, then ENTRY, then DN, in the order the methods are listed: 
pamIDMapMethod: RDN ENTRY DN
The different mapping methods are listed in Table 14.9, “Mapping Methods for PAM Authentication”.

Note

Directory Server user account inactivation is only validated using the ENTRY mapping method. With RDN or DN, a Directory Server user whose account is inactivated can still bind to the server successfully.

Table 14.9. Mapping Methods for PAM Authentication

Mapping Description
RDN This method uses the value from the leftmost RDN in the bind DN. The mapping for this method is defined by Directory Server. This is the default mapping method, if none is given.
ENTRY This method pulls the value of the PAM identity from a user-defined attribute in the bind DN entry. The identity attribute is defined in the pamIDAttr attribute. 
pamIDAttr: customPamUid
DN This method uses the full distinguished name from the bind DN. The mapping for this method is defined by Directory Server.

14.10.1.4. Configuring General PAM PTA Settings

Three general configuration settings can be set for PAM authentication:
  • The service name to send to PAM (pamService); this is the name of the configuration file to use in /etc/pam.d
  • Whether to require a secure connection (pamSecure)
  • Whether to fall back to LDAP authentication if PAM authentication fails (pamFallback) 
pamFallback: false
pamSecure: false
pamService: ldapserver

14.10.2. Configuring PAM Pass-Through Authentication

Note

There can be multiple configuration instances of the PAM Pass-Through Authentication plug-in. An instance of the PAM Pass-Through Authentication plug-in can be applied to a subset of user entries by using the pamFilter attribute to set an LDAP filter to search for the specific entries to use with the plug-in.
PAM pass-through authentication is configured through the command line.
  1. Make sure the PAM service is fully configured.
  2. Remove the pam_fprintd.so module from the PAM configuration file.

    Important

    The pam_fprintd.so module cannot be in the configuration file referenced by the pamService attribute of the PAM Pass-Through Authentication Plug-in configuration. Using the PAM fprintd module causes the Directory Server to hit the max file descriptor limit and can cause the Directory Server process to abort.
  3. Enable the plug-in; this is disabled by default. 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=PAM Pass-Through Auth Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
  4. Create the PAM Pass-Through Auth plug-in configuration entry. 
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=Admin PAM PTA Config,cn=PAM Pass-Through Auth Plugin,cn=plugins,cn=config
cn: AD PAM PTA Config
  5. Add the attributes available for the PAM plug-in. The available attributes are listed in Table 14.8, “PAM Pass-Through Auth Plug-in Attributes”, and Example 14.1, “Example PAM Pass-Through Authentication Configuration Entry” has an example entry.
  6. Restart the server to load the new plug-in configuration. 
    service dirsrv restart

Example 14.1. Example PAM Pass-Through Authentication Configuration Entry

 dn: cn=Admin PAM PTA Config,cn=PAM Pass Through Auth,cn=plugins,cn=config
 objectclass: top
 objectclass: pamConfig
 objectClass: nsSlapdPlugin
 objectClass: extensibleObject
 cn: Admin PAM PTA Config
 pamMissingSuffix: ALLOW
 pamExcludeSuffix: cn=config  
 pamExcludeSuffix: o=NetscapeRoot  
 pamIDMapMethod: RDN ENTRY  
 pamIDAttr: customPamUid  
 pamFilter: (manager=uid=bjensen,ou=people,dc=example,dc=com)  
 pamFallback: FALSE
 pamSecure: TRUE  
 pamService: ldapserver

14.10.3. Using PAM Pass-Through Authentication with Active Directory as the Backend

PAM pass-through authentication forwards the credentials from the Directory Server to the PAM service. One option is to set up and configure PAM modules specifically for Directory Server. Another option — and one which may be more repeatable and more convenient in some infrastructures — is to use the System Security Services Daemon (SSSD) to configure PAM. Because SSSD can use a variety of different identity stores, a lot of different servers or services can be used to provide credentials, including Active Directory.
Using pass-through authentication through SSSD is a daisy chain of services. The PAM PTA Plug-in is configured as normal. It points to the given PAM service file to use. This service file is managed by SSSD, and SSSD is configured to connect with whatever identity provider is required, even multiple providers.
PAM Pass-Through Authentication with SSSD

Figure 14.4. PAM Pass-Through Authentication with SSSD

For more information on SSSD, see the Red Hat Enterprise Linux 6 Deployment Guide.
To configure PAM pass-through authentication with Active Directory:
  1. Configure SSSD to use the Active Directory server as one of its identity providers.
    This configuration is covered in the Red Hat Enterprise Linux 6 Deployment Guide.
  2. Enable the PAM Pass-Through Auth plug-in; this is disabled by default. 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=PAM Pass-Through Auth Plugin,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
  3. Create the PAM Pass-Through Auth plug-in configuration entry. 
    ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=AD PAM PTA Config,cn=PAM Pass-Through Auth Plugin,cn=plugins,cn=config
cn: AD PAM PTA Config
  4. Set the pamService attribute to point to the PAM configuration file managed by SSSD. By default, this is /etc/pam.d/system-auth. 
    pamService: system-auth

    Important

    The pam_fprintd.so module cannot be in the configuration file referenced by the pamService attribute of the PAM Pass-Through Authentication Plug-in configuration. Using the PAM fprintd module causes the Directory Server to hit the max file descriptor limit and can cause the Directory Server process to abort.
  5. Configure the ID map method and attribute. There are several options for how this can be done, depending on the Directory Server environment.
    The simplest is to use the RDN map method, which automatically uses the uid attribute (or the correct naming attribute) to map Directory Server users back to Active Directory users (since Active Directory is the identity provider). 
    pamIDMapMethod: RDN
    Similarly, this can be accomplished with the ENTRY map method by using the samAccountName attribute. If the user accounts in Directory Server are created with uids that match the samAccountName value for the user account in Active Directory, then the mapping is successful. 
    pamIDMapMethod: ENTRY
pamIDAttr: samAccountName
    If Windows synchronization is configured, then the ENTRY method can be used with the ntUserDomainId attribute. The Directory Server and Active Directory user accounts are already synced, based on that attribute value, so the PAM mapping is successful. 
    pamIDMapMethod: ENTRY
pamIDAttr: ntUserDomainId
  6. Restart the server to load the plug-in configuration. 
    service dirsrv restart