1pam_ldap(5) File Formats Manual pam_ldap(5)
2
6 pam_ldap - LDAP pluggable authentication module
7
9 The pam_ldap module is a Pluggable Authentication Module (PAM) which
10 provides for authentication, authorization and password changing
11 against LDAP servers.
12 Features of the PADL pam_ldap module include support for transport
14 layer security, SASL authentication, directory server-enforced password
15 policy, and host- and group- based logon authorization.
16 The present version of pam_ldap supports AIX 5L, FreeBSD 3.x and above,
18 HP-UX 11i, IRIX 6.x, Linux, Mac OS X 10.2 and above, and Solaris 2.6
19 and above. Many vendors provide their own LDAP authentication
20 providers, often also called pam_ldap. This manual page applies to the
21 PADL pam_ldap module only. If you are using a vendor provided module,
22 consult the relevant documentation instead.
23 When authenticating or authorizing a user, pam_ldap first maps the
25 user's login name to a distinguished name by searching the directory
26 server. This must be possible using the local system's identity, speci‐
27 fied in pam_ldap.conf. (Note that presently only simple authentication
28 is supported for authenticating in this initial step.)
29 To authenticate a user, pam_ldap attempts to bind to the directory
31 server using the distinguished name of the user (retrieved previously).
32 Both simple and SASL authentication mechanisms are supported; in the
33 former case, one should take care to use transport security to prevent
34 the user's password being transmitted in the clear.
35 A variety of authorization primitives are supported by pam_ldap, dis‐
37 cussed in the configuration section below.
38 Finally, pam_ldap supports a number of password change protocols used
40 by directory servers from various vendors. (Some directory servers sup‐
41 port more than one password change protocol.)
42 Whilst pam_ldap is generally configured in the system LDAP naming con‐
44 figuration file (pam_ldap.conf), some options can be configured in the
45 PAM configuration file, to allow for per-service granularity. These
46 options include the path to the LDAP naming configuration file to use,
47 so in effect all options can be configured on a per-service basis.
48 Options are listed below under PAM Configuration.
49
51 pam_ldap stores its configuration in the pam_ldap.conf file. (It should
52 be noted that some LDAP client libraries, such as OpenLDAP, also use a
53 configuration file of the same name. pam_ldap supports many of the
54 same configuration file options as OpenLDAP, but it adds several that
55 are specific to the functionality it provides. It is not guaranteed
56 that pam_ldap will continue to match the configuration file semantics
57 of OpenLDAP. You may wish to use different files.)
58 Configuration file options consist of a keyword followed by a space and
60 any arguments. The following options are supported by both pam_ldap and
61 the PADL nss_ldap module:
62 host <name:port ...>
64 Specifies the name(s) or IP address(es) of the LDAP server(s) to
65 connect to. In the case that nss_ldap is used for host name res‐
66 olution, each server should be specified as an IP address or
67 name that can be resolved without using LDAP. Multiple servers
68 may be specified, each separated by a space. The failover time
69 depends on whether the LDAP client library supports configurable
70 network or connect timeouts (see bind_timelimit below).
71 base <base>
73 Specifies the default base distinguished name (DN) to use for
74 searches.
75 uri <ldap[is]://[name[:port]] ...>
77 For LDAP client libraries that support it, specifies the URI(s)
78 of the LDAP server(s) to connect to. The URI scheme may be ldap,
79 ldapi, or ldaps, specifying LDAP over TCP, IPC and SSL respec‐
80 tively. If applicable, a port number can be specified; the
81 default port number for the selected protocol is used if omit‐
82 ted. This option takes precedence over the host option; it is
83 not possible to combine the two.
84 ldap_version <version>
86 Specifies the version of the LDAP protocol to use. Presently
87 version must be 2 or 3. The default is to use the maximum ver‐
88 sion supported by the client library.
89 binddn <binddn>
91 Specifies the distinguished name with which to bind to the
92 directory server(s). This option is optional; the default is to
93 bind anonymously.
94 bindpw <bindpw>
96 Specifies the cleartext credentials with which to bind. This
97 option is only applicable when used with binddn above. The
98 default is no credential (anonymous bind). When binding to the
99 directory using SASL or other authentication mechanisms apart
100 from simple binds, this option is not used.
101 rootbinddn <binddn>
103 This option has the same syntax and effect as the binddn option
104 above, except it applies when the effective user ID is zero. If
105 not specified, then the identity specified in binddn is used
106 instead. Because the configuration file may be readable by many
107 users, the root bind DN credentials are stored in the
108 pam_ldap.secret file instead. This file is usually in the same
109 directory as the configuration file.
110 port <port>
112 Specifies the port to connect to; this option is used with the
113 host option, and is ignored with the uri option.
114 scope <sub|one|base>
116 Specifies the search scope (subtree, one level or base object).
117 The default scope is subtree; base scope is almost never useful
118 for nameservice lookups.
119 deref <never|searching|finding|always>
121 Specifies the policy for dereferencing aliases. The default pol‐
122 icy is to never dereference aliases.
123 timelimit <timelimit>
125 Specifies the time limit (in seconds) to use when performing
126 searches. A value of zero (0), which is the default, is to wait
127 indefinitely for searches to be completed.
128 bind_timelimit <timelimit>
130 Specifies the time limit (in seconds) to use when connecting to
131 the directory server. This is distinct from the time limit spec‐
132 ified in timelimit and affects the initial server connection
133 only. (Server connections are otherwise cached.) Only some LDAP
134 client libraries have the underlying functionality necessary to
135 support this option. The default bind timelimit is 30 seconds.
136 referrals <yes|no>
138 Specifies whether automatic referral chasing should be enabled.
139 The default behaviour is specifed by the LDAP client library.
140 restart <yes|no>
142 Specifies whether the LDAP client library should restart the
143 select(2) system call when interrupted. This feature is not sup‐
144 ported by all client libraries.
145 logdir <directory>
147 Specifies the directory used for logging by the LDAP client
148 library. This feature is not supported by all client libraries.
149 debug <level>
151 Specifies the debug level used for logging by the LDAP client
152 library. This feature is not supported by all client libraries,
153 and does not apply to the nss_ldap and pam_ldap modules them‐
154 selves (debugging, if any, is configured separately and usually
155 at compile time).
156 ssl <on|off|start_tls>
158 Specifies whether to use SSL/TLS or not (the default is not to).
159 If start_tls is specified then StartTLS is used rather than raw
160 LDAP over SSL. Not all LDAP client libraries support both SSL
161 and StartTLS, and all related configuration options.
162 sslpath <cert7_path>
164 For the Netscape and Mozilla LDAP client libraries only, this
165 specifies the path to the X.509 certificate database.
166 tls_checkpeer <yes|no>
168 Specifies whether to require and verify the server certificate
169 or not, when using SSL/TLS with the OpenLDAP client library.
170 The default is to use the default behaviour of the client
171 library; for OpenLDAP 2.0 and earlier it is "no", for OpenLDAP
172 2.1 and later it is "yes". At least one of tls_cacertdir and
173 tls_cacertfile is required if peer verification is enabled.
174 tls_cacertdir <certificate_dir>
176 Specifies the directory containing X.509 certificates for peer
177 authentication.
178 tls_cacertfile <certificate_file>
180 Specifies the path to the X.509 certificate for peer authentica‐
181 tion.
182 tls_randfile <entropy_file>
184 Specifies the path to an entropy source.
185 tls_ciphers <ciphers>
187 Specifies the ciphers to use for TLS. See your TLS implementa‐
188 tion's documentation for further information.
189 tls_cert <certificate_file>
191 Specifies the path to the file containing the local certificate
192 for client TLS authentication.
193 tls_key <key_file>
195 Specifies the path to the file containing the private key for
196 client TLS authentication.
197 The following configuration options apply to pam_ldap only:
199 pam_login_attribute <attribute>
201 Specifies the attribute to use when constructing the attribute
202 value assertion for retrieving a directory entry for a user's
203 login name. The default is "uid", for compatibility with RFC
204 2307.
205 pam_filter <filter>
207 Specifies a filter to use when retrieving user information. The
208 user entry must match the attribute value assertion of
209 (pam_login_attribute=login_name) as well as any filter specified
210 here. There is no default for this option.
211 pam_lookup_policy <yes|no>
213 Specifies whether to search the root DSE for password policy.
214 The default is "no".
215 pam_check_host_attr <yes|no>
217 Specifies whether the "host" attribute should be checked for
218 logon authorization ("account" in the PAM stack). The default is
219 not to. If set to "yes" and a user has no value for the "host"
220 attribute, then the user will be unable to login.
221 pam_check_service_attr <yes|no>
223 Specifies whether the "authorizedService" attribute should be
224 checked for logon authorization ("account" in the PAM stack).
225 The default is not to. If set to "yes" and a user has no value
226 for the "authorizedService" attribute, then the user will be
227 unable to login.
228 pam_groupdn <groupdn>
230 Specifies the distinguished name of a group to which a user must
231 belong for logon authorization to succeed. pam_member_attribute
232 <attribute> Specifies the attribute to use when testing a user's
233 membership of a group specified in the pam_groupdn option.
234 pam_nsrole <role>
236 Specifies a value which the user's entry's "nsRole" attribute
237 must match for logon authorization to succeed.
238 pam_min_uid <uid>
240 If specified, a user must have a POSIX user ID of at least uid
241 in order for logon authorization to succeed.
242 pam_max_uid <uid>
244 If specified, a user must have a POSIX user ID of no greater
245 than uid in order for logon authorization to succeed.
246 pam_template_login_attribute <attribute>
248 When using template users (not supported by all PAM applica‐
249 tions), specifies the attribute containing the user's actual
250 login name. The pam_ldap module will set PAM_USER to the value
251 of this attribute if present in the user's entry, otherwise it
252 defaults to the user specified in the pam_template_login option.
253 pam_template_login <user>
255 When using template users (not supported by all PAM applica‐
256 tions), pam_ldap will set PAM_USER to the value of this option
257 if the user does not contain a template login attribute.
258 pam_password <protocol>
260 Specifies the password change protocol to use. The following
261 protocols are supported:
262 clear Change password using an LDAPModify request, replacing
264 the userPassword value with the new cleartext password.
265 clear_remove_old
267 Change password using an LDAPModify request, first remov‐
268 ing the userPassword value containing the old cleartext
269 password, and then adding the userPassword value with the
270 new cleartext password. This protocol is necessary for
271 use with Novell NDS and IBM RACF.
272 crypt Change password using an LDAPModify request, first gener‐
274 ating a one way hash of the new password using crypt(3)
275 and then replacing userPassword value with the new hashed
276 password.
277 md5 Change password using an LDAPModify request, first gener‐
279 ating a one way hash of the new password using MD5 and
280 then replacing userPassword value with the new hashed
281 password.
282 nds This is an alias for clear_remove_old.
284 racf This is an alias for clear_remove_old.
286 ad Change password using an LDAPModify request, using the
288 Active Directory Services Interface (ADSI) password
289 change protocol.
290 exop Change password using the RFC 3062 password modify
292 extended operation (only the new password is sent).
293 exop_send_old
295 Change password using the RFC 3062 password modify
296 extended operation (both the old and new passwords are
297 sent).
298 pam_password_prohibit_message <message>
300 Specifies a message to send to users indicating that passwords
301 cannot be changed. This could be used to redirect users to
302 another means of changing passwords.
303 pam_sasl_mech <mechanism>
305 Specifies the SASL mechanism to use for PAM authentication. This
306 requires SASL libraries be installed. Support for this function‐
307 ality presently experimental and does not support password pol‐
308 icy controls.
309
311 It is possible to configure some aspects of pam_ldap on a per-service
312 basis, in the PAM configuration file (this is usually /etc/pam.conf;
313 for PAM implementations based on Linux-PAM, per-service files in
314 /etc/pam.d are also supported).
315 The following options may be specified as arguments to the pam_ldap
317 module:
318 config=<path>
320 Specifies that pam_ldap should use the configuration file in
321 path instead of pam_ldap.conf to retrieve its global configura‐
322 tion. Configuring multiple instances of pam_ldap for the same
323 service with different configuration files is not supported,
324 because the configuration information is cached.
325 use_first_pass
327 Specifies that pam_ldap should always use the first password
328 provided in the authentication stack.
329 try_first_pass
331 Specifies that pam_ldap should first try the first password pro‐
332 vided in the authentication stack, and then prompt the user for
333 their LDAP password if authentication fails.
334 ignore_unknown_user
336 Specifies that pam_ldap should return PAM_IGNORE for users that
337 are not present in LDAP. This forces the PAM framework to
338 ignore the pam_ldap module. This option is useful where certain
339 accounts do not reside in LDAP, but one wishes to make pam_ldap
340 "required" for all accounts in the directory. In this case one
341 would make both pam_ldap and the other module (for example,
342 pam_unix) "required" and enable the ignore_unknown_user option.
343 (For this to work, the other module must behave similarly for
344 users in the directory; in the case of a module such as pam_unix
345 that uses the system accounts database, using nss_ldap(5) should
346 be sufficient to meet this requirement.)
347 ignore_authinfo_unavail
349 Specifies that pam_ldap should return PAM_IGNORE if it cannot
350 contact the LDAP server. This option forces the PAM framework to
351 ignore the pam_ldap module in this case.
352 no_warn
354 Specifies that warning messages should not be propagated to the
355 PAM application.
356 use_authtok
358 Analogous to use_first_pass for password changing only.
359 debug This option is recognized by pam_ldap but is presently ignored.
361
363 The pam_ldap module was developed by PADL Software Pty Ltd
364 (www.padl.com).
365
367 /etc/pam_ldap.conf, /etc/pam_ldap.secret, /etc/pam.conf
368
370 pam(8)
371 pam_ldap(5)