'\" te
.\" Copyright (c) 2005, 2014, Oracle and/or its affiliates. All rights reserved.
.TH pam_ldap 5 "11 Mar 201" "SunOS 5.11" "Standards, Environments, and Macros"
.SH NAME
pam_ldap \- authentication, account, and password management PAM module for LDAP
.SH SYNOPSIS
.LP
.nf
\fB/usr/lib/security/pam_ldap.so.1\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpam_ldap\fR module implements \fBpam_sm_authenticate\fR(3PAM), \fBpam_sm_acct_mgmt\fR(3PAM), and \fBpam_sm_chauthtok\fR(3PAM) functions that provide functionality for the PAM authentication, account, and password management stacks. The \fBpam_ldap\fR module ties the authentication, account, and password 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 and password change component of \fBpam_ldap\fR 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 \fBpam_ldap\fR. Refer to the Oracle Directory Server Enterprise Edition documentation 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, credential, session, password, and account management, which are \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5), \fBpam_unix_cred\fR(5), and \fBpam_unix_session\fR(5). \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.
.sp
.LP
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, \fBpam_passwd_auth\fR, \fBpam_authtok_check\fR and \fBpam_authtok_store\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"
.sp
.LP
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.
.sp
.LP
The authentication method used is either defined in the client profile, or the authentication method is configured by using the \fBldapclient\fR(1M) 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
.mk
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
.rt  
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.mk
.na
\fB\fBnowarn\fR\fR
.ad
.RS 10n
.rt  
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"
.sp
.LP
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 (currently referred as Oracle Directory Server Enterprise Edition). The following options can be passed to the LDAP service module:
.sp
.ne 2
.mk
.na
\fB\fBdebug\fR\fR
.ad
.RS 10n
.rt  
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.ne 2
.mk
.na
\fB\fBnowarn\fR\fR
.ad
.RS 10n
.rt  
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"
.sp
.LP
There are multiple ways to configure password management for LDAP. Each uses \fBpam_authtok_store\fR(5) to actually update the password. Password qualification may be done with \fBpam_authtok_check\fR(5) for local password policy and/or directly by the directory server when the password change is requested by \fBpam_authtok_store\fR(5). The \fBpam_user_policy\fR(5) file \fBldap\fR 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:
.sp
.ne 2
.mk
.na
\fB\fBdebug\fR\fR
.ad
.RS 9n
.rt  
\fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
.RE

.sp
.LP
These options are case sensitive, and the options must be used exactly as presented here.
.SH ERRORS
.sp
.LP
The authentication service returns the following error codes:
.sp
.ne 2
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 20n
.rt  
The authentication was successful.
.RE

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

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

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

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

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

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

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

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

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

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

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

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

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

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBpam_ldap\fR With Authentication\fB\fR
.sp
.LP
The following PAM stack is for authenticating with the login service when using \fBpam_ldap\fR with \fB/etc/pam.conf\fR for PAM configuration. Lines that begin with the \fB#\fR 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

.sp
.LP
The equivalent PAM configuration in \fB/etc/pam.d/\fR would be the following entries in \fB/etc/pam.d/\fR login:

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

.LP
\fBExample 2 \fRUsing \fBpam_ldap\fR With Account Management
.sp
.LP
The following PAM stack is for account management when using \fBpam_ldap\fR for PAM services which are not explicitly listed in the PAM configuration using \fB/etc/pam.conf\fR for PAM configuration. Lines that begin with the \fB#\fR 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

.sp
.LP
The equivalent PAM configuration in \fB/etc/pam.d/\fR would be the following entries in \fB/etc/pam.d/other\fR:

.sp
.in +2
.nf
account requisite      pam_roles.so.1
account binding        pam_unix_account.so.1 server_policy
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 PAM stacks are for password management using \fBpam_authtok_store\fR when the PAM configuration is in \fB/etc/pam.conf\fR both local (\fB/etc/default/passwd\fR) and, if configured, directory server password qualification is desired. Lines that begin with the \fB#\fR 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 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

.sp
.LP
The equivalent PAM configuration in \fB/etc/pam.d/\fR would be the following entries in \fB/etc/pam.d/passwd\fR:

.sp
.in +2
.nf
auth binding  pam_passwd_auth.so.1 server_policy
auth required pam_ldap.so.1
.fi
.in -2

.sp
.LP
And, the following entries in \fB/etc/pam.d/other\fR:

.sp
.in +2
.nf
password requisite pam_authtok_get.so.1
password requisite pam_authtok_check.so.1
password required pam_authtok_store.so.1 server_policy
.fi
.in -2

.LP
\fBExample 4 \fRUsing \fBpam_user_policy\fR(5) to Configure \fBpam_ldap\fR
.sp
.LP
The \fBpam_user_policy\fR(5) PAM module can be configured to refere the supplied \fB/etc/security/pam_policy/ldap_server_qualification\fR file which uses \fBpam_ldap\fR for authentication, account management, and password management for LDAP users and Unix for authentication, account management, and password management for Unix users.

.sp
.LP
The following command assigns the \fB/etc/security/pam_policy/ldap\fR file to user \fBmaria\fR as the PAM policy: 

.sp
.in +2
.nf
# \fBusermod -K pam_policy=ldap maria\fR
.fi
.in -2
.sp

.sp
.LP
To configure the PAM policy system-wide, the \fBPAM_POLICY\fR key in \fBpolicy.conf\fR(4) can be edited to specify the name of a PAM policy file in \fB/etc/security/pam_policy\fR or an absolute path to a PAM policy file. For more information, see \fBpam_user_policy\fR(5).

.SH FILES
.sp
.ne 2
.mk
.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
.rt  
The LDAP configuration files of the client. Do not manually modify these files, as these files might not be human readable. Use \fBldapclient\fR(1M) to update these files.
.RE

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

.sp
.ne 2
.mk
.na
\fB\fB/etc/pam.d/\fIservice\fR\fR\fR
.ad
.RS 30n
.rt  
Alternate PAM configuration files.
.RE

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBidsconfig\fR(1M), \fBldap_cachemgr\fR(1M), \fBldapclient\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM), \fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM), \fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C), \fBpam.conf\fR(4), \fBattributes\fR(5), \fBldap\fR(5), \fBpam_authtok_check\fR(5), \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5)
.SH NOTES
.sp
.LP
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 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.