1 .TH SLAPO_PPOLICY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 2004-2016 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.
33 Note that the IETF Password Policy proposal for LDAP makes sense
34 when considering a single-valued password attribute, while
35 the userPassword attribute allows multiple values. This implementation
36 enforces a single value for the userPassword attribute, despite
42 configuration options apply to the ppolicy overlay. They should appear
47 .B ppolicy_default <policyDN>
48 Specify the DN of the pwdPolicy object to use when no specific policy is
49 set on a given user's entry. If there is no specific policy for an entry
50 and no default is given, then no policies will be enforced.
52 .B ppolicy_forward_updates
53 Specify that policy state changes that result from Bind operations (such
54 as recording failures, lockout, etc.) on a consumer should be forwarded
55 to a master instead of being written directly into the consumer's local
56 database. This setting is only useful on a replication consumer, and
61 overlay to be appropriately configured.
63 .B ppolicy_hash_cleartext
64 Specify that cleartext passwords present in Add and Modify requests should
65 be hashed before being stored in the database. This violates the X.500/LDAP
66 information model, but may be needed to compensate for LDAP clients that
67 don't use the Password Modify extended operation to manage passwords. It
68 is recommended that when this option is used that compare, search, and
69 read access be denied to all directory users.
71 .B ppolicy_use_lockout
72 A client will always receive an LDAP
75 Binding to a locked account. By default, when a Password Policy control
76 was provided on the Bind request, a Password Policy response will be
77 included with no special error code set. This option changes the
78 Password Policy response to include the
83 error code provides useful information
84 to an attacker; sites that are sensitive to security issues should not
90 overlay depends on the
92 object class. The definition of that class is as follows:
95 ( 1.3.6.1.4.1.42.2.27.8.2.1
101 pwdMinAge $ pwdMaxAge $ pwdInHistory $
102 pwdCheckQuality $ pwdMinLength $
103 pwdExpireWarning $ pwdGraceAuthnLimit $
104 pwdLockout $ pwdLockoutDuration $
105 pwdMaxFailure $ pwdFailureCountInterval $
106 pwdMustChange $ pwdAllowUserChange $
107 pwdSafeModify 4 pwdMaxRecordedFailure ) )
110 This implementation also provides an additional
112 objectclass, used for password quality checking (see below).
115 ( 1.3.6.1.4.1.4754.2.99.1
116 NAME 'pwdPolicyChecker'
119 MAY ( pwdCheckModule ) )
122 Every account that should be subject to password policy control should
126 attribute containing the DN of a valid
128 entry, or they can simply use the configured default.
129 In this way different users may be managed according to
132 .SH OBJECT CLASS ATTRIBUTES
134 Each one of the sections below details the meaning and use of a particular
142 This attribute contains the name of the attribute to which the password
143 policy is applied. For example, the password policy may be applied
148 Note: in this implementation, the only
152 .IR " userPassword ".
155 ( 1.3.6.1.4.1.42.2.27.8.1.1
157 EQUALITY objectIdentifierMatch
158 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
163 This attribute contains the number of seconds that must elapse
164 between modifications allowed to the password. If this attribute
165 is not present, zero seconds is assumed (i.e. the password may be
166 modified whenever and however often is desired).
169 ( 1.3.6.1.4.1.42.2.27.8.1.2
171 EQUALITY integerMatch
172 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
178 This attribute contains the number of seconds after which a modified
179 password will expire. If this attribute is not present, or if its
180 value is zero (0), then passwords will not expire.
183 ( 1.3.6.1.4.1.42.2.27.8.1.3
185 EQUALITY integerMatch
186 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
192 This attribute is used to specify the maximum number of used
193 passwords that will be stored in the
197 attribute is not present, or if its value is
198 zero (0), used passwords will not be stored in
200 and thus any previously-used password may be reused.
201 No history checking occurs if the password is being modified by the
203 although the password is saved in the history.
206 ( 1.3.6.1.4.1.42.2.27.8.1.4
208 EQUALITY integerMatch
209 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
215 This attribute indicates if and how password syntax will be checked
216 while a password is being modified or added. If this attribute is
217 not present, or its value is zero (0), no syntax checking will be
218 done. If its value is one (1), the server will check the syntax,
219 and if the server is unable to check the syntax,
220 whether due to a client-side hashed password or some other reason,
222 accepted. If its value is two (2), the server will check the syntax,
223 and if the server is unable to check the syntax it will return an
224 error refusing the password.
227 ( 1.3.6.1.4.1.42.2.27.8.1.5
228 NAME 'pwdCheckQuality'
229 EQUALITY integerMatch
230 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
236 When syntax checking is enabled
239 attribute), this attribute contains the minimum
240 number of characters that will be accepted in a password. If this
241 attribute is not present, minimum password length is not
242 enforced. If the server is unable to check the length of the password,
243 whether due to a client-side hashed password or some other reason,
244 the server will, depending on the
246 .BR pwdCheckQuality ,
247 either accept the password
248 without checking it (if
250 is zero (0) or one (1)) or refuse it (if
255 ( 1.3.6.1.4.1.42.2.27.8.1.6
257 EQUALITY integerMatch
258 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
264 This attribute contains the maximum number of seconds before a
265 password is due to expire that expiration warning messages will be
266 returned to a user who is authenticating to the directory.
267 If this attribute is not
268 present, or if the value is zero (0), no warnings will be sent.
271 ( 1.3.6.1.4.1.42.2.27.8.1.7
272 NAME 'pwdExpireWarning'
273 EQUALITY integerMatch
274 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
278 .B pwdGraceAuthnLimit
280 This attribute contains the number of times that an expired password
281 may be used to authenticate a user to the directory. If this
282 attribute is not present or if its value is zero (0), users with
283 expired passwords will not be allowed to authenticate to the
287 ( 1.3.6.1.4.1.42.2.27.8.1.8
288 NAME 'pwdGraceAuthnLimit'
289 EQUALITY integerMatch
290 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
296 This attribute specifies the action that should be taken
297 by the directory when a user has made a number of failed attempts
298 to authenticate to the directory. If
300 is set (its value is "TRUE"), the user will not be allowed to
301 attempt to authenticate to the directory after there have been a
302 specified number of consecutive failed bind attempts. The maximum
303 number of consecutive failed bind attempts allowed is specified by
308 is not present, or if its value is "FALSE", the password may be
309 used to authenticate no matter how many consecutive failed bind
310 attempts have been made.
313 ( 1.3.6.1.4.1.42.2.27.8.1.9
315 EQUALITY booleanMatch
316 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
320 .B pwdLockoutDuration
322 This attribute contains the number of seconds during
323 which the password cannot be used to authenticate the
324 user to the directory due to too many consecutive failed
331 .B pwdLockoutDuration
332 is not present, or if its value is zero (0), the password
333 cannot be used to authenticate the user to the directory
334 again until it is reset by an administrator.
337 ( 1.3.6.1.4.1.42.2.27.8.1.10
338 NAME 'pwdLockoutDuration'
339 EQUALITY integerMatch
340 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
346 This attribute contains the number of consecutive failed bind
347 attempts after which the password may not be used to authenticate
348 a user to the directory.
351 is not present, or its value is zero (0), then a user will
352 be allowed to continue to attempt to authenticate to
353 the directory, no matter how many consecutive failed
354 bind attempts have occurred with that user's DN.
358 .BR pwdLockoutDuration .)
361 ( 1.3.6.1.4.1.42.2.27.8.1.11
363 EQUALITY integerMatch
364 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
368 .B pwdMaxRecordedFailure
370 This attribute contains the maximum number of failed bind
371 attempts to store in a user's entry.
373 .B pwdMaxRecordedFailure
374 is not present, or its value is zero (0), then it defaults
377 If that value is also 0, the default is 5.
380 ( 1.3.6.1.4.1.42.2.27.8.1.16
381 NAME 'pwdMaxRecordedFailure'
382 EQUALITY integerMatch
383 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
387 .B pwdFailureCountInterval
389 This attribute contains the number of seconds after which old
390 consecutive failed bind attempts are purged from the failure counter,
391 even though no successful authentication has occurred.
393 .B pwdFailureCountInterval
394 is not present, or its value is zero (0), the failure
395 counter will only be reset by a successful authentication.
398 ( 1.3.6.1.4.1.42.2.27.8.1.12
399 NAME 'pwdFailureCountInterval'
400 EQUALITY integerMatch
401 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
407 This attribute specifies whether users must change their passwords
408 when they first bind to the directory after a password is set or
409 reset by the administrator, or not. If
411 has a value of "TRUE", users must change their passwords when they
412 first bind to the directory after a password is set or reset by
413 the administrator. If
415 is not present, or its value is "FALSE",
416 users are not required to change their password upon binding after
417 the administrator sets or resets the password.
420 ( 1.3.6.1.4.1.42.2.27.8.1.13
422 EQUALITY booleanMatch
423 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
427 .B pwdAllowUserChange
429 This attribute specifies whether users are allowed to change their own
431 .B pwdAllowUserChange
432 is set to "TRUE", or if the attribute is not present, users will be
433 allowed to change their own passwords. If its value is "FALSE",
434 users will not be allowed to change their own passwords.
436 Note: this implies that when
437 .B pwdAllowUserChange
439 users will still be able to change the password of another user,
440 subjected to access control.
441 This restriction only applies to modifications of ones's own password.
442 It should also be noted that
443 .B pwdAllowUserChange
444 was defined in the specification to provide rough access control
445 to the password attribute in implementations that do not allow fine-grain
447 Since OpenLDAP provides fine-grain access control, the use of this attribute
448 is discouraged; ACLs should be used instead
454 ( 1.3.6.1.4.1.42.2.27.8.1.14
455 NAME 'pwdAllowUserChange'
456 EQUALITY booleanMatch
457 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
463 This attribute denotes whether the user's existing password must be sent
464 along with their new password when changing a password. If
466 is set to "TRUE", the existing password must be sent
467 along with the new password. If the attribute is not present, or
468 its value is "FALSE", the existing password need not be sent
469 along with the new password.
472 ( 1.3.6.1.4.1.42.2.27.8.1.15
474 EQUALITY booleanMatch
475 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
481 This attribute names a user-defined loadable module that must
482 instantiate the check_password() function. This function
483 will be called to further check a new password if
485 is set to one (1) or two (2),
486 after all of the built-in password compliance checks have
487 been passed. This function will be called according to this
492 (char *pPasswd, char **ppErrStr, Entry *pEntry);
496 parameter contains the clear-text user password, the
498 parameter contains a double pointer that allows the function
499 to return human-readable details about any error it encounters.
502 parameter, if non-NULL, carries a pointer to the
503 entry whose password is being checked.
508 must NOT attempt to use it/them.
509 A return value of LDAP_SUCCESS from the called
510 function indicates that the password is ok, any other value
511 indicates that the password is unacceptable. If the password is
512 unacceptable, the server will return an error to the client, and
514 may be used to return a human-readable textual explanation of the
515 error. The error string must be dynamically allocated as it will
516 be free()'d by slapd.
519 ( 1.3.6.1.4.1.4754.1.99.1
520 NAME 'pwdCheckModule'
521 EQUALITY caseExactIA5Match
522 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
527 The user-defined loadable module named by
531 standard executable search PATH.
535 is a non-standard extension to the LDAP password
538 .SH OPERATIONAL ATTRIBUTES
540 The operational attributes used by the
542 module are stored in the user's entry. Most of these attributes
543 are not intended to be changed directly by users; they are there
544 to track user activity. They have been detailed here so that
545 administrators and users can both understand the workings of
551 Note that the current IETF Password Policy proposal does not define
552 how these operational attributes are expected to behave in a
553 replication environment. In general, authentication attempts on
554 a slave server only affect the copy of the operational attributes
555 on that slave and will not affect any attributes for
556 a user's entry on the master server. Operational attribute changes
557 resulting from authentication attempts on a master server
558 will usually replicate to the slaves (and also overwrite
559 any changes that originated on the slave).
560 These behaviors are not guaranteed and are subject to change
561 when a formal specification emerges.
567 attribute is not strictly part of the
569 module. It is, however, the attribute that is tracked and controlled
570 by the module. Please refer to the standard OpenLDAP schema for
575 This attribute refers directly to the
577 subentry that is to be used for this particular directory user.
580 exists, it must contain the DN of a valid
582 object. If it does not exist, the
584 module will enforce the default password policy rules on the
585 user associated with this authenticating DN. If there is no
586 default, or the referenced subentry does not exist, then no
587 policy rules will be enforced.
590 ( 1.3.6.1.4.1.42.2.27.8.1.23
591 NAME 'pwdPolicySubentry'
592 DESC 'The pwdPolicy subentry in effect for
594 EQUALITY distinguishedNameMatch
595 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
597 NO\-USER\-MODIFICATION
598 USAGE directoryOperation)
603 This attribute denotes the last time that the entry's password was
604 changed. This value is used by the password expiration policy to
605 determine whether the password is too old to be allowed to be used
606 for user authentication. If
608 does not exist, the user's password will not expire.
611 ( 1.3.6.1.4.1.42.2.27.8.1.16
612 NAME 'pwdChangedTime'
613 DESC 'The time the password was last changed'
614 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
615 EQUALITY generalizedTimeMatch
616 ORDERING generalizedTimeOrderingMatch
618 NO\-USER\-MODIFICATION
619 USAGE directoryOperation)
622 .B pwdAccountLockedTime
624 This attribute contains the time that the user's account was locked.
625 If the account has been locked, the password may no longer be used to
626 authenticate the user to the directory. If
627 .B pwdAccountLockedTime
628 is set to 000001010000Z, the user's account has been permanently locked
629 and may only be unlocked by an administrator. Note that account locking
630 only takes effect when the
632 password policy attribute is set to "TRUE".
635 ( 1.3.6.1.4.1.42.2.27.8.1.17
636 NAME 'pwdAccountLockedTime'
637 DESC 'The time an user account was locked'
638 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
639 EQUALITY generalizedTimeMatch
640 ORDERING generalizedTimeOrderingMatch
642 NO\-USER\-MODIFICATION
643 USAGE directoryOperation)
648 This attribute contains the timestamps of each of the consecutive
649 authentication failures made upon attempted authentication to this
650 DN (i.e. account). If too many timestamps accumulate here (refer to
653 password policy attribute for details),
656 password policy attribute is set to "TRUE", the
657 account may be locked.
658 (Please also refer to the
660 password policy attribute.)
661 Excess timestamps beyond those allowed by
664 .B pwdMaxRecordedFailure
665 may also be purged. If a successful authentication is made to this
666 DN (i.e. to this user account), then
668 will be cleansed of entries.
671 ( 1.3.6.1.4.1.42.2.27.8.1.19
672 NAME 'pwdFailureTime'
673 DESC 'The timestamps of the last consecutive
674 authentication failures'
675 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
676 EQUALITY generalizedTimeMatch
677 ORDERING generalizedTimeOrderingMatch
678 NO\-USER\-MODIFICATION
679 USAGE directoryOperation )
684 This attribute contains the history of previously used passwords
685 for this DN (i.e. for this user account).
686 The values of this attribute are stored in string format as follows:
692 time "#" syntaxOID "#" length "#" data
697 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
701 syntaxOID = numericoid
703 This is the string representation of the dotted-decimal OID that
704 defines the syntax used to store the password. numericoid is
705 described in section 1.4 of [RFC4512].
708 length = NumericString
710 The number of octets in the data. NumericString is described in
711 section 3.3.23 of [RFC4517].
716 Octets representing the password in the format specified by syntaxOID.
721 This format allows the server to store and transmit a history of
722 passwords that have been used. In order for equality matching
723 on the values in this attribute to function properly, the time
724 field is in GMT format.
727 ( 1.3.6.1.4.1.42.2.27.8.1.20
729 DESC 'The history of user passwords'
730 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
731 EQUALITY octetStringMatch
732 NO\-USER\-MODIFICATION
733 USAGE directoryOperation)
737 This attribute contains the list of timestamps of logins made after
738 the user password in the DN has expired. These post-expiration
739 logins are known as "\fIgrace logins\fP".
742 have been used (please refer to the
743 .B pwdGraceLoginLimit
744 password policy attribute), then the DN will no longer be allowed
745 to be used to authenticate the user to the directory until the
746 administrator changes the DN's
751 ( 1.3.6.1.4.1.42.2.27.8.1.21
752 NAME 'pwdGraceUseTime'
753 DESC 'The timestamps of the grace login once the password has expired'
754 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
755 EQUALITY generalizedTimeMatch
756 NO\-USER\-MODIFICATION
757 USAGE directoryOperation)
762 This attribute indicates whether the user's password has been reset
763 by the administrator and thus must be changed upon first use of this
764 DN for authentication to the directory. If
766 is set to "TRUE", then the password was reset and the user must change
767 it upon first authentication. If the attribute does not exist, or
768 is set to "FALSE", the user need not change their password due to
769 administrative reset.
772 ( 1.3.6.1.4.1.42.2.27.8.1.22
774 DESC 'The indication that the password has
776 EQUALITY booleanMatch
777 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
779 USAGE directoryOperation)
787 suffix dc=example,dc=com
790 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
797 .BR slapd\-config (5),
798 .BR slapo\-chain (5).
800 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
802 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
803 Sermersheim: documented in IETF document
804 "draft-behera-ldap-password-policy-09.txt".
807 The LDAP Password Policy specification is not yet an approved standard,
808 and it is still evolving. This code will continue to be in flux until the
809 specification is finalized.
813 This module was written in 2004 by Howard Chu of Symas Corporation
814 with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
816 This manual page borrows heavily and shamelessly from the specification
817 upon which the password policy module it describes is based. This
819 IETF LDAP password policy proposal by P. Behera, L.
820 Poitou and J. Sermersheim.
821 The proposal is fully documented in
823 IETF document named draft-behera-ldap-password-policy-09.txt,
824 written in July of 2005.