Tribblix: manual page: pam

PAM_LDAP(7) Standards, Environments, and Macros PAM_LDAP(7)

NAME

pam_ldap - authentication and account management PAM module for LDAP

SYNOPSIS

pam_ldap.so.1

DESCRIPTION

The pam_ldap module implements pam_sm_authenticate(3PAM) and
pam_sm_acct_mgmt(3PAM), the functions that provide functionality for
the PAM authentication and account management stacks. The pam_ldap
module ties the authentication and account 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
component of pam_ldap will work only with the Sun Java System
Directory Server. The server's user account management must be
properly configured before it can be used by pam_ldap. Refer to the
Sun Java System Directory Server Administration Guide 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, password, and account management, which are
pam_authtok_get(7), pam_passwd_auth(7), pam_unix_account(7), and
pam_unix_auth(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, and pam_passwd_auth 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. 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. See NOTES for information on password
prompting.

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. 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

LDAP password management is no longer supported by pam_ldap. Use
pam_authtok_store(7) instead of pam_ldap for password change.
pam_authtok_store(7) handles both the local and LDAP accounts and
updates the passwords in all the repositories configured by
nsswitch.conf(5).

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_ERR
A memory buffer error occurred.

PAM_SYSTEM_ERR
A system error occurred.

EXAMPLES

Example 1: Using pam_ldap With Authentication

The following is a configuration for the login service when using
pam_ldap. The service name login can be substituted for any other
authentication service such as dtlogin or su. 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

Example 2: Using pam_ldap With Account Management

The following is a configuration for account management when using
pam_ldap. 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

Example 3: Using pam_authtok_store With Password Management For Both

Local and LDAP Accounts

The following is a configuration for password management when using
pam_authtok_store. 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 required pam_dhkeys.so.1
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

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.

ATTRIBUTES

NOTES

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

The previously supported use_first_pass and try_first_pass options
are obsolete in this version, are no longer needed, can safely be
removed from pam.conf(5), and are silently ignored. They might be
removed in a future release. Password prompting must be provided for
by stacking pam_authtok_get(7) before pam_ldap in the auth and
password module stacks and pam_passwd_auth(7) in the passwd service
auth stack (as described in the EXAMPLES section). The previously
supported password update function is replaced in this release by the
previously recommended use of pam_authtok_store with the
server_policy option (as described in the EXAMPLES section).

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

August 19, 2023 PAM_LDAP(7)