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