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 ) )
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 pwdFailureCountInterval
278 This attribute contains the number of seconds after which old consecu‐
280 tive failed bind attempts are purged from the failure counter, even
281 though no successful authentication has occurred. If pwdFailure‐
282 CountInterval is not present, or its value is zero (0), the failure
283 counter will only be reset by a successful authentication.
284 ( 1.3.6.1.4.1.42.2.27.8.1.12
286 NAME 'pwdFailureCountInterval'
287 EQUALITY integerMatch
288 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
289 SINGLE-VALUE )
290 pwdMustChange
292 This attribute specifies whether users must change their passwords when
294 they first bind to the directory after a password is set or reset by
295 the administrator, or not. If pwdMustChange has a value of "TRUE",
296 users must change their passwords when they first bind to the directory
297 after a password is set or reset by the administrator. If pwd‐
298 MustChange is not present, or its value is "FALSE", users are not
299 required to change their password upon binding after the administrator
300 sets or resets the password.
301 ( 1.3.6.1.4.1.42.2.27.8.1.13
303 NAME 'pwdMustChange'
304 EQUALITY booleanMatch
305 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
306 SINGLE-VALUE )
307 pwdAllowUserChange
309 This attribute specifies whether users are allowed to change their own
311 passwords or not. If pwdAllowUserChange is set to "TRUE", or if the
312 attribute is not present, users will be allowed to change their own
313 passwords. If its value is "FALSE", users will not be allowed to
314 change their own passwords.
315 ( 1.3.6.1.4.1.42.2.27.8.1.14
317 NAME 'pwdAllowUserChange'
318 EQUALITY booleanMatch
319 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
320 SINGLE-VALUE )
321 pwdSafeModify
323 This attribute denotes whether the user's existing password must be
325 sent along with their new password when changing a password. If pwd‐
326 SafeModify is set to "TRUE", the existing password must be sent along
327 with the new password. If the attribute is not present, or its value
328 is "FALSE", the existing password need not be sent along with the new
329 password.
330 ( 1.3.6.1.4.1.42.2.27.8.1.15
332 NAME 'pwdSafeModify'
333 EQUALITY booleanMatch
334 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
335 SINGLE-VALUE )
336 pwdCheckModule
338 This attribute names a user-defined loadable module that must instanti‐
340 ate the check_password() function. This function will be called to
341 further check a new password if pwdCheckQuality is set to one (1) or
342 two (2), after all of the built-in password compliance checks have been
343 passed. This function will be called according to this function proto‐
344 type:
345 int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
346 The pPasswd parameter contains the clear-text user password, the
347 ppErrStr parameter contains a double pointer that allows the function
348 to return human-readable details about any error it encounters. The
349 optional pEntry parameter, if non-NULL, carries a pointer to the entry
350 whose password is being checked. If ppErrStr is NULL, then funcName
351 must NOT attempt to use it/them. A return value of LDAP_SUCCESS from
352 the called function indicates that the password is ok, any other value
353 indicates that the password is unacceptable. If the password is unac‐
354 ceptable, the server will return an error to the client, and ppErrStr
355 may be used to return a human-readable textual explanation of the
356 error. The error string must be dynamically allocated as it will be
357 free()'d by slapd.
358 ( 1.3.6.1.4.1.4754.1.99.1
360 NAME 'pwdCheckModule'
361 EQUALITY caseExactIA5Match
362 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
363 SINGLE-VALUE )
364 Note: The user-defined loadable module named by pwdCheckModule must be
366 in slapd's standard executable search PATH.
367 Note: pwdCheckModule is a non-standard extension to the LDAP password
369 policy proposal.
370
373 The operational attributes used by the ppolicy module are stored in the
374 user's entry. Most of these attributes are not intended to be changed
375 directly by users; they are there to track user activity. They have
376 been detailed here so that administrators and users can both understand
377 the workings of the ppolicy module.
378 Note that the current IETF Password Policy proposal does not define how
381 these operational attributes are expected to behave in a replication
382 environment. In general, authentication attempts on a slave server only
383 affect the copy of the operational attributes on that slave and will
384 not affect any attributes for a user's entry on the master server.
385 Operational attribute changes resulting from authentication attempts on
386 a master server will usually replicate to the slaves (and also over‐
387 write any changes that originated on the slave). These behaviors are
388 not guaranteed and are subject to change when a formal specification
389 emerges.
390 userPassword
392 The userPassword attribute is not strictly part of the ppolicy module.
394 It is, however, the attribute that is tracked and controlled by the
395 module. Please refer to the standard OpenLDAP schema for its defini‐
396 tion.
397 pwdPolicySubentry
399 This attribute refers directly to the pwdPolicy subentry that is to be
401 used for this particular directory user. If pwdPolicySubentry exists,
402 it must contain the DN of a valid pwdPolicy object. If it does not
403 exist, the ppolicy module will enforce the default password policy
404 rules on the user associated with this authenticating DN. If there is
405 no default, or the referenced subentry does not exist, then no policy
406 rules will be enforced.
407 ( 1.3.6.1.4.1.42.2.27.8.1.23
409 NAME 'pwdPolicySubentry'
410 DESC 'The pwdPolicy subentry in effect for
411 this object'
412 EQUALITY distinguishedNameMatch
413 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
414 SINGLE-VALUE
415 NO-USER-MODIFICATION
416 USAGE directoryOperation)
417 pwdChangedTime
419 This attribute denotes the last time that the entry's password was
421 changed. This value is used by the password expiration policy to
422 determine whether the password is too old to be allowed to be used for
423 user authentication. If pwdChangedTime does not exist, the user's
424 password will not expire.
425 ( 1.3.6.1.4.1.42.2.27.8.1.16
427 NAME 'pwdChangedTime'
428 DESC 'The time the password was last changed'
429 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
430 EQUALITY generalizedTimeMatch
431 ORDERING generalizedTimeOrderingMatch
432 SINGLE-VALUE
433 NO-USER-MODIFICATION
434 USAGE directoryOperation)
435 pwdAccountLockedTime
437 This attribute contains the time that the user's account was locked.
439 If the account has been locked, the password may no longer be used to
440 authenticate the user to the directory. If pwdAccountLockedTime is set
441 to 000001010000Z, the user's account has been permanently locked and
442 may only be unlocked by an administrator. Note that account locking
443 only takes effect when the pwdLockout password policy attribute is set
444 to "TRUE".
445 ( 1.3.6.1.4.1.42.2.27.8.1.17
447 NAME 'pwdAccountLockedTime'
448 DESC 'The time an user account was locked'
449 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
450 EQUALITY generalizedTimeMatch
451 ORDERING generalizedTimeOrderingMatch
452 SINGLE-VALUE
453 NO-USER-MODIFICATION
454 USAGE directoryOperation)
455 pwdFailureTime
457 This attribute contains the timestamps of each of the consecutive
459 authentication failures made upon attempted authentication to this DN
460 (i.e. account). If too many timestamps accumulate here (refer to the
461 pwdMaxFailure password policy attribute for details), and the pwdLock‐
462 out password policy attribute is set to "TRUE", the account may be
463 locked. (Please also refer to the pwdLockout password policy
464 attribute.) Excess timestamps beyond those allowed by pwdMaxFailure
465 may also be purged. If a successful authentication is made to this DN
466 (i.e. to this user account), then pwdFailureTime will be cleansed of
467 entries.
468 ( 1.3.6.1.4.1.42.2.27.8.1.19
470 NAME 'pwdFailureTime'
471 DESC 'The timestamps of the last consecutive
472 authentication failures'
473 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
474 EQUALITY generalizedTimeMatch
475 ORDERING generalizedTimeOrderingMatch
476 NO-USER-MODIFICATION
477 USAGE directoryOperation )
478 pwdHistory
480 This attribute contains the history of previously used passwords for
482 this DN (i.e. for this user account). The values of this attribute are
483 stored in string format as follows:
484 pwdHistory=
487 time "#" syntaxOID "#" length "#" data
488 time=
490 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
491 syntaxOID = numericoid
494 This is the string representation of the dotted-decimal OID
495 that defines the syntax used to store the password. numericoid
496 is described in section 1.4 of [RFC4512].
497 length = NumericString
499 The number of octets in the data. NumericString is described
500 in section 3.3.23 of [RFC4517].
501 data =
503 Octets representing the password in the format specified by
504 syntaxOID.
505 This format allows the server to store and transmit a history of pass‐
508 words that have been used. In order for equality matching on the val‐
509 ues in this attribute to function properly, the time field is in GMT
510 format.
511 ( 1.3.6.1.4.1.42.2.27.8.1.20
513 NAME 'pwdHistory'
514 DESC 'The history of user passwords'
515 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
516 EQUALITY octetStringMatch
517 NO-USER-MODIFICATION
518 USAGE directoryOperation)
519 pwdGraceUseTime This attribute contains the list of timestamps of
521 logins made after the user password in the DN has expired. These post-
522 expiration logins are known as "grace logins". If too many grace
523 logins have been used (please refer to the pwdGraceLoginLimit password
524 policy attribute), then the DN will no longer be allowed to be used to
525 authenticate the user to the directory until the administrator changes
526 the DN's userPassword attribute.
527 ( 1.3.6.1.4.1.42.2.27.8.1.21
529 NAME 'pwdGraceUseTime'
530 DESC 'The timestamps of the grace login once the password has
531 expired'
532 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
533 EQUALITY generalizedTimeMatch
534 NO-USER-MODIFICATION
535 USAGE directoryOperation)
536 pwdReset
538 This attribute indicates whether the user's password has been reset by
540 the administrator and thus must be changed upon first use of this DN
541 for authentication to the directory. If pwdReset is set to "TRUE",
542 then the password was reset and the user must change it upon first
543 authentication. If the attribute does not exist, or is set to "FALSE",
544 the user need not change their password due to administrative reset.
545 ( 1.3.6.1.4.1.42.2.27.8.1.22
547 NAME 'pwdReset'
548 DESC 'The indication that the password has
549 been reset'
550 EQUALITY booleanMatch
551 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
552 SINGLE-VALUE
553 USAGE directoryOperation)
554
557 database bdb
558 suffix dc=example,dc=com
559 ...
560 overlay ppolicy
561 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
562
565 ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).
566 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
568 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
570 Sermersheim: documented in IETF document "draft-behera-ldap-password-
571 policy-09.txt".
572
575 The LDAP Password Policy specification is not yet an approved standard,
576 and it is still evolving. This code will continue to be in flux until
577 the specification is finalized.
578
581 This module was written in 2004 by Howard Chu of Symas Corporation with
582 significant input from Neil Dunbar and Kartik Subbarao of Hewlett-
583 Packard.
584 This manual page borrows heavily and shamelessly from the specification
586 upon which the password policy module it describes is based. This
587 source is the IETF LDAP password policy proposal by P. Behera, L.
588 Poitou and J. Sermersheim. The proposal is fully documented in the
589 IETF document named draft-behera-ldap-password-policy-09.txt, written
590 in July of 2005.
591 OpenLDAP Software is developed and maintained by The OpenLDAP Project
593 <http://www.openldap.org/>. OpenLDAP Software is derived from Univer‐
594 sity of Michigan LDAP 3.3 Release.
595OpenLDAP 2.4.23 2010/06/30 SLAPO_PPOLICY(5)