Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, August 8, 2018
 
 

pam_ldap(7)

Name

pam_ldap - authentication, account, and password management PAM module for LDAP

Synopsis

/usr/lib/security/pam_ldap.so.1

Description

The pam_ldap module implements pam_sm_authenticate(3PAM), pam_sm_acct_mgmt(3PAM), and pam_sm_chauthtok(3PAM) functions that provide functionality for the PAM authentication, account, and password management stacks. The pam_ldap module ties the authentication, account, and password management functionality to the functionality of the supporting LDAP server. For authentication, pam_ldap can authenticate the user directly to any LDAP directory server by using any supported authentication mechanism, such as DIGEST-MD5. However, the account management and password change component of pam_ldap will work only with the Oracle Directory Server Enterprise Edition (formerly SUN Directory Server Enterprise Edition). The server's user account management must be properly configured before it can be used by pam_ldap. Refer to the Oracle Directory Server Enterprise Edition documentation for information on how to configure user account management, including password and account lockout policy.

pam_ldap must be used in conjunction with the modules that support the UNIX authentication, credential, session, password, and account management, which are pam_authtok_check(7), pam_authtok_get(7), pam_authtok_store(7), pam_passwd_auth(7), pam_unix_account(7), pam_unix_auth(7), pam_unix_cred(7), and pam_unix_session(7). pam_ldap is designed to be stacked directly below these modules. If other modules are designed to be stacked in this manner, the modules can be stacked below the pam_ldap module. The examples section shows how the UNIX modules are stacked with pam_ldap.

When stacked together, the UNIX modules are used to control local accounts, such as root. pam_ldap is used to control network accounts, that is, LDAP users. For the stacks to work, pam_unix_auth, pam_unix_account, pam_passwd_auth, pam_authtok_check and pam_authtok_store must be configured with the binding control flag and the server_policy option. This configuration allows local account override of a network account.

LDAP Authentication Module

The LDAP authentication module verifies the identity of a user specified by PAM_USER. If PAM_AUSER and PAM_USER are both specified and PAM_USER is a role, the user_attr(5) keyword roleauth is checked to determine if the password that is checked is for the role (PAM_USER) or the assuming user (PAM_AUSER). The pam_sm_authenticate(3PAM) function uses the password entered by the user to attempt to authenticate to the LDAP server. If successful, the user is authenticated.

The authentication method used is either defined in the client profile, or the authentication method is configured by using the ldapclient(8) command. To determine the authentication method to use, this module first attempts to use the authentication method that is defined, for service pam_ldap, for example, serviceAuthenticationMethod:pam_ldap:sasl/DIGEST-MD5. If no authentication method is defined, pam_ldap uses the default authentication method. If neither are set, the authentication fails. This module skips the configured authentication method if the authentication method is set to none.

The following options can be passed to the LDAP service module:

debug

syslog(3C) debugging information at LOG_DEBUG level.

nowarn

Turn off warning messages.

These options are case sensitive and must be used exactly as presented here.

LDAP Account Management Module

The LDAP account management module validates the user's account. The pam_sm_acct_mgmt(3PAM) function authenticates to the LDAP server to verify that the user's password has not expired, or that the user's account has not been locked. In the event that there is no user authentication token (PAM_AUTHTOK) available, the pam_sm_acct_mgmt(3PAM) function attempts to retrieve the user's account status without authenticating to the LDAP server as the user logging in. This procedure will succeed only if the LDAP server is Sun Java System Directory server 5.2 patch 4 or newer (currently referred as Oracle Directory Server Enterprise Edition). The following options can be passed to the LDAP service module:

debug

syslog(3C) debugging information at LOG_DEBUG level.

nowarn

Turn off warning messages.

These options are case sensitive, and the options must be used exactly as presented here.

LDAP Password Management Module

There are multiple ways to configure password management for LDAP. Each uses pam_authtok_store(7) to actually update the password. Password qualification may be done with pam_authtok_check(7) for local password policy and/or directly by the directory server when the password change is requested by pam_authtok_store(7). The pam_user_policy(7) file ldap configures for local qualification and can be configured for directory server qualification as well. The following options may be passed to the LDAP service module:

debug

syslog(3C) debugging information at LOG_DEBUG level.

These options are case sensitive, and the options must be used exactly as presented here.

Errors

The authentication service returns the following error codes:

PAM_SUCCESS

The authentication was successful.

PAM_MAXTRIES

The maximum number of authentication attempts was exceeded.

PAM_AUTH_ERR

The authentication failed.

PAM_USER_UNKNOWN

No account is present for the user.

PAM_BUF_ERR

A memory buffer error occurred.

PAM_SYSTEM_ERR

A system error occurred.

PAM_IGNORE

The user's account was inactivated.

The account management service returns the following error codes:

PAM_SUCCESS

The user was allowed access to the account.

PAM_NEW_AUTHTOK_REQD

A new authentication token is required.

PAM_ACCT_EXPIRED

The user account has expired.

PAM_PERM_DENIED

The user was denied access to the account at this time.

PAM_USER_UNKNOWN

No account is present for the user.

PAM_BUF_ERROR

A memory buffer error occurred.

PAM_SYSTEM_ERR

A system error occurred.

Examples

Example 1 Using pam_ldap With Authentication

The following PAM stack is for authenticating with the login service when using pam_ldap with /etc/pam.conf for PAM configuration. Lines that begin with the # symbol are comments and are ignored.

# Authentication management for login service is stacked.
# If pam_unix_auth succeeds, pam_ldap is not invoked.
# The control flag "binding" provides a local overriding
# remote (LDAP) control. The "server_policy" option is used
# to tell pam_unix_auth.so.1 to ignore the LDAP users.

