Ubuntu Manpage: pam_ldap - LDAP pluggable authentication module

Provided by: libpam-ldap_184-8.5ubuntu3_amd64

NAME

       pam_ldap - LDAP pluggable authentication module

DESCRIPTION

The pam_ldap module is a Pluggable Authentication Module (PAM) which provides for
authentication, authorization and password changing against LDAP servers.

Features of the PADL pam_ldap module include support for transport layer security, SASL
authentication, directory server-enforced password policy, and host- and group- based
logon authorization.

The present version of pam_ldap supports AIX 5L, FreeBSD 3.x and above, HP-UX 11i, IRIX
6.x, Linux, Mac OS X 10.2 and above, and Solaris 2.6 and above. Many vendors provide their
own LDAP authentication providers, often also called pam_ldap. This manual page applies
to the PADL pam_ldap module only. If you are using a vendor provided module, consult the
relevant documentation instead.

When authenticating or authorizing a user, pam_ldap first maps the user's login name to a
distinguished name by searching the directory server. This must be possible using the
local system's identity, specified in ldap.conf. (Note that presently only simple
authentication is supported for authenticating in this initial step.)

To authenticate a user, pam_ldap attempts to bind to the directory server using the
distinguished name of the user (retrieved previously). Both simple and SASL authentication
mechanisms are supported; in the former case, one should take care to use transport
security to prevent the user's password being transmitted in the clear.

A variety of authorization primitives are supported by pam_ldap, discussed in the
configuration section below.

Finally, pam_ldap supports a number of password change protocols used by directory servers
from various vendors. (Some directory servers support more than one password change
protocol.)

Whilst pam_ldap is generally configured in the system LDAP naming configuration file
(ldap.conf), some options can be configured in the PAM configuration file, to allow for
per-service granularity. These options include the path to the LDAP naming configuration
file to use, so in effect all options can be configured on a per-service basis. Options
are listed below under PAM Configuration.

CONFIGURATION

pam_ldap stores its configuration in the ldap.conf file. (It should be noted that some
LDAP client libraries, such as OpenLDAP, also use a configuration file of the same name.
pam_ldap supports many of the same configuration file options as OpenLDAP, but it adds
several that are specific to the functionality it provides. It is not guaranteed that
pam_ldap will continue to match the configuration file semantics of OpenLDAP. You may
wish to use different files.)

Configuration file options consist of a keyword followed by a space and any arguments. The
following options are supported by both pam_ldap and the PADL nss_ldap module:

host <name:port ...>
Specifies the name(s) or IP address(es) of the LDAP server(s) to connect to. In the
case that nss_ldap is used for host name resolution, each server should be
specified as an IP address or name that can be resolved without using LDAP.
Multiple servers may be specified, each separated by a space. The failover time
depends on whether the LDAP client library supports configurable network or connect
timeouts (see bind_timelimit below).

base <base>
Specifies the default base distinguished name (DN) to use for searches.

uri <ldap[is]://[name[:port]] ...>
For LDAP client libraries that support it, specifies the URI(s) of the LDAP
server(s) to connect to. The URI scheme may be ldap, ldapi, or ldaps, specifying
LDAP over TCP, IPC and SSL respectively. If applicable, a port number can be
specified; the default port number for the selected protocol is used if omitted.
This option takes precedence over the host option; it is not possible to combine
the two.

ldap_version <version>
Specifies the version of the LDAP protocol to use. Presently version must be 2 or
3. The default is to use the maximum version supported by the client library.

binddn <binddn>
Specifies the distinguished name with which to bind to the directory server(s).
This option is optional; the default is to bind anonymously.

bindpw <bindpw>
Specifies the cleartext credentials with which to bind. This option is only
applicable when used with binddn above. The default is no credential (anonymous
bind). When binding to the directory using SASL or other authentication mechanisms
apart from simple binds, this option is not used.

rootbinddn <binddn>
This option has the same syntax and effect as the binddn option above, except it
applies when the effective user ID is zero. If not specified, then the identity
specified in binddn is used instead. Because the configuration file may be readable
by many users, the root bind DN credentials are stored in the ldap.secret file
instead. This file is usually in the same directory as the configuration file.

