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,
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. 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
37 These slapd.conf configuration options apply to the ppolicy overlay.
38 They should appear after the overlay directive.
39 ppolicy_default <policyDN>
41 Specify the DN of the pwdPolicy object to use when no specific
42 policy is set on a given user's entry. If there is no specific
43 policy for an entry and no default is given, then no policies
44 will be enforced.
45 ppolicy_forward_updates
47 Specify that policy state changes that result from Bind opera‐
48 tions (such as recording failures, lockout, etc.) on a consumer
49 should be forwarded to a master instead of being written
50 directly into the consumer's local database. This setting is
51 only useful on a replication consumer, and also requires the
52 updateref setting and chain overlay to be appropriately config‐
53 ured.
54 ppolicy_hash_cleartext
56 Specify that cleartext passwords present in Add and Modify
57 requests should be hashed before being stored in the database.
58 This violates the X.500/LDAP information model, but may be
59 needed to compensate for LDAP clients that don't use the Pass‐
60 word Modify extended operation to manage passwords. It is rec‐
61 ommended that when this option is used that compare, search, and
62 read access be denied to all directory users.
63 ppolicy_use_lockout
65 A client will always receive an LDAP InvalidCredentials response
66 when Binding to a locked account. By default, when a Password
67 Policy control was provided on the Bind request, a Password Pol‐
68 icy response will be included with no special error code set.
69 This option changes the Password Policy response to include the
70 AccountLocked error code. Note that sending the AccountLocked
71 error code provides useful information to an attacker; sites
72 that are sensitive to security issues should not enable this
73 option.
74
77 The ppolicy overlay depends on the pwdPolicy object class. The defini‐
78 tion of that class is as follows:
79 ( 1.3.6.1.4.1.42.2.27.8.2.1
81 NAME 'pwdPolicy'
82 AUXILIARY
83 SUP top
84 MUST ( pwdAttribute )
85 MAY (
86 pwdMinAge $ pwdMaxAge $ pwdInHistory $
87 pwdCheckQuality $ pwdMinLength $
88 pwdExpireWarning $ pwdGraceAuthnLimit $
89 pwdLockout $ pwdLockoutDuration $
90 pwdMaxFailure $ pwdFailureCountInterval $
91 pwdMustChange $ pwdAllowUserChange $
92 pwdSafeModify $ pwdMaxRecordedFailure ) )
93 This implementation also provides an additional pwdPolicyChecker
95 objectclass, used for password quality checking (see below).
96 ( 1.3.6.1.4.1.4754.2.99.1
98 NAME 'pwdPolicyChecker'
99 AUXILIARY
100 SUP top
101 MAY ( pwdCheckModule ) )
102 Every account that should be subject to password policy control should
104 have a pwdPolicySubentry attribute containing the DN of a valid pwdPol‐
105 icy entry, or they can simply use the configured default. In this way
106 different users may be managed according to different policies.
107
110 Each one of the sections below details the meaning and use of a partic‐
111 ular attribute of this pwdPolicy object class.
112 pwdAttribute
114 This attribute contains the name of the attribute to which the password
116 policy is applied. For example, the password policy may be applied to
117 the userPassword attribute.
118 Note: in this implementation, the only value accepted for pwdAttribute
120 is userPassword .
121 ( 1.3.6.1.4.1.42.2.27.8.1.1
123 NAME 'pwdAttribute'
124 EQUALITY objectIdentifierMatch
125 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
126 pwdMinAge
128 This attribute contains the number of seconds that must elapse between
130 modifications allowed to the password. If this attribute is not
131 present, zero seconds is assumed (i.e. the password may be modified
132 whenever and however often is desired).
133 ( 1.3.6.1.4.1.42.2.27.8.1.2
135 NAME 'pwdMinAge'
136 EQUALITY integerMatch
137 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
138 SINGLE-VALUE )
139 pwdMaxAge
141 This attribute contains the number of seconds after which a modified
143 password will expire. If this attribute is not present, or if its
144 value is zero (0), then passwords will not expire.
145 ( 1.3.6.1.4.1.42.2.27.8.1.3
147 NAME 'pwdMaxAge'
148 EQUALITY integerMatch
149 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
150 SINGLE-VALUE )
151 pwdInHistory
153 This attribute is used to specify the maximum number of used passwords
155 that will be stored in the pwdHistory attribute. If the pwdInHistory
156 attribute is not present, or if its value is zero (0), used passwords
157 will not be stored in pwdHistory and thus any previously-used password
158 may be reused. No history checking occurs if the password is being
159 modified by the rootdn, although the password is saved in the history.
160 ( 1.3.6.1.4.1.42.2.27.8.1.4
162 NAME 'pwdInHistory'
163 EQUALITY integerMatch
164 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
165 SINGLE-VALUE )
166 pwdCheckQuality
168 This attribute indicates if and how password syntax will be checked
170 while a password is being modified or added. If this attribute is not
171 present, or its value is zero (0), no syntax checking will be done. If
172 its value is one (1), the server will check the syntax, and if the
173 server is unable to check the syntax, whether due to a client-side
174 hashed password or some other reason, it will be accepted. If its value
175 is two (2), the server will check the syntax, and if the server is
176 unable to check the syntax it will return an error refusing the pass‐
177 word.
178 ( 1.3.6.1.4.1.42.2.27.8.1.5
180 NAME 'pwdCheckQuality'
181 EQUALITY integerMatch
182 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
183 SINGLE-VALUE )
184 pwdMinLength
186 When syntax checking is enabled (see also the pwdCheckQuality
188 attribute), this attribute contains the minimum number of characters
189 that will be accepted in a password. If this attribute is not present,
190 minimum password length is not enforced. If the server is unable to
191 check the length of the password, whether due to a client-side hashed
192 password or some other reason, the server will, depending on the value
193 of pwdCheckQuality, either accept the password without checking it (if
194 pwdCheckQuality is zero (0) or one (1)) or refuse it (if pwdCheckQual‐
195 ity is two (2)).
196 ( 1.3.6.1.4.1.42.2.27.8.1.6
198 NAME 'pwdMinLength'
199 EQUALITY integerMatch
200 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
201 SINGLE-VALUE )
202 pwdExpireWarning
204 This attribute contains the maximum number of seconds before a password
206 is due to expire that expiration warning messages will be returned to a
207 user who is authenticating to the directory. If this attribute is not
208 present, or if the value is zero (0), no warnings will be sent.
209 ( 1.3.6.1.4.1.42.2.27.8.1.7
211 NAME 'pwdExpireWarning'
212 EQUALITY integerMatch
213 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
214 SINGLE-VALUE )
215 pwdGraceAuthnLimit
217 This attribute contains the number of times that an expired password
219 may be used to authenticate a user to the directory. If this attribute
220 is not present or if its value is zero (0), users with expired pass‐
221 words will not be allowed to authenticate to the directory.
222 ( 1.3.6.1.4.1.42.2.27.8.1.8
224 NAME 'pwdGraceAuthnLimit'
225 EQUALITY integerMatch
226 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
227 SINGLE-VALUE )
228 pwdLockout
230 This attribute specifies the action that should be taken by the direc‐
232 tory when a user has made a number of failed attempts to authenticate
233 to the directory. If pwdLockout is set (its value is "TRUE"), the user
234 will not be allowed to attempt to authenticate to the directory after
235 there have been a specified number of consecutive failed bind attempts.
236 The maximum number of consecutive failed bind attempts allowed is spec‐
237 ified by the pwdMaxFailure attribute. If pwdLockout is not present, or
238 if its value is "FALSE", the password may be used to authenticate no
239 matter how many consecutive failed bind attempts have been made.
240 ( 1.3.6.1.4.1.42.2.27.8.1.9
242 NAME 'pwdLockout'
243 EQUALITY booleanMatch
244 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
245 SINGLE-VALUE )
246 pwdLockoutDuration
248 This attribute contains the number of seconds during which the password
250 cannot be used to authenticate the user to the directory due to too
251 many consecutive failed bind attempts. (See also pwdLockout and pwd‐
252 MaxFailure.) If pwdLockoutDuration is not present, or if its value is
253 zero (0), the password cannot be used to authenticate the user to the
254 directory again until it is reset by an administrator.
255 ( 1.3.6.1.4.1.42.2.27.8.1.10
257 NAME 'pwdLockoutDuration'
258 EQUALITY integerMatch
259 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
260 SINGLE-VALUE )
261 pwdMaxFailure
263 This attribute contains the number of consecutive failed bind attempts
265 after which the password may not be used to authenticate a user to the
266 directory. If pwdMaxFailure is not present, or its value is zero (0),
267 then a user will be allowed to continue to attempt to authenticate to
268 the directory, no matter how many consecutive failed bind attempts have
269 occurred with that user's DN. (See also pwdLockout and pwdLockoutDura‐
270 tion.)
271 ( 1.3.6.1.4.1.42.2.27.8.1.11
273 NAME 'pwdMaxFailure'
274 EQUALITY integerMatch
275 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
276 SINGLE-VALUE )
277 pwdMaxRecordedFailure
279 This attribute contains the maximum number of failed bind attempts to
281 store in a user's entry. If pwdMaxRecordedFailure is not present, or
282 its value is zero (0), then it defaults to the value of pwdMaxFailure.
283 If that value is also 0, the default is 5.
284 ( 1.3.6.1.4.1.42.2.27.8.1.16
286 NAME 'pwdMaxRecordedFailure'
287 EQUALITY integerMatch
288 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
289 SINGLE-VALUE )
290 pwdFailureCountInterval
292 This attribute contains the number of seconds after which old consecu‐
294 tive failed bind attempts are purged from the failure counter, even
295 though no successful authentication has occurred. If pwdFailure‐
296 CountInterval is not present, or its value is zero (0), the failure
297 counter will only be reset by a successful authentication.
298 ( 1.3.6.1.4.1.42.2.27.8.1.12
300 NAME 'pwdFailureCountInterval'
301 EQUALITY integerMatch
302 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
303 SINGLE-VALUE )
304 pwdMustChange
306 This attribute specifies whether users must change their passwords when
308 they first bind to the directory after a password is set or reset by
309 the administrator, or not. If pwdMustChange has a value of "TRUE",
310 users must change their passwords when they first bind to the directory
311 after a password is set or reset by the administrator. If pwd‐
312 MustChange is not present, or its value is "FALSE", users are not
313 required to change their password upon binding after the administrator
314 sets or resets the password.
315 ( 1.3.6.1.4.1.42.2.27.8.1.13
317 NAME 'pwdMustChange'
318 EQUALITY booleanMatch
319 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
320 SINGLE-VALUE )
321 pwdAllowUserChange
323 This attribute specifies whether users are allowed to change their own
325 passwords or not. If pwdAllowUserChange is set to "TRUE", or if the
326 attribute is not present, users will be allowed to change their own
327 passwords. If its value is "FALSE", users will not be allowed to
328 change their own passwords.
329 Note: this implies that when pwdAllowUserChange is set to "TRUE", users
331 will still be able to change the password of another user, subjected to
332 access control. This restriction only applies to modifications of
333 ones's own password. It should also be noted that pwdAllowUserChange
334 was defined in the specification to provide rough access control to the
335 password attribute in implementations that do not allow fine-grain
336 access control. Since OpenLDAP provides fine-grain access control, the
337 use of this attribute is discouraged; ACLs should be used instead (see
338 slapd.access(5) for details).
339 ( 1.3.6.1.4.1.42.2.27.8.1.14
341 NAME 'pwdAllowUserChange'
342 EQUALITY booleanMatch
343 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
344 SINGLE-VALUE )
345 pwdSafeModify
347 This attribute denotes whether the user's existing password must be
349 sent along with their new password when changing a password. If pwd‐
350 SafeModify is set to "TRUE", the existing password must be sent along
351 with the new password. If the attribute is not present, or its value
352 is "FALSE", the existing password need not be sent along with the new
353 password.
354 ( 1.3.6.1.4.1.42.2.27.8.1.15
356 NAME 'pwdSafeModify'
357 EQUALITY booleanMatch
358 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
359 SINGLE-VALUE )
360 pwdCheckModule
362 This attribute names a user-defined loadable module that must instanti‐
364 ate the check_password() function. This function will be called to
365 further check a new password if pwdCheckQuality is set to one (1) or
366 two (2), after all of the built-in password compliance checks have been
367 passed. This function will be called according to this function proto‐
368 type:
369 int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
370 The pPasswd parameter contains the clear-text user password, the
371 ppErrStr parameter contains a double pointer that allows the function
372 to return human-readable details about any error it encounters. The
373 optional pEntry parameter, if non-NULL, carries a pointer to the entry
374 whose password is being checked. If ppErrStr is NULL, then funcName
375 must NOT attempt to use it/them. A return value of LDAP_SUCCESS from
376 the called function indicates that the password is ok, any other value
377 indicates that the password is unacceptable. If the password is unac‐
378 ceptable, the server will return an error to the client, and ppErrStr
379 may be used to return a human-readable textual explanation of the
380 error. The error string must be dynamically allocated as it will be
381 free()'d by slapd.
382 ( 1.3.6.1.4.1.4754.1.99.1
384 NAME 'pwdCheckModule'
385 EQUALITY caseExactIA5Match
386 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
387 SINGLE-VALUE )
388 Note: The user-defined loadable module named by pwdCheckModule must be
390 in slapd's standard executable search PATH.
391 Note: pwdCheckModule is a non-standard extension to the LDAP password
393 policy proposal.
394
397 The operational attributes used by the ppolicy module are stored in the
398 user's entry. Most of these attributes are not intended to be changed
399 directly by users; they are there to track user activity. They have
400 been detailed here so that administrators and users can both understand
401 the workings of the ppolicy module.
402 Note that the current IETF Password Policy proposal does not define how
405 these operational attributes are expected to behave in a replication
406 environment. In general, authentication attempts on a slave server only
407 affect the copy of the operational attributes on that slave and will
408 not affect any attributes for a user's entry on the master server.
409 Operational attribute changes resulting from authentication attempts on
410 a master server will usually replicate to the slaves (and also over‐
411 write any changes that originated on the slave). These behaviors are
412 not guaranteed and are subject to change when a formal specification
413 emerges.
414 userPassword
416 The userPassword attribute is not strictly part of the ppolicy module.
418 It is, however, the attribute that is tracked and controlled by the
419 module. Please refer to the standard OpenLDAP schema for its defini‐
420 tion.
421 pwdPolicySubentry
423 This attribute refers directly to the pwdPolicy subentry that is to be
425 used for this particular directory user. If pwdPolicySubentry exists,
426 it must contain the DN of a valid pwdPolicy object. If it does not
427 exist, the ppolicy module will enforce the default password policy
428 rules on the user associated with this authenticating DN. If there is
429 no default, or the referenced subentry does not exist, then no policy
430 rules will be enforced.
431 ( 1.3.6.1.4.1.42.2.27.8.1.23
433 NAME 'pwdPolicySubentry'
434 DESC 'The pwdPolicy subentry in effect for
435 this object'
436 EQUALITY distinguishedNameMatch
437 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
438 SINGLE-VALUE
439 NO-USER-MODIFICATION
440 USAGE directoryOperation)
441 pwdChangedTime
443 This attribute denotes the last time that the entry's password was
445 changed. This value is used by the password expiration policy to
446 determine whether the password is too old to be allowed to be used for
447 user authentication. If pwdChangedTime does not exist, the user's
448 password will not expire.
449 ( 1.3.6.1.4.1.42.2.27.8.1.16
451 NAME 'pwdChangedTime'
452 DESC 'The time the password was last changed'
453 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
454 EQUALITY generalizedTimeMatch
455 ORDERING generalizedTimeOrderingMatch
456 SINGLE-VALUE
457 NO-USER-MODIFICATION
458 USAGE directoryOperation)
459 pwdAccountLockedTime
461 This attribute contains the time that the user's account was locked.
463 If the account has been locked, the password may no longer be used to
464 authenticate the user to the directory. If pwdAccountLockedTime is set
465 to 000001010000Z, the user's account has been permanently locked and
466 may only be unlocked by an administrator. Note that account locking
467 only takes effect when the pwdLockout password policy attribute is set
468 to "TRUE".
469 ( 1.3.6.1.4.1.42.2.27.8.1.17
471 NAME 'pwdAccountLockedTime'
472 DESC 'The time an user account was locked'
473 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
474 EQUALITY generalizedTimeMatch
475 ORDERING generalizedTimeOrderingMatch
476 SINGLE-VALUE
477 NO-USER-MODIFICATION
478 USAGE directoryOperation)
479 pwdFailureTime
481 This attribute contains the timestamps of each of the consecutive
483 authentication failures made upon attempted authentication to this DN
484 (i.e. account). If too many timestamps accumulate here (refer to the
485 pwdMaxFailure password policy attribute for details), and the pwdLock‐
486 out password policy attribute is set to "TRUE", the account may be
487 locked. (Please also refer to the pwdLockout password policy
488 attribute.) Excess timestamps beyond those allowed by pwdMaxFailure or
489 pwdMaxRecordedFailure may also be purged. If a successful authentica‐
490 tion is made to this DN (i.e. to this user account), then pwdFailure‐
491 Time will be cleansed of entries.
492 ( 1.3.6.1.4.1.42.2.27.8.1.19
494 NAME 'pwdFailureTime'
495 DESC 'The timestamps of the last consecutive
496 authentication failures'
497 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
498 EQUALITY generalizedTimeMatch
499 ORDERING generalizedTimeOrderingMatch
500 NO-USER-MODIFICATION
501 USAGE directoryOperation )
502 pwdHistory
504 This attribute contains the history of previously used passwords for
506 this DN (i.e. for this user account). The values of this attribute are
507 stored in string format as follows:
508 pwdHistory=
511 time "#" syntaxOID "#" length "#" data
512 time=
514 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
515 syntaxOID = numericoid
518 This is the string representation of the dotted-decimal OID
519 that defines the syntax used to store the password. numericoid
520 is described in section 1.4 of [RFC4512].
521 length = NumericString
523 The number of octets in the data. NumericString is described
524 in section 3.3.23 of [RFC4517].
525 data =
527 Octets representing the password in the format specified by
528 syntaxOID.
529 This format allows the server to store and transmit a history of pass‐
532 words that have been used. In order for equality matching on the val‐
533 ues in this attribute to function properly, the time field is in GMT
534 format.
535 ( 1.3.6.1.4.1.42.2.27.8.1.20
537 NAME 'pwdHistory'
538 DESC 'The history of user passwords'
539 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
540 EQUALITY octetStringMatch
541 NO-USER-MODIFICATION
542 USAGE directoryOperation)
543 pwdGraceUseTime This attribute contains the list of timestamps of
545 logins made after the user password in the DN has expired. These post-
546 expiration logins are known as "grace logins". If too many grace
547 logins have been used (please refer to the pwdGraceLoginLimit password
548 policy attribute), then the DN will no longer be allowed to be used to
549 authenticate the user to the directory until the administrator changes
550 the DN's userPassword attribute.
551 ( 1.3.6.1.4.1.42.2.27.8.1.21
553 NAME 'pwdGraceUseTime'
554 DESC 'The timestamps of the grace login once the password has
555 expired'
556 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
557 EQUALITY generalizedTimeMatch
558 NO-USER-MODIFICATION
559 USAGE directoryOperation)
560 pwdReset
562 This attribute indicates whether the user's password has been reset by
564 the administrator and thus must be changed upon first use of this DN
565 for authentication to the directory. If pwdReset is set to "TRUE",
566 then the password was reset and the user must change it upon first
567 authentication. If the attribute does not exist, or is set to "FALSE",
568 the user need not change their password due to administrative reset.
569 ( 1.3.6.1.4.1.42.2.27.8.1.22
571 NAME 'pwdReset'
572 DESC 'The indication that the password has
573 been reset'
574 EQUALITY booleanMatch
575 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
576 SINGLE-VALUE
577 USAGE directoryOperation)
578
581 database bdb
582 suffix dc=example,dc=com
583 ...
584 overlay ppolicy
585 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
586
589 ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).
590 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
592 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
594 Sermersheim: documented in IETF document "draft-behera-ldap-password-
595 policy-09.txt".
596
599 The LDAP Password Policy specification is not yet an approved standard,
600 and it is still evolving. This code will continue to be in flux until
601 the specification is finalized.
602
605 This module was written in 2004 by Howard Chu of Symas Corporation with
606 significant input from Neil Dunbar and Kartik Subbarao of Hewlett-
607 Packard.
608 This manual page borrows heavily and shamelessly from the specification
610 upon which the password policy module it describes is based. This
611 source is the IETF LDAP password policy proposal by P. Behera, L.
612 Poitou and J. Sermersheim. The proposal is fully documented in the
613 IETF document named draft-behera-ldap-password-policy-09.txt, written
614 in July of 2005.
615 OpenLDAP Software is developed and maintained by The OpenLDAP Project
617 <http://www.openldap.org/>. OpenLDAP Software is derived from the Uni‐
618 versity of Michigan LDAP 3.3 Release.
619OpenLDAP 2.4.47 2018/12/19 SLAPO_PPOLICY(5)