Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
pam_ldap(5)		      File Formats Manual		   pam_ldap(5)

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,	speci-
       fied  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,  dis-
       cussed 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 sup-
       port more than one password change protocol.)

       Whilst  pam_ldap	is generally configured	in the system LDAP naming con-
       figuration 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 res-
	      olution, 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 respec-
	      tively. If applicable, a port number can be specified;  the  de-
	      fault  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  ver-
	      sion supported by	the client library.

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

       bindpw <bindpw>
	      Specifies	the cleartext credentials with which to	bind. This op-
	      tion 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 in-
	      stead. Because the configuration file may	be  readable  by  many
	      users,  the  root	bind DN	credentials are	stored in the ldap.se-
	      cret 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 pol-
	      icy 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 spec-
	      ified  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 sup-
	      ported by	all client libraries.

       logdir <directory>
	      Specifies	 the directory used for	logging	by the LDAP client li-
	      brary. 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	 them-
	      selves  (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  li-
	      brary; 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 authentica-
	      tion.

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

       tls_ciphers <ciphers>
	      Specifies	 the  ciphers to use for TLS. See your TLS implementa-
	      tion'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_lo-
	      gin_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 lo-
	      gon 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 un-
	      able 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 applica-
	      tions), specifies	the attribute containing the user's actual lo-
	      gin name.	 The pam_ldap module will set PAM_USER to the value of
	      this attribute if	present	in the user's entry, otherwise it  de-
	      faults to	the user specified in the pam_template_login option.

       pam_template_login <user>
	      When  using  template  users  (not supported by all PAM applica-
	      tions), 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	remov-
		     ing 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	gener-
		     ating 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	gener-
		     ating  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 ex-
		     tended operation (only the	new password is	sent).

	      exop_send_old
		     Change password using the RFC 3062	 password  modify  ex-
		     tended  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 an-
	      other 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 function-
	      ality presently experimental and does not	support	password  pol-
	      icy 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 pro-
	      vided  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 ig-
	      nore 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
       /etc/ldap.conf, /etc/ldap.secret, /etc/pam.conf

SEE ALSO
       pam(8)

								   pam_ldap(5)

NAME | DESCRIPTION | CONFIGURATION | PAM CONFIGURATION | AUTHOR | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pam_ldap&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help