2 .\" Copyright 2004 The OpenLDAP Foundation All Rights Reserved.
3 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
4 .TH SLAPO_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
6 slapo-ppolicy \- Password Policy overlay
14 is an implementation of the most recent IETF Password
15 Policy proposal for LDAP. When instantiated, it intercepts,
16 decodes and applies specific password policy controls to overall
17 use of a backend database, changes to user password fields, etc.
19 The overlay provides a variety of password control mechanisms. They
20 include password aging--both minimum and maximum ages, password
21 reuse and duplication control, account time-outs, mandatory password
22 resets, acceptable password content, and even grace logins.
23 Different groups of users may be associated with different password
24 policies, and there is no limit to the number of password policies
30 configuration options apply to the ppolicy overlay. They should appear
35 .B ppolicy_default <policyDN>
36 Specify the DN of the pwdPolicy object to use when no specific policy is
37 set on a given user's entry. If there is no specific policy for an entry
38 and no default is given, then no policies will be enforced.
40 .B ppolicy_use_lockout
41 A client will always receive an LDAP
44 Binding to a locked account. By default, when a Password Policy control
45 was provided on the Bind request, a Password Policy response will be
46 included with no special error code set. This option changes the
47 Password Policy response to include the
52 error code provides useful information
53 to an attacker; sites that are sensitive to security issues should not
59 overlay depends on the
61 object class. The definition of that class is as follows:
64 ( 1.3.6.1.4.1.42.2.27.8.2.1
70 pwdMinAge $ pwdMaxAge $ pwdInHistory $
71 pwdCheckSyntax $ pwdMinLength $
72 pwdExpireWarning $ pwdGraceLoginLimit $
73 pwdLockout $ pwdLockoutDuration $
74 pwdMaxFailure $ pwdFailureCountInterval $
75 pwdMustChange $ pwdAllowUserChange $
79 This implementation also provides an additional
81 objectclass, used for password quality checking (see below).
84 ( 1.3.6.1.4.1.4754.2.99.1
85 NAME 'pwdPolicyChecker'
88 MAY ( pwdCheckModule ) )
91 Every account that should be subject to password policy control should
95 attribute containing the DN of a valid
97 entry, or they can simply use the configured default.
98 In this way different users may be managed according to
101 .SH OBJECT CLASS ATTRIBUTES
103 Each one of the sections below details the meaning and use of a particular
111 This attribute contains the name of the attribute to which the password
112 policy is applied. For example, the password policy may be applied
117 Note: in this implementation, the only
121 .RI " userPassword ".
124 ( 1.3.6.1.4.1.42.2.27.8.1.1
126 EQUALITY objectIdentifierMatch
127 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
132 This attribute contains the number of seconds that must elapse
133 between modifications allowed to the password. If this attribute
134 is not present, zero seconds is assumed (i.e. the password may be
135 modified whenever and however often is desired).
138 ( 1.3.6.1.4.1.42.2.27.8.1.2
140 EQUALITY integerMatch
141 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
147 This attribute contains the number of seconds after which a modified
148 password will expire. If this attribute is not present, or if its
149 value is zero (0), then passwords will not expire.
152 ( 1.3.6.1.4.1.42.2.27.8.1.3
154 EQUALITY integerMatch
155 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
161 This attribute is used to specify the maximum number of used
162 passwords that will be stored in the
166 attribute is not present, or if its value is
167 zero (0), used passwords will not be stored in
169 and thus any previously-used password may be reused.
172 ( 1.3.6.1.4.1.42.2.27.8.1.4
174 EQUALITY integerMatch
175 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
181 This attribute indicates if and how password syntax will be checked
182 while a password is being modified or added. If this attribute is
183 not present, or its value is zero (0), no syntax checking will be
184 done. If its value is one (1), the server will check the syntax,
185 and if the server is unable to check the syntax,
186 whether due to a client-side hashed password or some other reason,
188 accepted. If its value is two (2), the server will check the syntax,
189 and if the server is unable to check the syntax it will return an
190 error refusing the password.
193 ( 1.3.6.1.4.1.42.2.27.8.1.5
194 NAME 'pwdCheckQuality'
195 EQUALITY integerMatch
196 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
202 When syntax checking is enabled
205 attribute), this attribute contains the minimum
206 number of characters that will be accepted in a password. If this
207 attribute is not present, minimum password length is not
208 enforced. If the server is unable to check the length of the password,
209 whether due to a client-side hashed password or some other reason,
210 the server will, depending on the
213 either accept the password
214 without checking it (if
216 is zero (0) or one (1)) or refuse it (if
221 ( 1.3.6.1.4.1.42.2.27.8.1.6
223 EQUALITY integerMatch
224 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
230 This attribute contains the maximum number of seconds before a
231 password is due to expire that expiration warning messages will be
232 returned to a user who is authenticating to the directory.
233 If this attribute is not
234 present, or if the value is zero (0), no warnings will be sent.
237 ( 1.3.6.1.4.1.42.2.27.8.1.7
238 NAME 'pwdExpireWarning'
239 EQUALITY integerMatch
240 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
244 .B pwdGraceLoginLimit
246 This attribute contains the number of times that an expired password
247 may be used to authenticate a user to the directory. If this
248 attribute is not present or if its value is zero (0), users with
249 expired passwords will not be allowed to authenticate to the
253 ( 1.3.6.1.4.1.42.2.27.8.1.8
254 NAME 'pwdGraceLoginLimit'
255 EQUALITY integerMatch
256 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
262 This attribute specifies the action that should be taken
263 by the directory when a user has made a number of failed attempts
264 to authenticate to the directory. If
266 is set (its value is "TRUE"), the user will not be allowed to
267 attempt to authenticate to the directory after there have been a
268 specified number of consecutive failed bind attempts. The maximum
269 number of consecutive failed bind attempts allowed is specified by
274 is not present, or if its value is "FALSE", the password may be
275 used to authenticate no matter how many consecutive failed bind
276 attempts have been made.
279 ( 1.3.6.1.4.1.42.2.27.8.1.9
281 EQUALITY booleanMatch
282 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
286 .B pwdLockoutDuration
288 This attribute contains the number of seconds during
289 which the password cannot be used to authenticate the
290 user to the directory due to too many consecutive failed
297 .B pwdLockoutDuration
298 is not present, or if its value is zero (0), the password
299 cannot be used to authenticate the user to the directory
300 again until it is reset by an administrator.
303 ( 1.3.6.1.4.1.42.2.27.8.1.10
304 NAME 'pwdLockoutDuration'
305 EQUALITY integerMatch
306 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
312 This attribute contains the number of consecutive failed bind
313 attempts after which the password may not be used to authenticate
314 a user to the directory.
317 is not present, or its value is zero (0), then a user will
318 be allowed to continue to attempt to authenticate to
319 the directory, no matter how many consecutive failed
320 bind attempts have occurred with that user's DN.
324 .BR pwdLockoutDuration .)
327 ( 1.3.6.1.4.1.42.2.27.8.1.11
329 EQUALITY integerMatch
330 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
334 .B pwdFailureCountInterval
336 This attribute contains the number of seconds after which old
337 consecutive failed bind attempts are purged from the failure counter,
338 even though no successful authentication has occurred.
340 .B pwdFailureCountInterval
341 is not present, or its value is zero (0), the failure
342 counter will only be reset by a successful authentication.
345 ( 1.3.6.1.4.1.42.2.27.8.1.12
346 NAME 'pwdFailureCountInterval'
347 EQUALITY integerMatch
348 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
354 This attribute specifies whether users must change their passwords
355 when they first bind to the directory after a password is set or
356 reset by the administrator, or not. If
358 has a value of "TRUE", users must change their passwords when they
359 first bind to the directory after a password is set or reset by
360 the administrator. If
362 is not present, or its value is "FALSE",
363 users are not required to change their password upon binding after
364 the administrator sets or resets the password.
367 ( 1.3.6.1.4.1.42.2.27.8.1.13
369 EQUALITY booleanMatch
370 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
374 .B pwdAllowUserChange
376 This attribute specifies whether users are allowed to change their own
378 .B pwdAllowUserChange
379 is set to "TRUE", or if the attribute is not present, users will be
380 allowed to change their own passwords. If its value is "FALSE",
381 users will not be allowed to change their own passwords.
384 ( 1.3.6.1.4.1.42.2.27.8.1.14
385 NAME 'pwdAllowUserChange'
386 EQUALITY booleanMatch
387 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
393 This attribute denotes whether the user's existing password must be sent
394 along with their new password when changing a password. If
396 is set to "TRUE", the existing password must be sent
397 along with the new password. If the attribute is not present, or
398 its value is "FALSE", the existing password need not be sent
399 along with the new password.
402 ( 1.3.6.1.4.1.42.2.27.8.1.15
404 EQUALITY booleanMatch
405 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
411 This attribute names a user-defined loadable module that must
412 instantiate the check_password() function. This function
413 will be called to further check a new password if
415 is set to one (1) or two (2),
416 after all of the built-in password compliance checks have
417 been passed. This function will be called according to this
422 (char *pPasswd, char **ppErrStr, void *pArg);
426 parameter contains the clear-text user password, the
428 parameter contains a double pointer that allows the function
429 to return human-readable details about any error it encounters.
432 parameter is currently unused.
437 must NOT attempt to use it/them.
438 A return value of LDAP_SUCCESS from the called
439 function indicates that the password is ok, any other value
440 indicates that the password is unacceptable. If the password is
441 unacceptable, the server will return an error to the client, and
443 may be used to return a human-readable textual explanation of the
447 ( 1.3.6.1.4.1.4754.1.99.1
448 NAME 'pwdCheckModule'
449 EQUALITY caseExactIA5Match
450 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
455 The user-defined loadable module named by
459 standard executable search PATH.
463 is a non-standard extension to the LDAP password
466 .SH OPERATIONAL ATTRIBUTES
468 The operational attributes used by the
470 module are stored in the user's entry. Most of these attributes
471 are not intended to be changed directly by users; they are there
472 to track user activity. They have been detailed here so that
473 administrators and users can both understand the workings of
482 attribute is not strictly part of the
484 module. It is, however, the attribute that is tracked and controlled
485 by the module. Please refer to the standard OpenLDAP schema for
490 This attribute refers directly to the
492 subentry that is to be used for this particular directory user.
495 exists, it must contain the DN of a valid
497 object. If it does not exist, the
499 module will enforce the default password policy rules on the
500 user associated with this authenticating DN. If there is no
501 default, or the referenced subentry does not exist, then no
502 policy rules wil be enforced.
505 ( 1.3.6.1.4.1.42.2.27.8.1.23
506 NAME 'pwdPolicySubentry'
507 DESC 'The pwdPolicy subentry in effect for
509 EQUALITY distinguishedNameMatch
510 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
512 USAGE directoryOperation)
517 This attribute denotes the last time that the entry's password was
518 changed. This value is used by the password expiration policy to
519 determine whether the password is too old to be allowed to be used
520 for user authentication. If
522 does not exist, the user's password will not expire.
525 ( 1.3.6.1.4.1.42.2.27.8.1.16
526 NAME 'pwdChangedTime'
527 DESC 'The time the password was last changed'
528 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
529 EQUALITY generalizedTimeMatch
530 ORDERING generalizedTimeOrderingMatch
532 USAGE directoryOperation)
535 .B pwdAccountLockedTime
537 This attribute contains the time that the user's account was locked.
538 If the account has been locked, the password may no longer be used to
539 authenticate the user to the directory. If
540 .B pwdAccountLockedTime
541 is set to zero (0), the user's account has been permanently locked
542 and may only be unlocked by an administrator.
545 ( 1.3.6.1.4.1.42.2.27.8.1.17
546 NAME 'pwdAccountLockedTime'
547 DESC 'The time an user account was locked'
548 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
549 EQUALITY generalizedTimeMatch
550 ORDERING generalizedTimeOrderingMatch
552 USAGE directoryOperation)
555 .B pwdExpirationWarned
557 This attribute denotes the time when the first password
558 expiration warning was sent to the client regarding this account.
559 The amount of time between when this warning is sent and when
560 the password actually expires is the amount of time stored in
563 password policy attribute.
566 ( 1.3.6.1.4.1.42.2.27.8.1.18
567 NAME 'pwdExpirationWarned'
568 DESC 'The time the user was first warned about the
569 coming expiration of their password'
570 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
571 EQUALITY generalizedTimeMatch
572 ORDERING generalizedTimeOrderingMatch
574 USAGE directoryOperation )
579 This attribute contains the timestamps of each of the consecutive
580 authentication failures made upon attempted authentication to this
581 DN (i.e. account). If too many timestamps accumulate here (refer to
584 password policy attribute for details),
587 password policy attribute is set to "TRUE", the
588 account may be locked.
589 (Please also refer to the
591 password policy attribute.)
592 Excess timestamps beyond those allowed by
594 may also be purged. If a successful authentication is made to this
595 DN (i.e. to this user account), then
597 will be cleansed of entries.
600 ( 1.3.6.1.4.1.42.2.27.8.1.19
601 NAME 'pwdFailureTime'
602 DESC 'The timestamps of the last consecutive
603 authentication failures'
604 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
605 EQUALITY generalizedTimeMatch
606 ORDERING generalizedTimeOrderingMatch
607 USAGE directoryOperation )
612 This attribute contains the history of previously used passwords
613 for this DN (i.e. for this user account).
614 The values of this attribute are stored in string format as follows:
620 time "#" syntaxOID "#" length "#" data
625 generalizedTimeString as specified in section 6.14 of [RFC2252]
629 syntaxOID = numericoid
631 This is the string representation of the dotted-decimal OID that
632 defines the syntax used to store the password. numericoid is
633 described in section 4.1 of [RFC2252].
636 length = numericstring
638 The number of octets in the data. numericstring is described in
639 section 4.1 of [RFC2252].
644 Octets representing the password in the format specified by syntaxOID.
649 This format allows the server to store and transmit a history of
650 passwords that have been used. In order for equality matching
651 on the values in this attribute to function properly, the time
652 field is in GMT format.
655 ( 1.3.6.1.4.1.42.2.27.8.1.20
657 DESC 'The history of user passwords'
658 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
659 EQUALITY octetStringMatch
660 USAGE directoryOperation)
664 This attribute contains the list of timestamps of logins made after
665 the user password in the DN has expired. These post-expiration
667 .RI " "grace logins" ."
670 have been used (please refer to the
671 .B pwdGraceLoginLimit
672 password policy attribute), then the DN will no longer be allowed
673 to be used to authenticate the user to the directory until the
674 administrator changes the DN's
679 ( 1.3.6.1.4.1.42.2.27.8.1.21
680 NAME 'pwdGraceUseTime'
681 DESC 'The timestamps of the grace login once the password has expired'
682 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
683 EQUALITY generalizedTimeMatch
684 USAGE directoryOperation)
689 This attribute indicates whether the user's password has been reset
690 by the administrator and thus must be changed upon first use of this
691 DN for authentication to the directory. If
693 is set to "TRUE", then the password was reset and the user must change
694 it upon first authentication. If the attribute does not exist, or
695 is set to "FALSE", the user need not change their password due to
696 administrative reset.
699 ( 1.3.6.1.4.1.42.2.27.8.1.22
701 DESC 'The indication that the password has
703 EQUALITY booleanMatch
704 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
706 USAGE directoryOperation)
714 suffix dc=example,dc=com
717 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
725 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
727 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
728 Sermersheim: documented in IETF document
729 "draft-behera-ldap-password-policy-07.txt".
732 The LDAP Password Policy specification is not yet an approved standard,
733 and it is still evolving. This code will continue to be in flux until the
734 specification is finalized.
738 This module was written in 2004 by Howard Chu of Symas Corporation
739 with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
741 This manual page borrows heavily and shamelessly from the specification
742 upon which the password policy module it describes is based. This
744 IETF LDAP password policy proposal by P. Behera, L.
745 Poitou and J. Sermersheim.
746 The proposal is fully documented in
748 IETF document named draft-behera-ldap-password-policy-07.txt,
749 written in February of 2004.
752 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
754 is derived from University of Michigan LDAP 3.3 Release.