| blob | fec71f0322623e3a231da9ebbee278661fcc61cb |
1 '\" te
2 .\" Copyright (C) 2005, Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH PAM_LDAP 5 "Dec 21, 2005"
7 .SH NAME
8 pam_ldap \- authentication and account management PAM module for LDAP
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/lib/security/pam_ldap.so.1\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 The \fBpam_ldap\fR module implements \fBpam_sm_authenticate\fR(3PAM) and
19 \fBpam_sm_acct_mgmt\fR(3PAM), the functions that provide functionality for the
20 PAM authentication and account management stacks. The \fBpam_ldap\fR module
21 ties the authentication and account management functionality to the
22 functionality of the supporting LDAP server. For authentication, \fBpam_ldap\fR
23 can authenticate the user directly to any LDAP directory server by using any
24 supported authentication mechanism, such as \fBDIGEST-MD5\fR. However, the
25 account management component of \fBpam_ldap\fR will work only with the Sun Java
26 System Directory Server. The server's user account management must be properly
27 configured before it can be used by \fBpam_ldap\fR. Refer to the \fISun Java
28 System Directory Server Administration Guide\fR for information on how to
29 configure user account management, including password and account lockout
30 policy.
31 .sp
32 .LP
33 \fBpam_ldap\fR must be used in conjunction with the modules that support the
34 UNIX authentication, password, and account management, which are
35 \fBpam_authtok_get\fR(5), \fBpam_passwd_auth\fR(5), \fBpam_unix_account\fR(5),
36 and \fBpam_unix_auth\fR(5). \fBpam_ldap\fR is designed to be stacked directly
37 below these modules. If other modules are designed to be stacked in this
38 manner, the modules can be stacked below the \fBpam_ldap\fR module. The
39 Examples section shows how the UNIX modules are stacked with \fBpam_ldap\fR.
40 When stacked together, the UNIX modules are used to control local accounts,
41 such as \fBroot\fR. \fBpam_ldap\fR is used to control network accounts, that
42 is, LDAP users. For the stacks to work, \fBpam_unix_auth\fR,
43 \fBpam_unix_account\fR, and \fBpam_passwd_auth\fR must be configured with the
44 \fBbinding\fR control flag and the \fBserver_policy\fR option. This
45 configuration allows local account override of a network account.
46 .SS "LDAP Authentication Module"
47 .sp
48 .LP
49 The LDAP authentication module verifies the identity of a user. The
50 \fBpam_sm_authenticate\fR(3PAM) function uses the password entered by the user
51 to attempt to authenticate to the LDAP server. If successful, the user is
52 authenticated. See NOTES for information on password prompting.
53 .sp
54 .LP
55 The authentication method used is either defined in the client profile , or the
56 authentication method is configured by using the \fBldapclient\fR(1M) command.
57 To determine the authentication method to use, this module first attempts to
58 use the authentication method that is defined, for service \fBpam_ldap\fR, for
59 example, \fBserviceAuthenticationMethod:pam_ldap:sasl/DIGEST-MD5\fR. If no
60 authentication method is defined, \fBpam_ldap\fR uses the default
61 authentication method. If neither are set, the authentication fails. This
62 module skips the configured authentication method if the authentication method
63 is set to \fBnone\fR.
64 .sp
65 .LP
66 The following options can be passed to the LDAP service module:
67 .sp
68 .ne 2
69 .na
70 \fB\fBdebug\fR\fR
71 .ad
72 .RS 10n
73 \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
74 .RE
76 .sp
77 .ne 2
78 .na
79 \fB\fBnowarn\fR\fR
80 .ad
81 .RS 10n
82 Turn off warning messages.
83 .RE
85 .sp
86 .LP
87 These options are case sensitive and must be used exactly as presented here.
88 .SS "LDAP Account Management Module"
89 .sp
90 .LP
91 The LDAP account management module validates the user's account. The
92 \fBpam_sm_acct_mgmt\fR(3PAM) function authenticates to the LDAP server to
93 verify that the user's password has not expired, or that the user's account has
94 not been locked. In the event that there is no user authentication token
95 (\fBPAM_AUTHTOK\fR) available, the \fBpam_sm_acct_mgmt\fR(3PAM) function
96 attempts to retrieve the user's account status without authenticating to the
97 LDAP server as the user logging in. This procedure will succeed only if the
98 LDAP server is Sun Java System Directory server 5.2 patch 4 or newer. The
99 following options can be passed to the LDAP service module:
100 .sp
101 .ne 2
102 .na
103 \fB\fBdebug\fR\fR
104 .ad
105 .RS 10n
106 \fBsyslog\fR(3C) debugging information at \fBLOG_DEBUG\fR level.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fBnowarn\fR\fR
113 .ad
114 .RS 10n
115 Turn off warning messages.
116 .RE
118 .sp
119 .LP
120 These options are case sensitive, and the options must be used exactly as
121 presented here.
122 .SS "LDAP Password Management Module"
123 .sp
124 .LP
125 LDAP password management is no longer supported by \fBpam_ldap\fR. Use
126 \fBpam_authtok_store\fR(5) instead of \fBpam_ldap\fR for password change.
127 \fBpam_authtok_store\fR(5) handles both the local and LDAP accounts and updates
128 the passwords in all the repositories configured by \fBnsswitch.conf\fR(4).
129 .SH ERRORS
130 .sp
131 .LP
132 The authentication service returns the following error codes:
133 .sp
134 .ne 2
135 .na
136 \fB\fBPAM_SUCCESS\fR\fR
137 .ad
138 .RS 20n
139 The uthentication was successful.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fBPAM_MAXTRIES\fR\fR
146 .ad
147 .RS 20n
148 The maximum number of authentication attempts was exceeded.
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBPAM_AUTH_ERR\fR\fR
155 .ad
156 .RS 20n
157 The authentication failed.
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fBPAM_USER_UNKNOWN\fR\fR
164 .ad
165 .RS 20n
166 No account is present for the user.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fBPAM_BUF_ERR\fR\fR
173 .ad
174 .RS 20n
175 A memory buffer error occurred.
176 .RE
178 .sp
179 .ne 2
180 .na
181 \fB\fBPAM_SYSTEM_ERR\fR\fR
182 .ad
183 .RS 20n
184 A system error occurred.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fBPAM_IGNORE\fR\fR
191 .ad
192 .RS 20n
193 The user's account was inactivated.
194 .RE
196 .sp
197 .LP
198 The account management service returns the following error codes:
199 .sp
200 .ne 2
201 .na
202 \fB\fBPAM_SUCCESS\fR\fR
203 .ad
204 .RS 24n
205 The user was allowed access to the account.
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fBPAM_NEW_AUTHTOK_REQD\fR\fR
212 .ad
213 .RS 24n
214 A new authentication token is required.
215 .RE
217 .sp
218 .ne 2
219 .na
220 \fB\fBPAM_ACCT_EXPIRED\fR\fR
221 .ad
222 .RS 24n
223 The user account has expired.
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fB\fBPAM_PERM_DENIED\fR\fR
230 .ad
231 .RS 24n
232 The user was denied access to the account at this time.
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fBPAM_USER_UNKNOWN\fR\fR
239 .ad
240 .RS 24n
241 No account is present for the user.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBPAM_BUF_ERROR\fR\fR
248 .ad
249 .RS 24n
250 A memory buffer error occurred.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fBPAM_SYSTEM_ERR\fR\fR
257 .ad
258 .RS 24n
259 A system error occurred.
260 .RE
262 .SH EXAMPLES
263 .LP
264 \fBExample 1 \fRUsing \fBpam_ldap\fR With Authentication\fB\fR
265 .sp
266 .LP
267 The following is a configuration for the login service when using
268 \fBpam_ldap\fR. The service name \fBlogin\fR can be substituted for any other
269 authentication service such as \fBdtlogin\fR or \fBsu\fR. Lines that begin with
270 the # symbol are comments and are ignored.
272 .sp
273 .in +2
274 .nf
275 # Authentication management for login service is stacked.
276 # If pam_unix_auth succeeds, pam_ldap is not invoked.
277 # The control flag "binding" provides a local overriding
278 # remote (LDAP) control. The "server_policy" option is used
279 # to tell pam_unix_auth.so.1 to ignore the LDAP users.
281 login auth requisite pam_authtok_get.so.1
282 login auth required pam_dhkeys.so.1
283 login auth required pam_unix_cred.so.1
284 login auth binding pam_unix_auth.so.1 server_policy
285 login auth required pam_ldap.so.1
286 .fi
287 .in -2
289 .LP
290 \fBExample 2 \fRUsing \fBpam_ldap\fR With Account Management
291 .sp
292 .LP
293 The following is a configuration for account management when using
294 \fBpam_ldap\fR. Lines that begin with the # symbol are comments and are
295 ignored.
297 .sp
298 .in +2
299 .nf
300 # Account management for all services is stacked
301 # If pam_unix_account succeeds, pam_ldap is not invoked.
302 # The control flag "binding" provides a local overriding
303 # remote (LDAP) control. The "server_policy" option is used
304 # to tell pam_unix_account.so.1 to ignore the LDAP users.
306 other account requisite pam_roles.so.1
307 other account binding pam_unix_account.so.1 server_policy
308 other account required pam_ldap.so.1
309 .fi
310 .in -2
312 .LP
313 \fBExample 3 \fRUsing \fBpam_authtok_store\fR With Password Management For Both
314 Local and LDAP Accounts
315 .sp
316 .LP
317 The following is a configuration for password management when using
318 \fBpam_authtok_store\fR. Lines that begin with the # symbol are comments and
319 are ignored.
321 .sp
322 .in +2
323 .nf
324 # Password management (authentication)
325 # The control flag "binding" provides a local overriding
326 # remote (LDAP) control. The server_policy option is used
327 # to tell pam_passwd_auth.so.1 to ignore the LDAP users.
329 passwd auth binding pam_passwd_auth.so.1 server_policy
330 passwd auth required pam_ldap.so.1
332 # Password management (updates)
333 # This updates passwords stored both in the local /etc
334 # files and in the LDAP directory. The "server_policy"
335 # option is used to tell pam_authtok_store to
336 # follow the LDAP server's policy when updating
337 # passwords stored in the LDAP directory
339 other password required pam_dhkeys.so.1
340 other password requisite pam_authtok_get.so.1
341 other password requisite pam_authtok_check.so.1
342 other password required pam_authtok_store.so.1 server_policy
343 .fi
344 .in -2
346 .SH FILES
347 .sp
348 .ne 2
349 .na
350 \fB\fB/var/ldap/ldap_client_file\fR\fR
351 .ad
352 .br
353 .na
354 \fB\fB/var/ldap/ldap_client_cred\fR\fR
355 .ad
356 .RS 30n
357 The LDAP configuration files of the client. Do not manually modify these files,
358 as these files might not be human readable. Use \fBldapclient\fR(1M) to update
359 these files.
360 .RE
362 .sp
363 .ne 2
364 .na
365 \fB\fB/etc/pam.conf\fR\fR
366 .ad
367 .RS 30n
368 PAM configuration file.
369 .RE
371 .SH ATTRIBUTES
372 .sp
373 .LP
374 See \fBattributes\fR(5) for descriptions of the following attributes:
375 .sp
377 .sp
378 .TS
379 box;
380 c | c
381 l | l .
382 ATTRIBUTE TYPE ATTRIBUTE VALUE
383 _
384 Interface Stability Evolving
385 _
386 MT-Level MT-Safe with exceptions
387 .TE
389 .SH SEE ALSO
390 .sp
391 .LP
392 \fBldap\fR(1), \fBidsconfig\fR(1M), \fBldap_cachemgr\fR(1M),
393 \fBldapclient\fR(1M), \fBlibpam\fR(3LIB), \fBpam\fR(3PAM),
394 \fBpam_sm_acct_mgmt\fR(3PAM), \fBpam_sm_authenticate\fR(3PAM),
395 \fBpam_sm_chauthtok\fR(3PAM), \fBpam_sm_close_session\fR(3PAM),
396 \fBpam_sm_open_session\fR(3PAM), \fBpam_sm_setcred\fR(3PAM), \fBsyslog\fR(3C),
397 \fBpam.conf\fR(4), \fBattributes\fR(5), \fBpam_authtok_check\fR(5),
398 \fBpam_authtok_get\fR(5), \fBpam_authtok_store\fR(5), \fBpam_passwd_auth\fR(5),
399 \fBpam_unix_account\fR(5), \fBpam_unix_auth\fR(5)
400 .SH NOTES
401 .sp
402 .LP
403 The interfaces in \fBlibpam\fR(3LIB) are MT-Safe only if each thread within the
404 multi-threaded application uses its own \fBPAM\fR handle.
405 .sp
406 .LP
407 The previously supported \fBuse_first_pass\fR and \fBtry_first_pass\fR options
408 are obsolete in this version, are no longer needed, can safely be removed from
409 \fBpam.conf\fR(4), and are silently ignored. They might be removed in a future
410 release. Password prompting must be provided for by stacking
411 \fBpam_authtok_get\fR(5) before \fBpam_ldap\fR in the \fBauth\fR and
412 \fBpassword\fR module stacks and \fBpam_passwd_auth\fR(5) in the \fBpasswd\fR
413 service \fBauth\fR stack (as described in the EXAMPLES section). The previously
414 supported password update function is replaced in this release by the
415 previously recommended use of \fBpam_authtok_store\fR with the
416 \fBserver_policy\fR option (as described in the EXAMPLES section).
417 .sp
418 .LP
419 The functions: \fBpam_sm_setcred\fR(3PAM), \fBpam_sm_chauthtok\fR(3PAM),
420 \fBpam_sm_open_session\fR(3PAM), and \fBpam_sm_close_session\fR(3PAM) do
421 nothing and return \fBPAM_IGNORE\fR in \fBpam_ldap\fR.