port <port>
Specifies the port to connect to; this option is used with the host option, and is
ignored with the uri option.

scope <sub|one|base>
Specifies the search scope (subtree, one level or base object). The default scope
is subtree; base scope is almost never useful for nameservice lookups.

deref <never|searching|finding|always>
Specifies the policy for dereferencing aliases. The default policy is to never
dereference aliases.

timelimit <timelimit>
Specifies the time limit (in seconds) to use when performing searches. A value of
zero (0), which is the default, is to wait indefinitely for searches to be
completed.

bind_timelimit <timelimit>
Specifies the time limit (in seconds) to use when connecting to the directory
server. This is distinct from the time limit specified in timelimit and affects the
initial server connection only. (Server connections are otherwise cached.) Only
some LDAP client libraries have the underlying functionality necessary to support
this option. The default bind timelimit is 30 seconds.

referrals <yes|no>
Specifies whether automatic referral chasing should be enabled. The default
behaviour is specifed by the LDAP client library.

restart <yes|no>
Specifies whether the LDAP client library should restart the select(2) system call
when interrupted. This feature is not supported by all client libraries.

logdir <directory>
Specifies the directory used for logging by the LDAP client library. This feature
is not supported by all client libraries.

debug <level>
Specifies the debug level used for logging by the LDAP client library. This feature
is not supported by all client libraries, and does not apply to the nss_ldap and
pam_ldap modules themselves (debugging, if any, is configured separately and
usually at compile time).

ssl <on|off|start_tls>
Specifies whether to use SSL/TLS or not (the default is not to). If start_tls is
specified then StartTLS is used rather than raw LDAP over SSL. Not all LDAP client
libraries support both SSL and StartTLS, and all related configuration options.

sslpath <cert7_path>
For the Netscape and Mozilla LDAP client libraries only, this specifies the path to
the X.509 certificate database.

tls_checkpeer <yes|no>
Specifies whether to require and verify the server certificate or not, when using
SSL/TLS with the OpenLDAP client library. The default is to use the default
behaviour of the client library; for OpenLDAP 2.0 and earlier it is "no", for
OpenLDAP 2.1 and later it is "yes". At least one of tls_cacertdir and
tls_cacertfile is required if peer verification is enabled.

tls_cacertdir <certificate_dir>
Specifies the directory containing X.509 certificates for peer authentication.

tls_cacertfile <certificate_file>
Specifies the path to the X.509 certificate for peer authentication.

tls_randfile <entropy_file>
Specifies the path to an entropy source.

tls_ciphers <ciphers>
Specifies the ciphers to use for TLS. See your TLS implementation's documentation
for further information.

tls_cert <certificate_file>
Specifies the path to the file containing the local certificate for client TLS
authentication.

tls_key <key_file>
Specifies the path to the file containing the private key for client TLS
authentication.

The following configuration options apply to pam_ldap only:

pam_login_attribute <attribute>
Specifies the attribute to use when constructing the attribute value assertion for
retrieving a directory entry for a user's login name. The default is "uid", for
compatibility with RFC 2307.

pam_filter <filter>
Specifies a filter to use when retrieving user information. The user entry must
match the attribute value assertion of (pam_login_attribute=login_name) as well as
any filter specified here. There is no default for this option.

pam_lookup_policy <yes|no>
Specifies whether to search the root DSE for password policy. The default is "no".

pam_check_host_attr <yes|no>
Specifies whether the "host" attribute should be checked for logon authorization
("account" in the PAM stack). The default is not to. If set to "yes" and a user
has no value for the "host" attribute, then the user will be unable to login.

pam_check_service_attr <yes|no>
Specifies whether the "authorizedService" attribute should be checked for logon
authorization ("account" in the PAM stack). The default is not to. If set to "yes"
and a user has no value for the "authorizedService" attribute, then the user will
be unable to login.