login   auth requisite  pam_authtok_get.so.1
login   auth required   pam_dhkeys.so.1
login   auth required   pam_unix_cred.so.1
login   auth binding    pam_unix_auth.so.1 server_policy 
login   auth required   pam_ldap.so.1 

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/ login:

auth requisite  pam_authtok_get.so.1
auth required   pam_dhkeys.so.1
auth required   pam_unix_cred.so.1
auth binding    pam_unix_auth.so.1 server_policy
auth required   pam_ldap.so.1
Example 2 Using pam_ldap With Account Management

The following PAM stack is for account management when using pam_ldap for PAM services which are not explicitly listed in the PAM configuration using /etc/pam.conf for PAM configuration. Lines that begin with the # symbol are comments and are ignored.

# Account management for all services is stacked
# If pam_unix_account succeeds, pam_ldap is not invoked.
# The control flag "binding" provides a local overriding
# remote (LDAP) control. The "server_policy" option is used
# to tell pam_unix_account.so.1 to ignore the LDAP users.

other   account  requisite      pam_roles.so.1
other   account  binding        pam_unix_account.so.1 server_policy
other   account  required       pam_ldap.so.1

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/other:

account requisite      pam_roles.so.1
account binding        pam_unix_account.so.1 server_policy
account required       pam_ldap.so.1
Example 3 Using pam_authtok_store With Password Management For Both Local and LDAP Accounts

The following PAM stacks are for password management using pam_authtok_store when the PAM configuration is in /etc/pam.conf both local (/etc/default/passwd) and, if configured, directory server password qualification is desired. Lines that begin with the # symbol are comments and are ignored.

# Password management (authentication)
# The control flag "binding" provides a local overriding
# remote (LDAP) control. The server_policy option is used
# to tell pam_passwd_auth.so.1 to ignore the LDAP users.

passwd  auth binding  pam_passwd_auth.so.1 server_policy
passwd  auth required pam_ldap.so.1

# Password management (updates)
# This updates passwords stored both in the local /etc
# files and in the LDAP directory. The "server_policy"
# option is used to tell pam_authtok_store to
# follow the LDAP server's policy when updating
# passwords stored in the LDAP directory

other password requisite  pam_authtok_get.so.1
other password requisite  pam_authtok_check.so.1
other password required   pam_authtok_store.so.1 server_policy

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/passwd:

auth binding  pam_passwd_auth.so.1 server_policy
auth required pam_ldap.so.1

And, the following entries in /etc/pam.d/other:

password requisite pam_authtok_get.so.1
password requisite pam_authtok_check.so.1
password required pam_authtok_store.so.1 server_policy

The following PAM stacks are for password management using pam_authtok_store when the PAM configuration is in /etc/pam.conf and only directory server password qualification is desired. Lines that begin with # are comments and ignored.

# Password management (authentication)
# The control flag "binding" provides a local overriding
# remote (LDAP) control. The server_policy option is used
# to tell pam_passwd_auth.so.1 to ignore the LDAP users.

passwd  auth binding  pam_passwd_auth.so.1 server_policy
passwd  auth required pam_ldap.so.1

# Password management (updates)
# This updates passwords stored both in the local /etc
# files and in the LDAP directory. The "server_policy"
# option is used to tell pam_authtok_store to
# follow the LDAP server's policy when updating
# passwords stored in the LDAP directory

other password requisite  pam_authtok_get.so.1
other password requisite  pam_ldap.so.1
other password required   pam_authtok_store.so.1 server_policy

The equivalent PAM configuration in /etc/pam.d/ would be the following entries in /etc/pam.d/passwd:

auth binding  pam_passwd_auth.so.1 server_policy
auth required pam_ldap.so.1

And, the following entries in /etc/pam.d/other:

password requisite pam_authtok_get.so.1
password requisite pam_ldap.so.1
password required pam_authtok_store.so.1 server_policy
Example 4 Using pam_user_policy to Configure pam_ldap

The pam_user_policy(7) PAM module can be configured to refer to the supplied /etc/security/pam_policy/ldap file which uses pam_ldap for authentication, account management, and password management for LDAP users and Unix for authentication, account management, and password management for Unix users.

The following command assigns the /etc/security/pam_policy/ldap file to user maria as the PAM policy:

# usermod -K pam_policy=ldap maria

To configure the PAM policy system-wide, the PAM_POLICY key in policy.conf(5) can be edited to specify the name of a PAM policy file in /etc/security/pam_policy or an absolute path to a PAM policy file. For more information, see pam_user_policy(7).

Files

/var/ldap/ldap_client_file
/var/ldap/ldap_client_cred

The LDAP configuration files of the client. Do not manually modify these files, as these files might not be human readable. Use ldapclient(8) to update these files.

/etc/pam.conf

PAM configuration file.

/etc/pam.d/service

Alternate PAM configuration files.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe with exceptions

See Also

syslog(3C), libpam(3LIB), pam_sm_setcred(3PAM), pam(3PAM), pam_sm_acct_mgmt(3PAM), pam_sm_authenticate(3PAM), pam_sm_chauthtok(3PAM), pam_sm_close_session(3PAM), pam_sm_open_session(3PAM), pam.conf(5), attributes(7), ldap(7), pam_authtok_check(7), pam_authtok_get(7), pam_authtok_store(7), pam_passwd_auth(7), pam_unix_account(7), pam_unix_auth(7), pam_user_policy(7), idsconfig(8), ldap_cachemgr(8), ldapclient(8)

Notes

The interfaces in libpam(3LIB) are MT-Safe only if each thread within the multi-threaded application uses its own PAM handle.

The functions: pam_sm_setcred(3PAM), pam_sm_open_session(3PAM), and pam_sm_close_session(3PAM) do nothing and return PAM_IGNORE in pam_ldap.