1 .TH SLAPO_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 2004-2018 The OpenLDAP Foundation All Rights Reserved.
3 .\" Copying restrictions apply. See COPYRIGHT/LICENSE.
6 slapo\-ppolicy \- Password Policy overlay to slapd
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
27 Note that some of the policies do not take effect when the operation
30 identity; all the operations, when performed with any other identity,
31 may be subjected to constraints, like access control. This overlay
32 requires a rootdn to be configured on the database.
34 Note that the IETF Password Policy proposal for LDAP makes sense
35 when considering a single-valued password attribute, while
36 the userPassword attribute allows multiple values. This implementation
37 enforces a single value for the userPassword attribute, despite
43 configuration options apply to the ppolicy overlay. They should appear
48 .B ppolicy_default <policyDN>
49 Specify the DN of the pwdPolicy object to use when no specific policy is
50 set on a given user's entry. If there is no specific policy for an entry
51 and no default is given, then no policies will be enforced.
53 .B ppolicy_forward_updates
54 Specify that policy state changes that result from Bind operations (such
55 as recording failures, lockout, etc.) on a consumer should be forwarded
56 to a master instead of being written directly into the consumer's local
57 database. This setting is only useful on a replication consumer, and
62 overlay to be appropriately configured.
64 .B ppolicy_hash_cleartext
65 Specify that cleartext passwords present in Add and Modify requests should
66 be hashed before being stored in the database. This violates the X.500/LDAP
67 information model, but may be needed to compensate for LDAP clients that
68 don't use the Password Modify extended operation to manage passwords. It
69 is recommended that when this option is used that compare, search, and
70 read access be denied to all directory users.
72 .B ppolicy_use_lockout
73 A client will always receive an LDAP
76 Binding to a locked account. By default, when a Password Policy control
77 was provided on the Bind request, a Password Policy response will be
78 included with no special error code set. This option changes the
79 Password Policy response to include the
84 error code provides useful information
85 to an attacker; sites that are sensitive to security issues should not
91 overlay depends on the
93 object class. The definition of that class is as follows:
96 ( 1.3.6.1.4.1.42.2.27.8.2.1
100 MUST ( pwdAttribute )
102 pwdMinAge $ pwdMaxAge $ pwdInHistory $
103 pwdCheckQuality $ pwdMinLength $
104 pwdExpireWarning $ pwdGraceAuthnLimit $
105 pwdLockout $ pwdLockoutDuration $
106 pwdMaxFailure $ pwdFailureCountInterval $
107 pwdMustChange $ pwdAllowUserChange $
108 pwdSafeModify $ pwdMaxRecordedFailure ) )
111 This implementation also provides an additional
113 objectclass, used for password quality checking (see below).
116 ( 1.3.6.1.4.1.4754.2.99.1
117 NAME 'pwdPolicyChecker'
120 MAY ( pwdCheckModule ) )
123 Every account that should be subject to password policy control should
127 attribute containing the DN of a valid
129 entry, or they can simply use the configured default.
130 In this way different users may be managed according to
133 .SH OBJECT CLASS ATTRIBUTES
135 Each one of the sections below details the meaning and use of a particular
143 This attribute contains the name of the attribute to which the password
144 policy is applied. For example, the password policy may be applied
149 Note: in this implementation, the only
153 .IR " userPassword ".
156 ( 1.3.6.1.4.1.42.2.27.8.1.1
158 EQUALITY objectIdentifierMatch
159 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
164 This attribute contains the number of seconds that must elapse
165 between modifications allowed to the password. If this attribute
166 is not present, zero seconds is assumed (i.e. the password may be
167 modified whenever and however often is desired).
170 ( 1.3.6.1.4.1.42.2.27.8.1.2
172 EQUALITY integerMatch
173 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
179 This attribute contains the number of seconds after which a modified
180 password will expire. If this attribute is not present, or if its
181 value is zero (0), then passwords will not expire.
184 ( 1.3.6.1.4.1.42.2.27.8.1.3
186 EQUALITY integerMatch
187 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
193 This attribute is used to specify the maximum number of used
194 passwords that will be stored in the
198 attribute is not present, or if its value is
199 zero (0), used passwords will not be stored in
201 and thus any previously-used password may be reused.
202 No history checking occurs if the password is being modified by the
204 although the password is saved in the history.
207 ( 1.3.6.1.4.1.42.2.27.8.1.4
209 EQUALITY integerMatch
210 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
216 This attribute indicates if and how password syntax will be checked
217 while a password is being modified or added. If this attribute is
218 not present, or its value is zero (0), no syntax checking will be
219 done. If its value is one (1), the server will check the syntax,
220 and if the server is unable to check the syntax,
221 whether due to a client-side hashed password or some other reason,
223 accepted. If its value is two (2), the server will check the syntax,
224 and if the server is unable to check the syntax it will return an
225 error refusing the password.
228 ( 1.3.6.1.4.1.42.2.27.8.1.5
229 NAME 'pwdCheckQuality'
230 EQUALITY integerMatch
231 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
237 When syntax checking is enabled
240 attribute), this attribute contains the minimum
241 number of characters that will be accepted in a password. If this
242 attribute is not present, minimum password length is not
243 enforced. If the server is unable to check the length of the password,
244 whether due to a client-side hashed password or some other reason,
245 the server will, depending on the
247 .BR pwdCheckQuality ,
248 either accept the password
249 without checking it (if
251 is zero (0) or one (1)) or refuse it (if
256 ( 1.3.6.1.4.1.42.2.27.8.1.6
258 EQUALITY integerMatch
259 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
265 This attribute contains the maximum number of seconds before a
266 password is due to expire that expiration warning messages will be
267 returned to a user who is authenticating to the directory.
268 If this attribute is not
269 present, or if the value is zero (0), no warnings will be sent.
272 ( 1.3.6.1.4.1.42.2.27.8.1.7
273 NAME 'pwdExpireWarning'
274 EQUALITY integerMatch
275 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
279 .B pwdGraceAuthnLimit
281 This attribute contains the number of times that an expired password
282 may be used to authenticate a user to the directory. If this
283 attribute is not present or if its value is zero (0), users with
284 expired passwords will not be allowed to authenticate to the
288 ( 1.3.6.1.4.1.42.2.27.8.1.8
289 NAME 'pwdGraceAuthnLimit'
290 EQUALITY integerMatch
291 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
297 This attribute specifies the action that should be taken
298 by the directory when a user has made a number of failed attempts
299 to authenticate to the directory. If
301 is set (its value is "TRUE"), the user will not be allowed to
302 attempt to authenticate to the directory after there have been a
303 specified number of consecutive failed bind attempts. The maximum
304 number of consecutive failed bind attempts allowed is specified by
309 is not present, or if its value is "FALSE", the password may be
310 used to authenticate no matter how many consecutive failed bind
311 attempts have been made.
314 ( 1.3.6.1.4.1.42.2.27.8.1.9
316 EQUALITY booleanMatch
317 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
321 .B pwdLockoutDuration
323 This attribute contains the number of seconds during
324 which the password cannot be used to authenticate the
325 user to the directory due to too many consecutive failed
332 .B pwdLockoutDuration
333 is not present, or if its value is zero (0), the password
334 cannot be used to authenticate the user to the directory
335 again until it is reset by an administrator.
338 ( 1.3.6.1.4.1.42.2.27.8.1.10
339 NAME 'pwdLockoutDuration'
340 EQUALITY integerMatch
341 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
347 This attribute contains the number of consecutive failed bind
348 attempts after which the password may not be used to authenticate
349 a user to the directory.
352 is not present, or its value is zero (0), then a user will
353 be allowed to continue to attempt to authenticate to
354 the directory, no matter how many consecutive failed
355 bind attempts have occurred with that user's DN.
359 .BR pwdLockoutDuration .)
362 ( 1.3.6.1.4.1.42.2.27.8.1.11
364 EQUALITY integerMatch
365 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
369 .B pwdMaxRecordedFailure
371 This attribute contains the maximum number of failed bind
372 attempts to store in a user's entry.
374 .B pwdMaxRecordedFailure
375 is not present, or its value is zero (0), then it defaults
378 If that value is also 0, the default is 5.
381 ( 1.3.6.1.4.1.42.2.27.8.1.16
382 NAME 'pwdMaxRecordedFailure'
383 EQUALITY integerMatch
384 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
388 .B pwdFailureCountInterval
390 This attribute contains the number of seconds after which old
391 consecutive failed bind attempts are purged from the failure counter,
392 even though no successful authentication has occurred.
394 .B pwdFailureCountInterval
395 is not present, or its value is zero (0), the failure
396 counter will only be reset by a successful authentication.
399 ( 1.3.6.1.4.1.42.2.27.8.1.12
400 NAME 'pwdFailureCountInterval'
401 EQUALITY integerMatch
402 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
408 This attribute specifies whether users must change their passwords
409 when they first bind to the directory after a password is set or
410 reset by the administrator, or not. If
412 has a value of "TRUE", users must change their passwords when they
413 first bind to the directory after a password is set or reset by
414 the administrator. If
416 is not present, or its value is "FALSE",
417 users are not required to change their password upon binding after
418 the administrator sets or resets the password.
421 ( 1.3.6.1.4.1.42.2.27.8.1.13
423 EQUALITY booleanMatch
424 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
428 .B pwdAllowUserChange
430 This attribute specifies whether users are allowed to change their own
432 .B pwdAllowUserChange
433 is set to "TRUE", or if the attribute is not present, users will be
434 allowed to change their own passwords. If its value is "FALSE",
435 users will not be allowed to change their own passwords.
437 Note: this implies that when
438 .B pwdAllowUserChange
440 users will still be able to change the password of another user,
441 subjected to access control.
442 This restriction only applies to modifications of ones's own password.
443 It should also be noted that
444 .B pwdAllowUserChange
445 was defined in the specification to provide rough access control
446 to the password attribute in implementations that do not allow fine-grain
448 Since OpenLDAP provides fine-grain access control, the use of this attribute
449 is discouraged; ACLs should be used instead
455 ( 1.3.6.1.4.1.42.2.27.8.1.14
456 NAME 'pwdAllowUserChange'
457 EQUALITY booleanMatch
458 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
464 This attribute denotes whether the user's existing password must be sent
465 along with their new password when changing a password. If
467 is set to "TRUE", the existing password must be sent
468 along with the new password. If the attribute is not present, or
469 its value is "FALSE", the existing password need not be sent
470 along with the new password.
473 ( 1.3.6.1.4.1.42.2.27.8.1.15
475 EQUALITY booleanMatch
476 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
482 This attribute names a user-defined loadable module that must
483 instantiate the check_password() function. This function
484 will be called to further check a new password if
486 is set to one (1) or two (2),
487 after all of the built-in password compliance checks have
488 been passed. This function will be called according to this
493 (char *pPasswd, char **ppErrStr, Entry *pEntry);
497 parameter contains the clear-text user password, the
499 parameter contains a double pointer that allows the function
500 to return human-readable details about any error it encounters.
503 parameter, if non-NULL, carries a pointer to the
504 entry whose password is being checked.
509 must NOT attempt to use it/them.
510 A return value of LDAP_SUCCESS from the called
511 function indicates that the password is ok, any other value
512 indicates that the password is unacceptable. If the password is
513 unacceptable, the server will return an error to the client, and
515 may be used to return a human-readable textual explanation of the
516 error. The error string must be dynamically allocated as it will
517 be free()'d by slapd.
520 ( 1.3.6.1.4.1.4754.1.99.1
521 NAME 'pwdCheckModule'
522 EQUALITY caseExactIA5Match
523 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
528 The user-defined loadable module named by
532 standard executable search PATH.
536 is a non-standard extension to the LDAP password
539 .SH OPERATIONAL ATTRIBUTES
541 The operational attributes used by the
543 module are stored in the user's entry. Most of these attributes
544 are not intended to be changed directly by users; they are there
545 to track user activity. They have been detailed here so that
546 administrators and users can both understand the workings of
552 Note that the current IETF Password Policy proposal does not define
553 how these operational attributes are expected to behave in a
554 replication environment. In general, authentication attempts on
555 a slave server only affect the copy of the operational attributes
556 on that slave and will not affect any attributes for
557 a user's entry on the master server. Operational attribute changes
558 resulting from authentication attempts on a master server
559 will usually replicate to the slaves (and also overwrite
560 any changes that originated on the slave).
561 These behaviors are not guaranteed and are subject to change
562 when a formal specification emerges.
568 attribute is not strictly part of the
570 module. It is, however, the attribute that is tracked and controlled
571 by the module. Please refer to the standard OpenLDAP schema for
576 This attribute refers directly to the
578 subentry that is to be used for this particular directory user.
581 exists, it must contain the DN of a valid
583 object. If it does not exist, the
585 module will enforce the default password policy rules on the
586 user associated with this authenticating DN. If there is no
587 default, or the referenced subentry does not exist, then no
588 policy rules will be enforced.
591 ( 1.3.6.1.4.1.42.2.27.8.1.23
592 NAME 'pwdPolicySubentry'
593 DESC 'The pwdPolicy subentry in effect for
595 EQUALITY distinguishedNameMatch
596 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
598 NO\-USER\-MODIFICATION
599 USAGE directoryOperation)
604 This attribute denotes the last time that the entry's password was
605 changed. This value is used by the password expiration policy to
606 determine whether the password is too old to be allowed to be used
607 for user authentication. If
609 does not exist, the user's password will not expire.
612 ( 1.3.6.1.4.1.42.2.27.8.1.16
613 NAME 'pwdChangedTime'
614 DESC 'The time the password was last changed'
615 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
616 EQUALITY generalizedTimeMatch
617 ORDERING generalizedTimeOrderingMatch
619 NO\-USER\-MODIFICATION
620 USAGE directoryOperation)
623 .B pwdAccountLockedTime
625 This attribute contains the time that the user's account was locked.
626 If the account has been locked, the password may no longer be used to
627 authenticate the user to the directory. If
628 .B pwdAccountLockedTime
629 is set to 000001010000Z, the user's account has been permanently locked
630 and may only be unlocked by an administrator. Note that account locking
631 only takes effect when the
633 password policy attribute is set to "TRUE".
636 ( 1.3.6.1.4.1.42.2.27.8.1.17
637 NAME 'pwdAccountLockedTime'
638 DESC 'The time an user account was locked'
639 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
640 EQUALITY generalizedTimeMatch
641 ORDERING generalizedTimeOrderingMatch
643 NO\-USER\-MODIFICATION
644 USAGE directoryOperation)
649 This attribute contains the timestamps of each of the consecutive
650 authentication failures made upon attempted authentication to this
651 DN (i.e. account). If too many timestamps accumulate here (refer to
654 password policy attribute for details),
657 password policy attribute is set to "TRUE", the
658 account may be locked.
659 (Please also refer to the
661 password policy attribute.)
662 Excess timestamps beyond those allowed by
665 .B pwdMaxRecordedFailure
666 may also be purged. If a successful authentication is made to this
667 DN (i.e. to this user account), then
669 will be cleansed of entries.
672 ( 1.3.6.1.4.1.42.2.27.8.1.19
673 NAME 'pwdFailureTime'
674 DESC 'The timestamps of the last consecutive
675 authentication failures'
676 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
677 EQUALITY generalizedTimeMatch
678 ORDERING generalizedTimeOrderingMatch
679 NO\-USER\-MODIFICATION
680 USAGE directoryOperation )
685 This attribute contains the history of previously used passwords
686 for this DN (i.e. for this user account).
687 The values of this attribute are stored in string format as follows:
693 time "#" syntaxOID "#" length "#" data
698 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
702 syntaxOID = numericoid
704 This is the string representation of the dotted-decimal OID that
705 defines the syntax used to store the password. numericoid is
706 described in section 1.4 of [RFC4512].
709 length = NumericString
711 The number of octets in the data. NumericString is described in
712 section 3.3.23 of [RFC4517].
717 Octets representing the password in the format specified by syntaxOID.
722 This format allows the server to store and transmit a history of
723 passwords that have been used. In order for equality matching
724 on the values in this attribute to function properly, the time
725 field is in GMT format.
728 ( 1.3.6.1.4.1.42.2.27.8.1.20
730 DESC 'The history of user passwords'
731 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
732 EQUALITY octetStringMatch
733 NO\-USER\-MODIFICATION
734 USAGE directoryOperation)
738 This attribute contains the list of timestamps of logins made after
739 the user password in the DN has expired. These post-expiration
740 logins are known as "\fIgrace logins\fP".
743 have been used (please refer to the
744 .B pwdGraceLoginLimit
745 password policy attribute), then the DN will no longer be allowed
746 to be used to authenticate the user to the directory until the
747 administrator changes the DN's
752 ( 1.3.6.1.4.1.42.2.27.8.1.21
753 NAME 'pwdGraceUseTime'
754 DESC 'The timestamps of the grace login once the password has expired'
755 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
756 EQUALITY generalizedTimeMatch
757 NO\-USER\-MODIFICATION
758 USAGE directoryOperation)
763 This attribute indicates whether the user's password has been reset
764 by the administrator and thus must be changed upon first use of this
765 DN for authentication to the directory. If
767 is set to "TRUE", then the password was reset and the user must change
768 it upon first authentication. If the attribute does not exist, or
769 is set to "FALSE", the user need not change their password due to
770 administrative reset.
773 ( 1.3.6.1.4.1.42.2.27.8.1.22
775 DESC 'The indication that the password has
777 EQUALITY booleanMatch
778 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
780 USAGE directoryOperation)
788 suffix dc=example,dc=com
791 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
798 .BR slapd\-config (5),
799 .BR slapo\-chain (5).
801 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
803 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
804 Sermersheim: documented in IETF document
805 "draft-behera-ldap-password-policy-09.txt".
808 The LDAP Password Policy specification is not yet an approved standard,
809 and it is still evolving. This code will continue to be in flux until the
810 specification is finalized.
814 This module was written in 2004 by Howard Chu of Symas Corporation
815 with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
817 This manual page borrows heavily and shamelessly from the specification
818 upon which the password policy module it describes is based. This
820 IETF LDAP password policy proposal by P. Behera, L.
821 Poitou and J. Sermersheim.
822 The proposal is fully documented in
824 IETF document named draft-behera-ldap-password-policy-09.txt,
825 written in July of 2005.