pam_groupdn <groupdn>
Specifies the distinguished name of a group to which a user must belong for logon
authorization to succeed. pam_member_attribute <attribute> Specifies the attribute
to use when testing a user's membership of a group specified in the pam_groupdn
option.

pam_min_uid <uid>
If specified, a user must have a POSIX user ID of at least uid in order for logon
authorization to succeed.

pam_max_uid <uid>
If specified, a user must have a POSIX user ID of no greater than uid in order for
logon authorization to succeed.

pam_template_login_attribute <attribute>
When using template users (not supported by all PAM applications), specifies the
attribute containing the user's actual login name. The pam_ldap module will set
PAM_USER to the value of this attribute if present in the user's entry, otherwise
it defaults to the user specified in the pam_template_login option.

pam_template_login <user>
When using template users (not supported by all PAM applications), pam_ldap will
set PAM_USER to the value of this option if the user does not contain a template
login attribute.

pam_password <protocol>
Specifies the password change protocol to use. The following protocols are
supported:

clear Change password using an LDAPModify request, replacing the userPassword
value with the new cleartext password.

clear_remove_old
Change password using an LDAPModify request, first removing the userPassword
value containing the old cleartext password, and then adding the
userPassword value with the new cleartext password. This protocol is
necessary for use with Novell NDS and IBM RACF.

crypt Change password using an LDAPModify request, first generating a one way hash
of the new password using crypt(3) and then replacing userPassword value
with the new hashed password.

md5 Change password using an LDAPModify request, first generating a one way hash
of the new password using MD5 and then replacing userPassword value with the
new hashed password.

nds This is an alias for clear_remove_old.

racf This is an alias for clear_remove_old.

ad Change password using an LDAPModify request, using the Active Directory
Services Interface (ADSI) password change protocol.

exop Change password using the RFC 3062 password modify extended operation (only
the new password is sent).

exop_send_old
Change password using the RFC 3062 password modify extended operation (both
the old and new passwords are sent).

pam_password_prohibit_message <message>
Specifies a message to send to users indicating that passwords cannot be changed.
This could be used to redirect users to another means of changing passwords.

pam_sasl_mech <mechanism>
Specifies the SASL mechanism to use for PAM authentication. This requires SASL
libraries be installed. Support for this functionality presently experimental and
does not support password policy controls.

PAM CONFIGURATION

It is possible to configure some aspects of pam_ldap on a per-service basis, in the PAM
configuration file (this is usually /etc/pam.conf; for PAM implementations based on Linux-
PAM, per-service files in /etc/pam.d are also supported).

The following options may be specified as arguments to the pam_ldap module:

config=<path>
Specifies that pam_ldap should use the configuration file in path instead of
ldap.conf to retrieve its global configuration. Configuring multiple instances of
pam_ldap for the same service with different configuration files is not supported,
because the configuration information is cached.

use_first_pass
Specifies that pam_ldap should always use the first password provided in the
authentication stack.

try_first_pass
Specifies that pam_ldap should first try the first password provided in the
authentication stack, and then prompt the user for their LDAP password if
authentication fails.

ignore_unknown_user
Specifies that pam_ldap should return PAM_IGNORE for users that are not present in
LDAP. This forces the PAM framework to ignore the pam_ldap module. This option is
useful where certain accounts do not reside in LDAP, but one wishes to make
pam_ldap "required" for all accounts in the directory. In this case one would make
both pam_ldap and the other module (for example, pam_unix) "required" and enable
the ignore_unknown_user option. (For this to work, the other module must behave
similarly for users in the directory; in the case of a module such as pam_unix that
uses the system accounts database, using nss_ldap(5) should be sufficient to meet
this requirement.)

ignore_authinfo_unavail
Specifies that pam_ldap should return PAM_IGNORE if it cannot contact the LDAP
server. This option forces the PAM framework to ignore the pam_ldap module in this
case.

no_warn
Specifies that warning messages should not be propagated to the PAM application.

use_authtok
Analogous to use_first_pass for password changing only.

debug This option is recognized by pam_ldap but is presently ignored.

AUTHOR

       The pam_ldap module was developed by PADL Software Pty Ltd (www.padl.com).

FILES