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