1SLAPO_PPOLICY(5) File Formats Manual SLAPO_PPOLICY(5)
2
6 slapo-ppolicy - Password Policy overlay
7
9 /etc/openldap/slapd.conf
10
12 The ppolicy overlay is an implementation of the most recent IETF Pass‐
13 word Policy proposal for LDAP. When instantiated, it intercepts,
14 decodes and applies specific password policy controls to overall use of
15 a backend database, changes to user password fields, etc.
16 The overlay provides a variety of password control mechanisms. They
18 include password aging--both minimum and maximum ages, password reuse
19 and duplication control, account time-outs, mandatory password resets,
20 acceptable password content, and even grace logins. Different groups
21 of users may be associated with different password policies, and there
22 is no limit to the number of password policies that may be created.
23 Note that some of the policies do not take effect when the operation is
25 performed with the rootdn identity; all the operations, when performed
26 with any other identity, may be subjected to constraints, like access
27 control.
28
31 These slapd.conf configuration options apply to the ppolicy overlay.
32 They should appear after the overlay directive.
33 ppolicy_default <policyDN>
35 Specify the DN of the pwdPolicy object to use when no specific
36 policy is set on a given user's entry. If there is no specific
37 policy for an entry and no default is given, then no policies
38 will be enforced.
39 ppolicy_hash_cleartext
41 Specify that cleartext passwords present in Add and Modify
42 requests should be hashed before being stored in the database.
43 This violates the X.500/LDAP information model, but may be
44 needed to compensate for LDAP clients that don't use the Pass‐
45 word Modify extended operation to manage passwords. It is rec‐
46 ommended that when this option is used that compare, search, and
47 read access be denied to all directory users.
48 ppolicy_use_lockout
50 A client will always receive an LDAP InvalidCredentials response
51 when Binding to a locked account. By default, when a Password
52 Policy control was provided on the Bind request, a Password Pol‐
53 icy response will be included with no special error code set.
54 This option changes the Password Policy response to include the
55 AccountLocked error code. Note that sending the AccountLocked
56 error code provides useful information to an attacker; sites
57 that are sensitive to security issues should not enable this
58 option.
59
62 The ppolicy overlay depends on the pwdPolicy object class. The defini‐
63 tion of that class is as follows:
64 ( 1.3.6.1.4.1.42.2.27.8.2.1
66 NAME 'pwdPolicy'
67 AUXILIARY
68 SUP top
69 MUST ( pwdAttribute )
70 MAY (
71 pwdMinAge $ pwdMaxAge $ pwdInHistory $
72 pwdCheckQuality $ pwdMinLength $
73 pwdExpireWarning $ pwdGraceAuthnLimit $
74 pwdLockout $ pwdLockoutDuration $
75 pwdMaxFailure $ pwdFailureCountInterval $
76 pwdMustChange $ pwdAllowUserChange $
77 pwdSafeModify ) )
78 This implementation also provides an additional pwdPolicyChecker
80 objectclass, used for password quality checking (see below).
81 ( 1.3.6.1.4.1.4754.2.99.1
83 NAME 'pwdPolicyChecker'
84 AUXILIARY
85 SUP top
86 MAY ( pwdCheckModule ) )
87 Every account that should be subject to password policy control should
89 have a pwdPolicySubentry attribute containing the DN of a valid pwdPol‐
90 icy entry, or they can simply use the configured default. In this way
91 different users may be managed according to different policies.
92
95 Each one of the sections below details the meaning and use of a partic‐
96 ular attribute of this pwdPolicy object class.
97 pwdAttribute
99 This attribute contains the name of the attribute to which the password
101 policy is applied. For example, the password policy may be applied to
102 the userPassword attribute.
103 Note: in this implementation, the only value accepted for pwdAttribute
105 is userPassword .
106 ( 1.3.6.1.4.1.42.2.27.8.1.1
108 NAME 'pwdAttribute'
109 EQUALITY objectIdentifierMatch
110 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
111 pwdMinAge
113 This attribute contains the number of seconds that must elapse between
115 modifications allowed to the password. If this attribute is not
116 present, zero seconds is assumed (i.e. the password may be modified
117 whenever and however often is desired).
118 ( 1.3.6.1.4.1.42.2.27.8.1.2
120 NAME 'pwdMinAge'
121 EQUALITY integerMatch
122 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
123 SINGLE-VALUE )
124 pwdMaxAge
126 This attribute contains the number of seconds after which a modified
128 password will expire. If this attribute is not present, or if its
129 value is zero (0), then passwords will not expire.
130 ( 1.3.6.1.4.1.42.2.27.8.1.3
132 NAME 'pwdMaxAge'
133 EQUALITY integerMatch
134 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
135 SINGLE-VALUE )
136 pwdInHistory
138 This attribute is used to specify the maximum number of used passwords
140 that will be stored in the pwdHistory attribute. If the pwdInHistory
141 attribute is not present, or if its value is zero (0), used passwords
142 will not be stored in pwdHistory and thus any previously-used password
143 may be reused. No history checking occurs if the password is being
144 modified by the rootdn, although the password is saved in the history.
145 ( 1.3.6.1.4.1.42.2.27.8.1.4
147 NAME 'pwdInHistory'
148 EQUALITY integerMatch
149 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
150 SINGLE-VALUE )
151 pwdCheckQuality
153 This attribute indicates if and how password syntax will be checked
155 while a password is being modified or added. If this attribute is not
156 present, or its value is zero (0), no syntax checking will be done. If
157 its value is one (1), the server will check the syntax, and if the
158 server is unable to check the syntax, whether due to a client-side
159 hashed password or some other reason, it will be accepted. If its value
160 is two (2), the server will check the syntax, and if the server is
161 unable to check the syntax it will return an error refusing the pass‐
162 word.
163 ( 1.3.6.1.4.1.42.2.27.8.1.5
165 NAME 'pwdCheckQuality'
166 EQUALITY integerMatch
167 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
168 SINGLE-VALUE )
169 pwdMinLength
171 When syntax checking is enabled (see also the pwdCheckQuality
173 attribute), this attribute contains the minimum number of characters
174 that will be accepted in a password. If this attribute is not present,
175 minimum password length is not enforced. If the server is unable to
176 check the length of the password, whether due to a client-side hashed
177 password or some other reason, the server will, depending on the value
178 of pwdCheckQuality, either accept the password without checking it (if
179 pwdCheckQuality is zero (0) or one (1)) or refuse it (if pwdCheckQual‐
180 ity is two (2)).
181 ( 1.3.6.1.4.1.42.2.27.8.1.6
183 NAME 'pwdMinLength'
184 EQUALITY integerMatch
185 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
186 SINGLE-VALUE )
187 pwdExpireWarning
189 This attribute contains the maximum number of seconds before a password
191 is due to expire that expiration warning messages will be returned to a
192 user who is authenticating to the directory. If this attribute is not
193 present, or if the value is zero (0), no warnings will be sent.
194 ( 1.3.6.1.4.1.42.2.27.8.1.7
196 NAME 'pwdExpireWarning'
197 EQUALITY integerMatch
198 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
199 SINGLE-VALUE )
200 pwdGraceAuthnLimit
202 This attribute contains the number of times that an expired password
204 may be used to authenticate a user to the directory. If this attribute
205 is not present or if its value is zero (0), users with expired pass‐
206 words will not be allowed to authenticate to the directory.
207 ( 1.3.6.1.4.1.42.2.27.8.1.8
209 NAME 'pwdGraceAuthnLimit'
210 EQUALITY integerMatch
211 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
212 SINGLE-VALUE )
213 pwdLockout
215 This attribute specifies the action that should be taken by the direc‐
217 tory when a user has made a number of failed attempts to authenticate
218 to the directory. If pwdLockout is set (its value is "TRUE"), the user
219 will not be allowed to attempt to authenticate to the directory after
220 there have been a specified number of consecutive failed bind attempts.
221 The maximum number of consecutive failed bind attempts allowed is spec‐
222 ified by the pwdMaxFailure attribute. If pwdLockout is not present, or
223 if its value is "FALSE", the password may be used to authenticate no
224 matter how many consecutive failed bind attempts have been made.
225 ( 1.3.6.1.4.1.42.2.27.8.1.9
227 NAME 'pwdLockout'
228 EQUALITY booleanMatch
229 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
230 SINGLE-VALUE )
231 pwdLockoutDuration
233 This attribute contains the number of seconds during which the password
235 cannot be used to authenticate the user to the directory due to too
236 many consecutive failed bind attempts. (See also pwdLockout and pwd‐
237 MaxFailure.) If pwdLockoutDuration is not present, or if its value is
238 zero (0), the password cannot be used to authenticate the user to the
239 directory again until it is reset by an administrator.
240 ( 1.3.6.1.4.1.42.2.27.8.1.10
242 NAME 'pwdLockoutDuration'
243 EQUALITY integerMatch
244 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
245 SINGLE-VALUE )
246 pwdMaxFailure
248 This attribute contains the number of consecutive failed bind attempts
250 after which the password may not be used to authenticate a user to the
251 directory. If pwdMaxFailure is not present, or its value is zero (0),
252 then a user will be allowed to continue to attempt to authenticate to
253 the directory, no matter how many consecutive failed bind attempts have
254 occurred with that user's DN. (See also pwdLockout and pwdLockoutDura‐
255 tion.)
256 ( 1.3.6.1.4.1.42.2.27.8.1.11
258 NAME 'pwdMaxFailure'
259 EQUALITY integerMatch
260 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
261 SINGLE-VALUE )
262 pwdFailureCountInterval
264 This attribute contains the number of seconds after which old consecu‐
266 tive failed bind attempts are purged from the failure counter, even
267 though no successful authentication has occurred. If pwdFailure‐
268 CountInterval is not present, or its value is zero (0), the failure
269 counter will only be reset by a successful authentication.
270 ( 1.3.6.1.4.1.42.2.27.8.1.12
272 NAME 'pwdFailureCountInterval'
273 EQUALITY integerMatch
274 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
275 SINGLE-VALUE )
276 pwdMustChange
278 This attribute specifies whether users must change their passwords when
280 they first bind to the directory after a password is set or reset by
281 the administrator, or not. If pwdMustChange has a value of "TRUE",
282 users must change their passwords when they first bind to the directory
283 after a password is set or reset by the administrator. If pwd‐
284 MustChange is not present, or its value is "FALSE", users are not
285 required to change their password upon binding after the administrator
286 sets or resets the password.
287 ( 1.3.6.1.4.1.42.2.27.8.1.13
289 NAME 'pwdMustChange'
290 EQUALITY booleanMatch
291 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
292 SINGLE-VALUE )
293 pwdAllowUserChange
295 This attribute specifies whether users are allowed to change their own
297 passwords or not. If pwdAllowUserChange is set to "TRUE", or if the
298 attribute is not present, users will be allowed to change their own
299 passwords. If its value is "FALSE", users will not be allowed to
300 change their own passwords.
301 ( 1.3.6.1.4.1.42.2.27.8.1.14
303 NAME 'pwdAllowUserChange'
304 EQUALITY booleanMatch
305 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
306 SINGLE-VALUE )
307 pwdSafeModify
309 This attribute denotes whether the user's existing password must be
311 sent along with their new password when changing a password. If pwd‐
312 SafeModify is set to "TRUE", the existing password must be sent along
313 with the new password. If the attribute is not present, or its value
314 is "FALSE", the existing password need not be sent along with the new
315 password.
316 ( 1.3.6.1.4.1.42.2.27.8.1.15
318 NAME 'pwdSafeModify'
319 EQUALITY booleanMatch
320 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
321 SINGLE-VALUE )
322 pwdCheckModule
324 This attribute names a user-defined loadable module that must instanti‐
326 ate the check_password() function. This function will be called to
327 further check a new password if pwdCheckQuality is set to one (1) or
328 two (2), after all of the built-in password compliance checks have been
329 passed. This function will be called according to this function proto‐
330 type:
331 int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
332 The pPasswd parameter contains the clear-text user password, the
333 ppErrStr parameter contains a double pointer that allows the function
334 to return human-readable details about any error it encounters. The
335 optional pEntry parameter, if non-NULL, carries a pointer to the entry
336 whose password is being checked. If ppErrStr is NULL, then funcName
337 must NOT attempt to use it/them. A return value of LDAP_SUCCESS from
338 the called function indicates that the password is ok, any other value
339 indicates that the password is unacceptable. If the password is unac‐
340 ceptable, the server will return an error to the client, and ppErrStr
341 may be used to return a human-readable textual explanation of the
342 error. The error string must be dynamically allocated as it will be
343 free()'d by slapd.
344 ( 1.3.6.1.4.1.4754.1.99.1
346 NAME 'pwdCheckModule'
347 EQUALITY caseExactIA5Match
348 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
349 SINGLE-VALUE )
350 Note: The user-defined loadable module named by pwdCheckModule must be
352 in slapd's standard executable search PATH.
353 Note: pwdCheckModule is a non-standard extension to the LDAP password
355 policy proposal.
356
359 The operational attributes used by the passwd_policy module are stored
360 in the user's entry. Most of these attributes are not intended to be
361 changed directly by users; they are there to track user activity. They
362 have been detailed here so that administrators and users can both
363 understand the workings of the ppolicy module.
364 userPassword
366 The attribute is not strictly part of the ppolicy module. It is, how‐
368 ever, the attribute that is tracked and controlled by the module.
369 Please refer to the standard OpenLDAP schema for its definition.
370 pwdPolicySubentry
372 This attribute refers directly to the pwdPolicy subentry that is to be
374 used for this particular directory user. If pwdPolicySubentry exists,
375 it must contain the DN of a valid pwdPolicy object. If it does not
376 exist, the ppolicy module will enforce the default password policy
377 rules on the user associated with this authenticating DN. If there is
378 no default, or the referenced subentry does not exist, then no policy
379 rules will be enforced.
380 ( 1.3.6.1.4.1.42.2.27.8.1.23
382 NAME 'pwdPolicySubentry'
383 DESC 'The pwdPolicy subentry in effect for
384 this object'
385 EQUALITY distinguishedNameMatch
386 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
387 SINGLE-VALUE
388 NO-USER-MODIFICATION
389 USAGE directoryOperation)
390 pwdChangedTime
392 This attribute denotes the last time that the entry's password was
394 changed. This value is used by the password expiration policy to
395 determine whether the password is too old to be allowed to be used for
396 user authentication. If pwdChangedTime does not exist, the user's
397 password will not expire.
398 ( 1.3.6.1.4.1.42.2.27.8.1.16
400 NAME 'pwdChangedTime'
401 DESC 'The time the password was last changed'
402 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
403 EQUALITY generalizedTimeMatch
404 ORDERING generalizedTimeOrderingMatch
405 SINGLE-VALUE
406 NO-USER-MODIFICATION
407 USAGE directoryOperation)
408 pwdAccountLockedTime
410 This attribute contains the time that the user's account was locked.
412 If the account has been locked, the password may no longer be used to
413 authenticate the user to the directory. If pwdAccountLockedTime is set
414 to zero (0), the user's account has been permanently locked and may
415 only be unlocked by an administrator.
416 ( 1.3.6.1.4.1.42.2.27.8.1.17
418 NAME 'pwdAccountLockedTime'
419 DESC 'The time an user account was locked'
420 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
421 EQUALITY generalizedTimeMatch
422 ORDERING generalizedTimeOrderingMatch
423 SINGLE-VALUE
424 NO-USER-MODIFICATION
425 USAGE directoryOperation)
426 pwdFailureTime
428 This attribute contains the timestamps of each of the consecutive
430 authentication failures made upon attempted authentication to this DN
431 (i.e. account). If too many timestamps accumulate here (refer to the
432 pwdMaxFailure password policy attribute for details), and the pwdLock‐
433 out password policy attribute is set to "TRUE", the account may be
434 locked. (Please also refer to the pwdLockout password policy
435 attribute.) Excess timestamps beyond those allowed by pwdMaxFailure
436 may also be purged. If a successful authentication is made to this DN
437 (i.e. to this user account), then pwdFailureTime will be cleansed of
438 entries.
439 ( 1.3.6.1.4.1.42.2.27.8.1.19
441 NAME 'pwdFailureTime'
442 DESC 'The timestamps of the last consecutive
443 authentication failures'
444 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
445 EQUALITY generalizedTimeMatch
446 ORDERING generalizedTimeOrderingMatch
447 NO-USER-MODIFICATION
448 USAGE directoryOperation )
449 pwdHistory
451 This attribute contains the history of previously used passwords for
453 this DN (i.e. for this user account). The values of this attribute are
454 stored in string format as follows:
455 pwdHistory=
458 time "#" syntaxOID "#" length "#" data
459 time=
461 generalizedTimeString as specified in section 6.14 of [RFC2252]
462 syntaxOID = numericoid
465 This is the string representation of the dotted-decimal OID
466 that defines the syntax used to store the password. numericoid
467 is described in section 4.1 of [RFC2252].
468 length = numericstring
470 The number of octets in the data. numericstring is described
471 in section 4.1 of [RFC2252].
472 data =
474 Octets representing the password in the format specified by
475 syntaxOID.
476 This format allows the server to store and transmit a history of pass‐
479 words that have been used. In order for equality matching on the val‐
480 ues in this attribute to function properly, the time field is in GMT
481 format.
482 ( 1.3.6.1.4.1.42.2.27.8.1.20
484 NAME 'pwdHistory'
485 DESC 'The history of user passwords'
486 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
487 EQUALITY octetStringMatch
488 NO-USER-MODIFICATION
489 USAGE directoryOperation)
490 pwdGraceUseTime This attribute contains the list of timestamps of
492 logins made after the user password in the DN has expired. These post-
493 expiration logins are known as "grace logins". If too many grace
494 logins have been used (please refer to the pwdGraceLoginLimit password
495 policy attribute), then the DN will no longer be allowed to be used to
496 authenticate the user to the directory until the administrator changes
497 the DN's userPassword attribute.
498 ( 1.3.6.1.4.1.42.2.27.8.1.21
500 NAME 'pwdGraceUseTime'
501 DESC 'The timestamps of the grace login once the password has
502 expired'
503 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
504 EQUALITY generalizedTimeMatch
505 NO-USER-MODIFICATION
506 USAGE directoryOperation)
507 pwdReset
509 This attribute indicates whether the user's password has been reset by
511 the administrator and thus must be changed upon first use of this DN
512 for authentication to the directory. If pwdReset is set to "TRUE",
513 then the password was reset and the user must change it upon first
514 authentication. If the attribute does not exist, or is set to "FALSE",
515 the user need not change their password due to administrative reset.
516 ( 1.3.6.1.4.1.42.2.27.8.1.22
518 NAME 'pwdReset'
519 DESC 'The indication that the password has
520 been reset'
521 EQUALITY booleanMatch
522 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
523 SINGLE-VALUE
524 USAGE directoryOperation)
525
528 database bdb
529 suffix dc=example,dc=com
530 overlay ppolicy
531 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
532
535 ldap(3), slapd.conf(5),
536 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
538 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
540 Sermersheim: documented in IETF document "draft-behera-ldap-password-
541 policy-09.txt".
542
545 The LDAP Password Policy specification is not yet an approved standard,
546 and it is still evolving. This code will continue to be in flux until
547 the specification is finalized.
548
551 This module was written in 2004 by Howard Chu of Symas Corporation with
552 significant input from Neil Dunbar and Kartik Subbarao of Hewlett-
553 Packard.
554 This manual page borrows heavily and shamelessly from the specification
556 upon which the password policy module it describes is based. This
557 source is the IETF LDAP password policy proposal by P. Behera, L.
558 Poitou and J. Sermersheim. The proposal is fully documented in the
559 IETF document named draft-behera-ldap-password-policy-09.txt, written
560 in July of 2005.
561 OpenLDAP is developed and maintained by The OpenLDAP Project
563 (http://www.openldap.org/). OpenLDAP is derived from University of
564 Michigan LDAP 3.3 Release.
565OpenLDAP 2.3.34 2007/2/16 SLAPO_PPOLICY(5)