'\" te
.\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_LDAP 7 "August 19, 2023"
.SH NAME
pam_ldap \- authentication and account management PAM module for LDAP
.SH SYNOPSIS
.nf
\fBpam_ldap.so.1\fR
.fi

.SH DESCRIPTION
The \fBpam_ldap\fR module implements \fBpam_sm_authenticate\fR(3PAM) and
\fBpam_sm_acct_mgmt\fR(3PAM), the functions that provide functionality for the
PAM authentication and account management stacks. The \fBpam_ldap\fR module
ties the authentication and account management functionality to the
functionality of the supporting LDAP server. For authentication, \fBpam_ldap\fR
can authenticate the user directly to any LDAP directory server by using any
supported authentication mechanism, such as \fBDIGEST-MD5\fR. However, the
account management component of \fBpam_ldap\fR 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 \fBpam_ldap\fR. Refer to the \fISun Java
System Directory Server Administration Guide\fR for information on how to
configure user account management, including password and account lockout
policy.
.sp
.LP
\fBpam_ldap\fR must be used in conjunction with the modules that support the
UNIX authentication, password, and account management, which are
\fBpam_authtok_get\fR(7), \fBpam_passwd_auth\fR(7), \fBpam_unix_account\fR(7),
and \fBpam_unix_auth\fR(7). \fBpam_ldap\fR 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 \fBpam_ldap\fR module. The
Examples section shows how the UNIX modules are stacked with \fBpam_ldap\fR.
When stacked together, the UNIX modules are used to control local accounts,
such as \fBroot\fR. \fBpam_ldap\fR is used to control network accounts, that
is, LDAP users. For the stacks to work, \fBpam_unix_auth\fR,
\fBpam_unix_account\fR, and \fBpam_passwd_auth\fR must be configured with the
\fBbinding\fR control flag and the \fBserver_policy\fR option. This
configuration allows local account override of a network account.
.SS "LDAP Authentication Module"
The LDAP authentication module verifies the identity of a user. The
\fBpam_sm_authenticate\fR(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.
.sp
.LP
The authentication method used is either defined in the client profile, or the
authentication method is configured by using the \fBldapclient\fR(8) command.
To determine the authentication method to use, this module first attempts to
use the authentication method that is defined, for service \fBpam_ldap\fR, for
example, \fBserviceAuthenticationMethod:pam_ldap:sasl/DIGEST-MD5\fR. If no
authentication method is defined, \fBpam_ldap\fR 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 \fBnone\fR.
.sp
.LP
The following options can be passed to the LDAP service module:
.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.na
\fB\fBnowarn\fR\fR
.ad
.RS 10n
Turn off warning messages.
.RE

.sp
.LP
These options are case sensitive and must be used exactly as presented here.
.SS "LDAP Account Management Module"
The LDAP account management module validates the user's account. The
\fBpam_sm_acct_mgmt\fR(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
(\fBPAM_AUTHTOK\fR) available, the \fBpam_sm_acct_mgmt\fR(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:
.sp
.ne 2
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.na
\fB\fBnowarn\fR\fR
.ad
.RS 10n
Turn off warning messages.
.RE

.sp
.LP
These options are case sensitive, and the options must be used exactly as
presented here.
.SS "LDAP Password Management Module"
LDAP password management is no longer supported by \fBpam_ldap\fR. Use
\fBpam_authtok_store\fR(7) instead of \fBpam_ldap\fR for password change.
\fBpam_authtok_store\fR(7) handles both the local and LDAP accounts and updates
the passwords in all the repositories configured by \fBnsswitch.conf\fR(5).
.SH ERRORS
The authentication service returns the following error codes:
.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 20n
The authentication was successful.
.RE

.sp
.ne 2
.na
\fB\fBPAM_MAXTRIES\fR\fR
.ad
.RS 20n
The maximum number of authentication attempts was exceeded.
.RE

.sp
.ne 2
.na
\fB\fBPAM_AUTH_ERR\fR\fR
.ad
.RS 20n
The authentication failed.
.RE

.sp
.ne 2
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 20n
No account is present for the user.
.RE

.sp
.ne 2
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 20n
A memory buffer error occurred.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 20n
A system error occurred.
.RE

.sp
.ne 2
.na
\fB\fBPAM_IGNORE\fR\fR
.ad
.RS 20n
The user's account was inactivated.
.RE

.sp
.LP
The account management service returns the following error codes:
.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 24n
The user was allowed access to the account.
.RE

.sp
.ne 2
.na
\fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR
.ad
.RS 24n
A new authentication token is required.
.RE

.sp
.ne 2
.na
\fB\fBPAM_ACCT_EXPIRED\fR\fR
.ad
.RS 24n
The user account has expired.
.RE

.sp
.ne 2
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.RS 24n
The user was denied access to the account at this time.
.RE

.sp
.ne 2
.na
\fB\fBPAM_USER_UNKNOWN\fR\fR
.ad
.RS 24n
No account is present for the user.
.RE

.sp
.ne 2
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 24n
A memory buffer error occurred.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 24n
A system error occurred.
.RE

.SH EXAMPLES
\fBExample 1 \fRUsing \fBpam_ldap\fR With Authentication\fB\fR
.sp
.LP
The following is a configuration for the login service when using
\fBpam_ldap\fR. The service name \fBlogin\fR can be substituted for any other
authentication service such as \fBdtlogin\fR or \fBsu\fR. Lines that begin with
the # symbol are comments and are ignored.

.sp
.in +2
.nf
# 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
.fi
.in -2

.LP
\fBExample 2 \fRUsing \fBpam_ldap\fR With Account Management
.sp
.LP
The following is a configuration for account management when using
\fBpam_ldap\fR. Lines that begin with the # symbol are comments and are
ignored.

.sp
.in +2
.nf
# 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
.fi
.in -2

.LP
\fBExample 3 \fRUsing \fBpam_authtok_store\fR With Password Management For Both
Local and LDAP Accounts
.sp
.LP
The following is a configuration for password management when using
\fBpam_authtok_store\fR. Lines that begin with the # symbol are comments and
are ignored.

.sp
.in +2
.nf
# 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
.fi
.in -2

.SH FILES
.ne 2
.na
\fB\fB/var/ldap/ldap_client_file\fR\fR
.ad
.br
.na
\fB\fB/var/ldap/ldap_client_cred\fR\fR
.ad
.RS 30n
The LDAP configuration files of the client. Do not manually modify these files,
as these files might not be human readable. Use \fBldapclient\fR(8) to update
these files.
.RE

.sp
.ne 2
.na
\fB\fB/etc/pam.conf\fR\fR
.ad
.RS 30n
PAM configuration file.
.RE

.SH ATTRIBUTES
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT-Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.BR ldap (1),
.BR syslog (3C),
.BR libpam (3LIB),
.BR pam (3PAM),
.BR pam_sm_acct_mgmt (3PAM),
.BR pam_sm_authenticate (3PAM),
.BR pam_sm_chauthtok (3PAM),
.BR pam_sm_close_session (3PAM),
.BR pam_sm_open_session (3PAM),
.BR pam_sm_setcred (3PAM),
.BR pam.conf (5),
.BR attributes (7),
.BR pam_authtok_check (7),
.BR pam_authtok_get (7),
.BR pam_authtok_store (7),
.BR pam_passwd_auth (7),
.BR pam_unix_account (7),
.BR pam_unix_auth (7),
.BR idsconfig (8),
.BR ldap_cachemgr (8),
.BR ldapclient (8)
.SH NOTES
The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
multi-threaded application uses its own \fBPAM\fR handle.
.sp
.LP
The previously supported \fBuse_first_pass\fR and \fBtry_first_pass\fR options
are obsolete in this version, are no longer needed, can safely be removed from
\fBpam.conf\fR(5), and are silently ignored. They might be removed in a future
release. Password prompting must be provided for by stacking
\fBpam_authtok_get\fR(7) before \fBpam_ldap\fR in the \fBauth\fR and
\fBpassword\fR module stacks and \fBpam_passwd_auth\fR(7) in the \fBpasswd\fR
service \fBauth\fR stack (as described in the EXAMPLES section). The previously
supported password update function is replaced in this release by the
previously recommended use of \fBpam_authtok_store\fR with the
\fBserver_policy\fR option (as described in the EXAMPLES section).
.sp
.LP
The functions: \fBpam_sm_setcred\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM),
\fBpam_sm_open_session\fR(3PAM), and \fBpam_sm_close_session\fR(3PAM) do
nothing and return \fBPAM_IGNORE\fR in \fBpam_ldap\fR.