1SLAPO_PPOLICY(5) File Formats Manual SLAPO_PPOLICY(5)
2
6 slapo-ppolicy - Password Policy overlay to slapd
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, de‐
14 codes and applies specific password policy controls to overall use of a
15 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. This overlay requires a rootdn to be configured on the data‐
28 base.
29 Note that the IETF Password Policy proposal for LDAP makes sense when
31 considering a single-valued password attribute, while the userPassword
32 attribute allows multiple values. This implementation enforces a sin‐
33 gle value for the userPassword attribute, despite its specification.
34 In addition to supporting the IETF Password Policy, this module can
36 send the Netscape Password validity controls when configured to do so.
37
40 These slapd.conf configuration options apply to the ppolicy overlay.
41 They should appear after the overlay directive.
42 ppolicy_default <policyDN>
44 Specify the DN of the pwdPolicy object to use when no specific
45 policy is set on a given user's entry. If there is no specific
46 policy for an entry and no default is given, then no policies
47 will be enforced.
48 ppolicy_forward_updates
50 Specify that policy state changes that result from Bind opera‐
51 tions (such as recording failures, lockout, etc.) on a consumer
52 should be forwarded to a provider instead of being written di‐
53 rectly into the consumer's local database. This setting is only
54 useful on a replication consumer, and also requires the up‐
55 dateref setting and chain overlay to be appropriately config‐
56 ured.
57 ppolicy_hash_cleartext
59 Specify that cleartext passwords present in Add and Modify re‐
60 quests should be hashed before being stored in the database.
61 This violates the X.500/LDAP information model, but may be
62 needed to compensate for LDAP clients that don't use the Pass‐
63 word Modify extended operation to manage passwords. It is rec‐
64 ommended that when this option is used that compare, search, and
65 read access be denied to all directory users.
66 ppolicy_use_lockout
68 A client will always receive an LDAP InvalidCredentials response
69 when Binding to a locked account. By default, when a Password
70 Policy control was provided on the Bind request, a Password Pol‐
71 icy response will be included with no special error code set.
72 This option changes the Password Policy response to include the
73 AccountLocked error code. Note that sending the AccountLocked
74 error code provides useful information to an attacker; sites
75 that are sensitive to security issues should not enable this op‐
76 tion.
77 ppolicy_send_netscape_controls
79 If set, ppolicy will send the password policy expired
80 (2.16.840.1.113730.3.4.4) and password policy expiring
81 (2.16.840.1.113730.3.4.5) controls when appropriate. The con‐
82 trols are not sent for bind requests where the Password policy
83 control has already been requested. Default is not to send the
84 controls.
85
88 The ppolicy overlay depends on the pwdPolicy object class. The defini‐
89 tion of that class is as follows:
90 ( 1.3.6.1.4.1.42.2.27.8.2.1
92 NAME 'pwdPolicy'
93 AUXILIARY
94 SUP top
95 MUST ( pwdAttribute )
96 MAY (
97 pwdMinAge $ pwdMaxAge $ pwdInHistory $
98 pwdCheckQuality $ pwdMinLength $
99 pwdExpireWarning $ pwdGraceAuthnLimit $
100 pwdLockout $ pwdLockoutDuration $
101 pwdMaxFailure $ pwdFailureCountInterval $
102 pwdMustChange $ pwdAllowUserChange $
103 pwdSafeModify $ pwdMaxRecordedFailure ) )
104 This implementation also provides an additional pwdPolicyChecker ob‐
106 jectclass, used for password quality checking (see below).
107 ( 1.3.6.1.4.1.4754.2.99.1
109 NAME 'pwdPolicyChecker'
110 AUXILIARY
111 SUP top
112 MAY ( pwdCheckModule ) )
113 Every account that should be subject to password policy control should
115 have a pwdPolicySubentry attribute containing the DN of a valid pwdPol‐
116 icy entry, or they can simply use the configured default. In this way
117 different users may be managed according to different policies.
118
121 Each one of the sections below details the meaning and use of a partic‐
122 ular attribute of this pwdPolicy object class.
123 pwdAttribute
125 This attribute contains the name of the attribute to which the password
127 policy is applied. For example, the password policy may be applied to
128 the userPassword attribute.
129 Note: in this implementation, the only value accepted for pwdAttribute
131 is userPassword .
132 ( 1.3.6.1.4.1.42.2.27.8.1.1
134 NAME 'pwdAttribute'
135 EQUALITY objectIdentifierMatch
136 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
137 pwdMinAge
139 This attribute contains the number of seconds that must elapse between
141 modifications allowed to the password. If this attribute is not
142 present, zero seconds is assumed (i.e. the password may be modified
143 whenever and however often is desired).
144 ( 1.3.6.1.4.1.42.2.27.8.1.2
146 NAME 'pwdMinAge'
147 EQUALITY integerMatch
148 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
149 SINGLE-VALUE )
150 pwdMaxAge
152 This attribute contains the number of seconds after which a modified
154 password will expire. If this attribute is not present, or if its
155 value is zero (0), then passwords will not expire.
156 ( 1.3.6.1.4.1.42.2.27.8.1.3
158 NAME 'pwdMaxAge'
159 EQUALITY integerMatch
160 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
161 SINGLE-VALUE )
162 pwdInHistory
164 This attribute is used to specify the maximum number of used passwords
166 that will be stored in the pwdHistory attribute. If the pwdInHistory
167 attribute is not present, or if its value is zero (0), used passwords
168 will not be stored in pwdHistory and thus any previously-used password
169 may be reused. No history checking occurs if the password is being
170 modified by the rootdn, although the password is saved in the history.
171 ( 1.3.6.1.4.1.42.2.27.8.1.4
173 NAME 'pwdInHistory'
174 EQUALITY integerMatch
175 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
176 SINGLE-VALUE )
177 pwdCheckQuality
179 This attribute indicates if and how password syntax will be checked
181 while a password is being modified or added. If this attribute is not
182 present, or its value is zero (0), no syntax checking will be done. If
183 its value is one (1), the server will check the syntax, and if the
184 server is unable to check the syntax, whether due to a client-side
185 hashed password or some other reason, it will be accepted. If its value
186 is two (2), the server will check the syntax, and if the server is un‐
187 able to check the syntax it will return an error refusing the password.
188 ( 1.3.6.1.4.1.42.2.27.8.1.5
190 NAME 'pwdCheckQuality'
191 EQUALITY integerMatch
192 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
193 SINGLE-VALUE )
194 pwdMinLength
196 When syntax checking is enabled (see also the pwdCheckQuality attri‐
198 bute), this attribute contains the minimum number of characters that
199 will be accepted in a password. If this attribute is not present, mini‐
200 mum password length is not enforced. If the server is unable to check
201 the length of the password, whether due to a client-side hashed pass‐
202 word or some other reason, the server will, depending on the value of
203 pwdCheckQuality, either accept the password without checking it (if
204 pwdCheckQuality is zero (0) or one (1)) or refuse it (if pwdCheckQual‐
205 ity is two (2)).
206 ( 1.3.6.1.4.1.42.2.27.8.1.6
208 NAME 'pwdMinLength'
209 EQUALITY integerMatch
210 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
211 SINGLE-VALUE )
212 pwdExpireWarning
214 This attribute contains the maximum number of seconds before a password
216 is due to expire that expiration warning messages will be returned to a
217 user who is authenticating to the directory. If this attribute is not
218 present, or if the value is zero (0), no warnings will be sent.
219 ( 1.3.6.1.4.1.42.2.27.8.1.7
221 NAME 'pwdExpireWarning'
222 EQUALITY integerMatch
223 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
224 SINGLE-VALUE )
225 pwdGraceAuthnLimit
227 This attribute contains the number of times that an expired password
229 may be used to authenticate a user to the directory. If this attribute
230 is not present or if its value is zero (0), users with expired pass‐
231 words will not be allowed to authenticate to the directory.
232 ( 1.3.6.1.4.1.42.2.27.8.1.8
234 NAME 'pwdGraceAuthnLimit'
235 EQUALITY integerMatch
236 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
237 SINGLE-VALUE )
238 pwdLockout
240 This attribute specifies the action that should be taken by the direc‐
242 tory when a user has made a number of failed attempts to authenticate
243 to the directory. If pwdLockout is set (its value is "TRUE"), the user
244 will not be allowed to attempt to authenticate to the directory after
245 there have been a specified number of consecutive failed bind attempts.
246 The maximum number of consecutive failed bind attempts allowed is spec‐
247 ified by the pwdMaxFailure attribute. If pwdLockout is not present, or
248 if its value is "FALSE", the password may be used to authenticate no
249 matter how many consecutive failed bind attempts have been made.
250 ( 1.3.6.1.4.1.42.2.27.8.1.9
252 NAME 'pwdLockout'
253 EQUALITY booleanMatch
254 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
255 SINGLE-VALUE )
256 pwdLockoutDuration
258 This attribute contains the number of seconds during which the password
260 cannot be used to authenticate the user to the directory due to too
261 many consecutive failed bind attempts. (See also pwdLockout and pwd‐
262 MaxFailure.) If pwdLockoutDuration is not present, or if its value is
263 zero (0), the password cannot be used to authenticate the user to the
264 directory again until it is reset by an administrator.
265 ( 1.3.6.1.4.1.42.2.27.8.1.10
267 NAME 'pwdLockoutDuration'
268 EQUALITY integerMatch
269 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
270 SINGLE-VALUE )
271 pwdMaxFailure
273 This attribute contains the number of consecutive failed bind attempts
275 after which the password may not be used to authenticate a user to the
276 directory. If pwdMaxFailure is not present, or its value is zero (0),
277 then a user will be allowed to continue to attempt to authenticate to
278 the directory, no matter how many consecutive failed bind attempts have
279 occurred with that user's DN. (See also pwdLockout and pwdLockoutDura‐
280 tion.)
281 ( 1.3.6.1.4.1.42.2.27.8.1.11
283 NAME 'pwdMaxFailure'
284 EQUALITY integerMatch
285 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
286 SINGLE-VALUE )
287 pwdMaxRecordedFailure
289 This attribute contains the maximum number of failed bind attempts to
291 store in a user's entry. If pwdMaxRecordedFailure is not present, or
292 its value is zero (0), then it defaults to the value of pwdMaxFailure.
293 If that value is also 0, the default is 5.
294 ( 1.3.6.1.4.1.42.2.27.8.1.16
296 NAME 'pwdMaxRecordedFailure'
297 EQUALITY integerMatch
298 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
299 SINGLE-VALUE )
300 pwdFailureCountInterval
302 This attribute contains the number of seconds after which old consecu‐
304 tive failed bind attempts are purged from the failure counter, even
305 though no successful authentication has occurred. If pwdFailure‐
306 CountInterval is not present, or its value is zero (0), the failure
307 counter will only be reset by a successful authentication.
308 ( 1.3.6.1.4.1.42.2.27.8.1.12
310 NAME 'pwdFailureCountInterval'
311 EQUALITY integerMatch
312 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
313 SINGLE-VALUE )
314 pwdMustChange
316 This attribute specifies whether users must change their passwords when
318 they first bind to the directory after a password is set or reset by
319 the administrator, or not. If pwdMustChange has a value of "TRUE",
320 users must change their passwords when they first bind to the directory
321 after a password is set or reset by the administrator. If pwd‐
322 MustChange is not present, or its value is "FALSE", users are not re‐
323 quired to change their password upon binding after the administrator
324 sets or resets the password.
325 ( 1.3.6.1.4.1.42.2.27.8.1.13
327 NAME 'pwdMustChange'
328 EQUALITY booleanMatch
329 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
330 SINGLE-VALUE )
331 pwdAllowUserChange
333 This attribute specifies whether users are allowed to change their own
335 passwords or not. If pwdAllowUserChange is set to "TRUE", or if the
336 attribute is not present, users will be allowed to change their own
337 passwords. If its value is "FALSE", users will not be allowed to
338 change their own passwords.
339 Note: this implies that when pwdAllowUserChange is set to "TRUE", users
341 will still be able to change the password of another user, subjected to
342 access control. This restriction only applies to modifications of
343 ones's own password. It should also be noted that pwdAllowUserChange
344 was defined in the specification to provide rough access control to the
345 password attribute in implementations that do not allow fine-grain ac‐
346 cess control. Since OpenLDAP provides fine-grain access control, the
347 use of this attribute is discouraged; ACLs should be used instead (see
348 slapd.access(5) for details).
349 ( 1.3.6.1.4.1.42.2.27.8.1.14
351 NAME 'pwdAllowUserChange'
352 EQUALITY booleanMatch
353 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
354 SINGLE-VALUE )
355 pwdSafeModify
357 This attribute denotes whether the user's existing password must be
359 sent along with their new password when changing a password. If pwd‐
360 SafeModify is set to "TRUE", the existing password must be sent along
361 with the new password. If the attribute is not present, or its value
362 is "FALSE", the existing password need not be sent along with the new
363 password.
364 ( 1.3.6.1.4.1.42.2.27.8.1.15
366 NAME 'pwdSafeModify'
367 EQUALITY booleanMatch
368 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
369 SINGLE-VALUE )
370 pwdCheckModule
372 This attribute names a user-defined loadable module that must instanti‐
374 ate the check_password() function. This function will be called to
375 further check a new password if pwdCheckQuality is set to one (1) or
376 two (2), after all of the built-in password compliance checks have been
377 passed. This function will be called according to this function proto‐
378 type:
379 int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
380 The pPasswd parameter contains the clear-text user password, the
381 ppErrStr parameter contains a double pointer that allows the function
382 to return human-readable details about any error it encounters. The
383 optional pEntry parameter, if non-NULL, carries a pointer to the entry
384 whose password is being checked. If ppErrStr is NULL, then funcName
385 must NOT attempt to use it/them. A return value of LDAP_SUCCESS from
386 the called function indicates that the password is ok, any other value
387 indicates that the password is unacceptable. If the password is unac‐
388 ceptable, the server will return an error to the client, and ppErrStr
389 may be used to return a human-readable textual explanation of the er‐
390 ror. The error string must be dynamically allocated as it will be
391 free()'d by slapd.
392 ( 1.3.6.1.4.1.4754.1.99.1
394 NAME 'pwdCheckModule'
395 EQUALITY caseExactIA5Match
396 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
397 SINGLE-VALUE )
398 Note: The user-defined loadable module named by pwdCheckModule must be
400 in slapd's standard executable search PATH.
401 Note: pwdCheckModule is a non-standard extension to the LDAP password
403 policy proposal.
404
407 The operational attributes used by the ppolicy module are stored in the
408 user's entry. Most of these attributes are not intended to be changed
409 directly by users; they are there to track user activity. They have
410 been detailed here so that administrators and users can both understand
411 the workings of the ppolicy module.
412 Note that the current IETF Password Policy proposal does not define how
415 these operational attributes are expected to behave in a replication
416 environment. In general, authentication attempts on a replica server
417 only affect the copy of the operational attributes on that replica and
418 will not affect any attributes for a user's entry on the provider. Op‐
419 erational attribute changes resulting from authentication attempts on a
420 provider will usually replicate to the replicas (and also overwrite any
421 changes that originated on the replica). These behaviors are not guar‐
422 anteed and are subject to change when a formal specification emerges.
423 userPassword
425 The userPassword attribute is not strictly part of the ppolicy module.
427 It is, however, the attribute that is tracked and controlled by the
428 module. Please refer to the standard OpenLDAP schema for its defini‐
429 tion.
430 pwdPolicySubentry
432 This attribute refers directly to the pwdPolicy subentry that is to be
434 used for this particular directory user. If pwdPolicySubentry exists,
435 it must contain the DN of a valid pwdPolicy object. If it does not ex‐
436 ist, the ppolicy module will enforce the default password policy rules
437 on the user associated with this authenticating DN. If there is no de‐
438 fault, or the referenced subentry does not exist, then no policy rules
439 will be enforced.
440 ( 1.3.6.1.4.1.42.2.27.8.1.23
442 NAME 'pwdPolicySubentry'
443 DESC 'The pwdPolicy subentry in effect for
444 this object'
445 EQUALITY distinguishedNameMatch
446 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
447 SINGLE-VALUE
448 NO-USER-MODIFICATION
449 USAGE directoryOperation)
450 pwdChangedTime
452 This attribute denotes the last time that the entry's password was
454 changed. This value is used by the password expiration policy to de‐
455 termine whether the password is too old to be allowed to be used for
456 user authentication. If pwdChangedTime does not exist, the user's
457 password will not expire.
458 ( 1.3.6.1.4.1.42.2.27.8.1.16
460 NAME 'pwdChangedTime'
461 DESC 'The time the password was last changed'
462 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
463 EQUALITY generalizedTimeMatch
464 ORDERING generalizedTimeOrderingMatch
465 SINGLE-VALUE
466 NO-USER-MODIFICATION
467 USAGE directoryOperation)
468 pwdAccountLockedTime
470 This attribute contains the time that the user's account was locked.
472 If the account has been locked, the password may no longer be used to
473 authenticate the user to the directory. If pwdAccountLockedTime is set
474 to 000001010000Z, the user's account has been permanently locked and
475 may only be unlocked by an administrator. Note that account locking
476 only takes effect when the pwdLockout password policy attribute is set
477 to "TRUE".
478 ( 1.3.6.1.4.1.42.2.27.8.1.17
480 NAME 'pwdAccountLockedTime'
481 DESC 'The time an user account was locked'
482 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
483 EQUALITY generalizedTimeMatch
484 ORDERING generalizedTimeOrderingMatch
485 SINGLE-VALUE
486 NO-USER-MODIFICATION
487 USAGE directoryOperation)
488 pwdFailureTime
490 This attribute contains the timestamps of each of the consecutive au‐
492 thentication failures made upon attempted authentication to this DN
493 (i.e. account). If too many timestamps accumulate here (refer to the
494 pwdMaxFailure password policy attribute for details), and the pwdLock‐
495 out password policy attribute is set to "TRUE", the account may be
496 locked. (Please also refer to the pwdLockout password policy attri‐
497 bute.) Excess timestamps beyond those allowed by pwdMaxFailure or pwd‐
498 MaxRecordedFailure may also be purged. If a successful authentication
499 is made to this DN (i.e. to this user account), then pwdFailureTime
500 will be cleansed of entries.
501 ( 1.3.6.1.4.1.42.2.27.8.1.19
503 NAME 'pwdFailureTime'
504 DESC 'The timestamps of the last consecutive
505 authentication failures'
506 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
507 EQUALITY generalizedTimeMatch
508 ORDERING generalizedTimeOrderingMatch
509 NO-USER-MODIFICATION
510 USAGE directoryOperation )
511 pwdHistory
513 This attribute contains the history of previously used passwords for
515 this DN (i.e. for this user account). The values of this attribute are
516 stored in string format as follows:
517 pwdHistory=
520 time "#" syntaxOID "#" length "#" data
521 time=
523 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
524 syntaxOID = numericoid
527 This is the string representation of the dotted-decimal OID
528 that defines the syntax used to store the password. numericoid
529 is described in section 1.4 of [RFC4512].
530 length = NumericString
532 The number of octets in the data. NumericString is described
533 in section 3.3.23 of [RFC4517].
534 data =
536 Octets representing the password in the format specified by
537 syntaxOID.
538 This format allows the server to store and transmit a history of pass‐
541 words that have been used. In order for equality matching on the val‐
542 ues in this attribute to function properly, the time field is in GMT
543 format.
544 ( 1.3.6.1.4.1.42.2.27.8.1.20
546 NAME 'pwdHistory'
547 DESC 'The history of user passwords'
548 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
549 EQUALITY octetStringMatch
550 NO-USER-MODIFICATION
551 USAGE directoryOperation)
552 pwdGraceUseTime This attribute contains the list of timestamps of lo‐
554 gins made after the user password in the DN has expired. These post-
555 expiration logins are known as "grace logins". If too many grace lo‐
556 gins have been used (please refer to the pwdGraceAuthnLimit password
557 policy attribute), then the DN will no longer be allowed to be used to
558 authenticate the user to the directory until the administrator changes
559 the DN's userPassword attribute.
560 ( 1.3.6.1.4.1.42.2.27.8.1.21
562 NAME 'pwdGraceUseTime'
563 DESC 'The timestamps of the grace login once the password has
564 expired'
565 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
566 EQUALITY generalizedTimeMatch
567 NO-USER-MODIFICATION
568 USAGE directoryOperation)
569 pwdReset
571 This attribute indicates whether the user's password has been reset by
573 the administrator and thus must be changed upon first use of this DN
574 for authentication to the directory. If pwdReset is set to "TRUE",
575 then the password was reset and the user must change it upon first au‐
576 thentication. If the attribute does not exist, or is set to "FALSE",
577 the user need not change their password due to administrative reset.
578 ( 1.3.6.1.4.1.42.2.27.8.1.22
580 NAME 'pwdReset'
581 DESC 'The indication that the password has
582 been reset'
583 EQUALITY booleanMatch
584 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
585 SINGLE-VALUE
586 USAGE directoryOperation)
587
590 database bdb
591 suffix dc=example,dc=com
592 ...
593 overlay ppolicy
594 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
595
598 ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).
599 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
601 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
603 Sermersheim: documented in IETF document "draft-behera-ldap-password-
604 policy-09.txt".
605
608 The LDAP Password Policy specification is not yet an approved standard,
609 and it is still evolving. This code will continue to be in flux until
610 the specification is finalized.
611
614 This module was written in 2004 by Howard Chu of Symas Corporation with
615 significant input from Neil Dunbar and Kartik Subbarao of Hewlett-
616 Packard.
617 This manual page borrows heavily and shamelessly from the specification
619 upon which the password policy module it describes is based. This
620 source is the IETF LDAP password policy proposal by P. Behera, L.
621 Poitou and J. Sermersheim. The proposal is fully documented in the
622 IETF document named draft-behera-ldap-password-policy-09.txt, written
623 in July of 2005.
624 OpenLDAP Software is developed and maintained by The OpenLDAP Project
626 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
627 versity of Michigan LDAP 3.3 Release.
628OpenLDAP 2.4.57 2021/01/18 SLAPO_PPOLICY(5)