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 Note: this implies that when pwdAllowUserChange is set to "TRUE", users
317 will still be able to change the password of another user, subjected to
318 access control. This restriction only applies to modifications of
319 ones's own password. It should also be noted that pwdAllowUserChange
320 was defined in the specification to provide rough access control to the
321 password attribute in implementations that do not allow fine-grain
322 access control. Since OpenLDAP provides fine-grain access control, the
323 use of this attribute is discouraged; ACLs should be used instead (see
324 slapd.access(5) for details).
325 ( 1.3.6.1.4.1.42.2.27.8.1.14
327 NAME 'pwdAllowUserChange'
328 EQUALITY booleanMatch
329 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
330 SINGLE-VALUE )
331 pwdSafeModify
333 This attribute denotes whether the user's existing password must be
335 sent along with their new password when changing a password. If pwd‐
336 SafeModify is set to "TRUE", the existing password must be sent along
337 with the new password. If the attribute is not present, or its value
338 is "FALSE", the existing password need not be sent along with the new
339 password.
340 ( 1.3.6.1.4.1.42.2.27.8.1.15
342 NAME 'pwdSafeModify'
343 EQUALITY booleanMatch
344 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
345 SINGLE-VALUE )
346 pwdCheckModule
348 This attribute names a user-defined loadable module that must instanti‐
350 ate the check_password() function. This function will be called to
351 further check a new password if pwdCheckQuality is set to one (1) or
352 two (2), after all of the built-in password compliance checks have been
353 passed. This function will be called according to this function proto‐
354 type:
355 int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);
356 The pPasswd parameter contains the clear-text user password, the
357 ppErrStr parameter contains a double pointer that allows the function
358 to return human-readable details about any error it encounters. The
359 optional pEntry parameter, if non-NULL, carries a pointer to the entry
360 whose password is being checked. If ppErrStr is NULL, then funcName
361 must NOT attempt to use it/them. A return value of LDAP_SUCCESS from
362 the called function indicates that the password is ok, any other value
363 indicates that the password is unacceptable. If the password is unac‐
364 ceptable, the server will return an error to the client, and ppErrStr
365 may be used to return a human-readable textual explanation of the
366 error. The error string must be dynamically allocated as it will be
367 free()'d by slapd.
368 ( 1.3.6.1.4.1.4754.1.99.1
370 NAME 'pwdCheckModule'
371 EQUALITY caseExactIA5Match
372 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
373 SINGLE-VALUE )
374 Note: The user-defined loadable module named by pwdCheckModule must be
376 in slapd's standard executable search PATH.
377 Note: pwdCheckModule is a non-standard extension to the LDAP password
379 policy proposal.
380
383 The operational attributes used by the ppolicy module are stored in the
384 user's entry. Most of these attributes are not intended to be changed
385 directly by users; they are there to track user activity. They have
386 been detailed here so that administrators and users can both understand
387 the workings of the ppolicy module.
388 Note that the current IETF Password Policy proposal does not define how
391 these operational attributes are expected to behave in a replication
392 environment. In general, authentication attempts on a slave server only
393 affect the copy of the operational attributes on that slave and will
394 not affect any attributes for a user's entry on the master server.
395 Operational attribute changes resulting from authentication attempts on
396 a master server will usually replicate to the slaves (and also over‐
397 write any changes that originated on the slave). These behaviors are
398 not guaranteed and are subject to change when a formal specification
399 emerges.
400 userPassword
402 The userPassword attribute is not strictly part of the ppolicy module.
404 It is, however, the attribute that is tracked and controlled by the
405 module. Please refer to the standard OpenLDAP schema for its defini‐
406 tion.
407 pwdPolicySubentry
409 This attribute refers directly to the pwdPolicy subentry that is to be
411 used for this particular directory user. If pwdPolicySubentry exists,
412 it must contain the DN of a valid pwdPolicy object. If it does not
413 exist, the ppolicy module will enforce the default password policy
414 rules on the user associated with this authenticating DN. If there is
415 no default, or the referenced subentry does not exist, then no policy
416 rules will be enforced.
417 ( 1.3.6.1.4.1.42.2.27.8.1.23
419 NAME 'pwdPolicySubentry'
420 DESC 'The pwdPolicy subentry in effect for
421 this object'
422 EQUALITY distinguishedNameMatch
423 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
424 SINGLE-VALUE
425 NO-USER-MODIFICATION
426 USAGE directoryOperation)
427 pwdChangedTime
429 This attribute denotes the last time that the entry's password was
431 changed. This value is used by the password expiration policy to
432 determine whether the password is too old to be allowed to be used for
433 user authentication. If pwdChangedTime does not exist, the user's
434 password will not expire.
435 ( 1.3.6.1.4.1.42.2.27.8.1.16
437 NAME 'pwdChangedTime'
438 DESC 'The time the password was last changed'
439 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
440 EQUALITY generalizedTimeMatch
441 ORDERING generalizedTimeOrderingMatch
442 SINGLE-VALUE
443 NO-USER-MODIFICATION
444 USAGE directoryOperation)
445 pwdAccountLockedTime
447 This attribute contains the time that the user's account was locked.
449 If the account has been locked, the password may no longer be used to
450 authenticate the user to the directory. If pwdAccountLockedTime is set
451 to 000001010000Z, the user's account has been permanently locked and
452 may only be unlocked by an administrator. Note that account locking
453 only takes effect when the pwdLockout password policy attribute is set
454 to "TRUE".
455 ( 1.3.6.1.4.1.42.2.27.8.1.17
457 NAME 'pwdAccountLockedTime'
458 DESC 'The time an user account was locked'
459 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
460 EQUALITY generalizedTimeMatch
461 ORDERING generalizedTimeOrderingMatch
462 SINGLE-VALUE
463 NO-USER-MODIFICATION
464 USAGE directoryOperation)
465 pwdFailureTime
467 This attribute contains the timestamps of each of the consecutive
469 authentication failures made upon attempted authentication to this DN
470 (i.e. account). If too many timestamps accumulate here (refer to the
471 pwdMaxFailure password policy attribute for details), and the pwdLock‐
472 out password policy attribute is set to "TRUE", the account may be
473 locked. (Please also refer to the pwdLockout password policy
474 attribute.) Excess timestamps beyond those allowed by pwdMaxFailure
475 may also be purged. If a successful authentication is made to this DN
476 (i.e. to this user account), then pwdFailureTime will be cleansed of
477 entries.
478 ( 1.3.6.1.4.1.42.2.27.8.1.19
480 NAME 'pwdFailureTime'
481 DESC 'The timestamps of the last consecutive
482 authentication failures'
483 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
484 EQUALITY generalizedTimeMatch
485 ORDERING generalizedTimeOrderingMatch
486 NO-USER-MODIFICATION
487 USAGE directoryOperation )
488 pwdHistory
490 This attribute contains the history of previously used passwords for
492 this DN (i.e. for this user account). The values of this attribute are
493 stored in string format as follows:
494 pwdHistory=
497 time "#" syntaxOID "#" length "#" data
498 time=
500 GeneralizedTime as specified in section 3.3.13 of [RFC4517]
501 syntaxOID = numericoid
504 This is the string representation of the dotted-decimal OID
505 that defines the syntax used to store the password. numericoid
506 is described in section 1.4 of [RFC4512].
507 length = NumericString
509 The number of octets in the data. NumericString is described
510 in section 3.3.23 of [RFC4517].
511 data =
513 Octets representing the password in the format specified by
514 syntaxOID.
515 This format allows the server to store and transmit a history of pass‐
518 words that have been used. In order for equality matching on the val‐
519 ues in this attribute to function properly, the time field is in GMT
520 format.
521 ( 1.3.6.1.4.1.42.2.27.8.1.20
523 NAME 'pwdHistory'
524 DESC 'The history of user passwords'
525 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
526 EQUALITY octetStringMatch
527 NO-USER-MODIFICATION
528 USAGE directoryOperation)
529 pwdGraceUseTime This attribute contains the list of timestamps of
531 logins made after the user password in the DN has expired. These post-
532 expiration logins are known as "grace logins". If too many grace
533 logins have been used (please refer to the pwdGraceLoginLimit password
534 policy attribute), then the DN will no longer be allowed to be used to
535 authenticate the user to the directory until the administrator changes
536 the DN's userPassword attribute.
537 ( 1.3.6.1.4.1.42.2.27.8.1.21
539 NAME 'pwdGraceUseTime'
540 DESC 'The timestamps of the grace login once the password has
541 expired'
542 SYNTAX 1.3.6.1.4.1.1466.115.121.1.24
543 EQUALITY generalizedTimeMatch
544 NO-USER-MODIFICATION
545 USAGE directoryOperation)
546 pwdReset
548 This attribute indicates whether the user's password has been reset by
550 the administrator and thus must be changed upon first use of this DN
551 for authentication to the directory. If pwdReset is set to "TRUE",
552 then the password was reset and the user must change it upon first
553 authentication. If the attribute does not exist, or is set to "FALSE",
554 the user need not change their password due to administrative reset.
555 ( 1.3.6.1.4.1.42.2.27.8.1.22
557 NAME 'pwdReset'
558 DESC 'The indication that the password has
559 been reset'
560 EQUALITY booleanMatch
561 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
562 SINGLE-VALUE
563 USAGE directoryOperation)
564
567 database bdb
568 suffix dc=example,dc=com
569 ...
570 overlay ppolicy
571 ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
572
575 ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).
576 "OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)
578 IETF LDAP password policy proposal by P. Behera, L. Poitou and J.
580 Sermersheim: documented in IETF document "draft-behera-ldap-password-
581 policy-09.txt".
582
585 The LDAP Password Policy specification is not yet an approved standard,
586 and it is still evolving. This code will continue to be in flux until
587 the specification is finalized.
588
591 This module was written in 2004 by Howard Chu of Symas Corporation with
592 significant input from Neil Dunbar and Kartik Subbarao of Hewlett-
593 Packard.
594 This manual page borrows heavily and shamelessly from the specification
596 upon which the password policy module it describes is based. This
597 source is the IETF LDAP password policy proposal by P. Behera, L.
598 Poitou and J. Sermersheim. The proposal is fully documented in the
599 IETF document named draft-behera-ldap-password-policy-09.txt, written
600 in July of 2005.
601 OpenLDAP Software is developed and maintained by The OpenLDAP Project
603 <http://www.openldap.org/>. OpenLDAP Software is derived from Univer‐
604 sity of Michigan LDAP 3.3 Release.
605OpenLDAP 2.4.40 2014/09/20 SLAPO_PPOLICY(5)