Section (5) slapo-ppolicy
Name
slapo−ppolicy — Password Policy overlay to slapd
Synopsis
ETCDIR/slapd.conf
DESCRIPTION
The ppolicy
overlay is an implementation of the most recent IETF Password
Policy proposal for LDAP. When instantiated, it intercepts,
decodes and applies specific password policy controls to
overall use of a backend database, changes to user password
fields, etc.
The overlay provides a variety of password control mechanisms. They include password aging -- both minimum and maximum ages, password reuse and duplication control, account time-outs, mandatory password resets, acceptable password content, and even grace logins. Different groups of users may be associated with different password policies, and there is no limit to the number of password policies that may be created.
Note that some of the policies do not take effect when the
operation is performed with the rootdn
identity; all the
operations, when performed with any other identity, may be
subjected to constraints, like access control. This overlay
requires a rootdn to be configured on the database.
Note that the IETF Password Policy proposal for LDAP makes sense when considering a single-valued password attribute, while the userPassword attribute allows multiple values. This implementation enforces a single value for the userPassword attribute, despite its specification.
CONFIGURATION
These slapd.conf
configuration options apply to the ppolicy overlay. They
should appear after the overlay
directive.
- ppolicy_default <policyDN>
-
Specify the DN of the pwdPolicy object to use when no specific policy is set on a given user_zsingle_quotesz_s entry. If there is no specific policy for an entry and no default is given, then no policies will be enforced.
ppolicy_forward_updates
-
Specify that policy state changes that result from Bind operations (such as recording failures, lockout, etc.) on a consumer should be forwarded to a master instead of being written directly into the consumer_zsingle_quotesz_s local database. This setting is only useful on a replication consumer, and also requires the
updateref
setting andchain
overlay to be appropriately configured. ppolicy_hash_cleartext
-
Specify that cleartext passwords present in Add and Modify requests should be hashed before being stored in the database. This violates the X.500/LDAP information model, but may be needed to compensate for LDAP clients that don_zsingle_quotesz_t use the Password Modify extended operation to manage passwords. It is recommended that when this option is used that compare, search, and read access be denied to all directory users.
ppolicy_use_lockout
-
A client will always receive an LDAP
InvalidCredentials
response when Binding to a locked account. By default, when a Password Policy control was provided on the Bind request, a Password Policy response will be included with no special error code set. This option changes the Password Policy response to include theAccountLocked
error code. Note that sending theAccountLocked
error code provides useful information to an attacker; sites that are sensitive to security issues should not enable this option.
OBJECT CLASS
The ppolicy
overlay depends on the pwdPolicy
object class. The
definition of that class is as follows:
( 1.3.6.1.4.1.42.2.27.8.2.1 NAME _zsingle_quotesz_pwdPolicy_zsingle_quotesz_ AUXILIARY SUP top MUST ( pwdAttribute ) MAY ( pwdMinAge $ pwdMaxAge $ pwdInHistory $ pwdCheckQuality $ pwdMinLength $ pwdExpireWarning $ pwdGraceAuthnLimit $ pwdLockout $ pwdLockoutDuration $ pwdMaxFailure $ pwdFailureCountInterval $ pwdMustChange $ pwdAllowUserChange $ pwdSafeModify $ pwdMaxRecordedFailure ) )
This implementation also provides an additional pwdPolicyChecker
objectclass,
used for password quality checking (see below).
( 1.3.6.1.4.1.4754.2.99.1 NAME _zsingle_quotesz_pwdPolicyChecker_zsingle_quotesz_ AUXILIARY SUP top MAY ( pwdCheckModule ) )
Every account that should be subject to password policy
control should have a pwdPolicySubentry
attribute
containing the DN of a valid pwdPolicy
entry, or they can
simply use the configured default. In this way different
users may be managed according to different policies.
OBJECT CLASS ATTRIBUTES
Each one of the sections below details the meaning and use
of a particular attribute of this pwdPolicy
object class.
pwdAttribute
This attribute contains the name of the attribute to which
the password policy is applied. For example, the password
policy may be applied to the userPassword
attribute.
![]() |
Note |
---|---|
In this implementation, the only value accepted
for |
( 1.3.6.1.4.1.42.2.27.8.1.1 NAME _zsingle_quotesz_pwdAttribute_zsingle_quotesz_ EQUALITY objectIdentifierMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
pwdMinAge
This attribute contains the number of seconds that must elapse between modifications allowed to the password. If this attribute is not present, zero seconds is assumed (i.e. the password may be modified whenever and however often is desired).
( 1.3.6.1.4.1.42.2.27.8.1.2 NAME _zsingle_quotesz_pwdMinAge_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdMaxAge
This attribute contains the number of seconds after which a modified password will expire. If this attribute is not present, or if its value is zero (0), then passwords will not expire.
( 1.3.6.1.4.1.42.2.27.8.1.3 NAME _zsingle_quotesz_pwdMaxAge_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdInHistory
This attribute is used to specify the maximum number of
used passwords that will be stored in the pwdHistory
attribute. If the
pwdInHistory
attribute is not present, or if its value is zero (0), used
passwords will not be stored in pwdHistory
and thus any
previously-used password may be reused. No history checking
occurs if the password is being modified by the rootdn
, although the password
is saved in the history.
( 1.3.6.1.4.1.42.2.27.8.1.4 NAME _zsingle_quotesz_pwdInHistory_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdCheckQuality
This attribute indicates if and how password syntax will be checked while a password is being modified or added. If this attribute is not present, or its value is zero (0), no syntax checking will be done. If its value is one (1), the server will check the syntax, and if the server is unable to check the syntax, whether due to a client-side hashed password or some other reason, it will be accepted. If its value is two (2), the server will check the syntax, and if the server is unable to check the syntax it will return an error refusing the password.
( 1.3.6.1.4.1.42.2.27.8.1.5 NAME _zsingle_quotesz_pwdCheckQuality_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdMinLength
When syntax checking is enabled (see also the pwdCheckQuality
attribute),
this attribute contains the minimum number of characters that
will be accepted in a password. If this attribute is not
present, minimum password length is not enforced. If the
server is unable to check the length of the password, whether
due to a client-side hashed password or some other reason,
the server will, depending on the value of pwdCheckQuality
, either
accept the password without checking it (if pwdCheckQuality
is zero (0)
or one (1)) or refuse it (if pwdCheckQuality
is two
(2)).
( 1.3.6.1.4.1.42.2.27.8.1.6 NAME _zsingle_quotesz_pwdMinLength_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdExpireWarning
This attribute contains the maximum number of seconds before a password is due to expire that expiration warning messages will be returned to a user who is authenticating to the directory. If this attribute is not present, or if the value is zero (0), no warnings will be sent.
( 1.3.6.1.4.1.42.2.27.8.1.7 NAME _zsingle_quotesz_pwdExpireWarning_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdGraceAuthnLimit
This attribute contains the number of times that an expired password may be used to authenticate a user to the directory. If this attribute is not present or if its value is zero (0), users with expired passwords will not be allowed to authenticate to the directory.
( 1.3.6.1.4.1.42.2.27.8.1.8 NAME _zsingle_quotesz_pwdGraceAuthnLimit_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdLockout
This attribute specifies the action that should be taken
by the directory when a user has made a number of failed
attempts to authenticate to the directory. If pwdLockout
is set (its value
is TRUE), the user will not be allowed to attempt to
authenticate to the directory after there have been a
specified number of consecutive failed bind attempts. The
maximum number of consecutive failed bind attempts allowed is
specified by the pwdMaxFailure
attribute. If
pwdLockout
is not
present, or if its value is FALSE, the password may be used
to authenticate no matter how many consecutive failed bind
attempts have been made.
( 1.3.6.1.4.1.42.2.27.8.1.9 NAME _zsingle_quotesz_pwdLockout_zsingle_quotesz_ EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE−VALUE )
pwdLockoutDuration
This attribute contains the number of seconds during which
the password cannot be used to authenticate the user to the
directory due to too many consecutive failed bind attempts.
(See also pwdLockout
and pwdMaxFailure
.) If pwdLockoutDuration
is not
present, or if its value is zero (0), the password cannot be
used to authenticate the user to the directory again until it
is reset by an administrator.
( 1.3.6.1.4.1.42.2.27.8.1.10 NAME _zsingle_quotesz_pwdLockoutDuration_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdMaxFailure
This attribute contains the number of consecutive failed
bind attempts after which the password may not be used to
authenticate a user to the directory. If pwdMaxFailure
is not present,
or its value is zero (0), then a user will be allowed to
continue to attempt to authenticate to the directory, no
matter how many consecutive failed bind attempts have
occurred with that user_zsingle_quotesz_s DN. (See also pwdLockout
and pwdLockoutDuration
.)
( 1.3.6.1.4.1.42.2.27.8.1.11 NAME _zsingle_quotesz_pwdMaxFailure_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdMaxRecordedFailure
This attribute contains the maximum number of failed bind
attempts to store in a user_zsingle_quotesz_s entry. If pwdMaxRecordedFailure
is not
present, or its value is zero (0), then it defaults to the
value of pwdMaxFailure
. If that value
is also 0, the default is 5.
( 1.3.6.1.4.1.42.2.27.8.1.16 NAME _zsingle_quotesz_pwdMaxRecordedFailure_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdFailureCountInterval
This attribute contains the number of seconds after which
old consecutive failed bind attempts are purged from the
failure counter, even though no successful authentication has
occurred. If pwdFailureCountInterval
is
not present, or its value is zero (0), the failure counter
will only be reset by a successful authentication.
( 1.3.6.1.4.1.42.2.27.8.1.12 NAME _zsingle_quotesz_pwdFailureCountInterval_zsingle_quotesz_ EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE−VALUE )
pwdMustChange
This attribute specifies whether users must change their
passwords when they first bind to the directory after a
password is set or reset by the administrator, or not. If
pwdMustChange
has a
value of TRUE, users must change their passwords when they
first bind to the directory after a password is set or reset
by the administrator. If pwdMustChange
is not present,
or its value is FALSE, users are not required to change
their password upon binding after the administrator sets or
resets the password.
( 1.3.6.1.4.1.42.2.27.8.1.13 NAME _zsingle_quotesz_pwdMustChange_zsingle_quotesz_ EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE−VALUE )
pwdAllowUserChange
This attribute specifies whether users are allowed to
change their own passwords or not. If pwdAllowUserChange
is set to
TRUE, or if the attribute is not present, users will be
allowed to change their own passwords. If its value is
FALSE, users will not be allowed to change their own
passwords.
![]() |
Note |
---|---|
This implies that when |
( 1.3.6.1.4.1.42.2.27.8.1.14 NAME _zsingle_quotesz_pwdAllowUserChange_zsingle_quotesz_ EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE−VALUE )
pwdSafeModify
This attribute denotes whether the user_zsingle_quotesz_s existing
password must be sent along with their new password when
changing a password. If pwdSafeModify
is set to
TRUE, the existing password must be sent along with the new
password. If the attribute is not present, or its value is
FALSE, the existing password need not be sent along with
the new password.
( 1.3.6.1.4.1.42.2.27.8.1.15 NAME _zsingle_quotesz_pwdSafeModify_zsingle_quotesz_ EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE−VALUE )
pwdCheckModule
This attribute names a user-defined loadable module that
must instantiate the check_password() function. This function
will be called to further check a new password if pwdCheckQuality
is set to one
(1) or two (2), after all of the built-in password compliance
checks have been passed. This function will be called
according to this function prototype:
int
check_password
(char *pPasswd, char **ppErrStr, Entry *pEntry);
The pPasswd
parameter contains the clear-text user password, the
ppErrStr
parameter
contains a double pointer that allows the function to return
human-readable details about any error it encounters. The
optional pEntry
parameter, if non-NULL, carries a pointer to the entry whose
password is being checked. If ppErrStr
is NULL, then
funcName
must NOT
attempt to use it/them. A return value of LDAP_SUCCESS from
the called function indicates that the password is ok, any
other value indicates that the password is unacceptable. If
the password is unacceptable, the server will return an error
to the client, and ppErrStr
may be used to
return a human-readable textual explanation of the error. The
error string must be dynamically allocated as it will be
free()_zsingle_quotesz_d by slapd.
( 1.3.6.1.4.1.4754.1.99.1 NAME _zsingle_quotesz_pwdCheckModule_zsingle_quotesz_ EQUALITY caseExactIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 SINGLE−VALUE )
![]() |
Note |
---|---|
The user-defined loadable module named by
|
![]() |
Note |
---|---|
|
OPERATIONAL ATTRIBUTES
The operational attributes used by the ppolicy
module are stored in
the user_zsingle_quotesz_s entry. Most of these attributes are not intended
to be changed directly by users; they are there to track user
activity. They have been detailed here so that administrators
and users can both understand the workings of the ppolicy
module.
Note that the current IETF Password Policy proposal does not define how these operational attributes are expected to behave in a replication environment. In general, authentication attempts on a slave server only affect the copy of the operational attributes on that slave and will not affect any attributes for a user_zsingle_quotesz_s entry on the master server. Operational attribute changes resulting from authentication attempts on a master server will usually replicate to the slaves (and also overwrite any changes that originated on the slave). These behaviors are not guaranteed and are subject to change when a formal specification emerges.
userPassword
The userPassword
attribute is not strictly part of the ppolicy
module. It is,
however, the attribute that is tracked and controlled by the
module. Please refer to the standard OpenLDAP schema for its
definition.
pwdPolicySubentry
This attribute refers directly to the pwdPolicy
subentry that is to
be used for this particular directory user. If pwdPolicySubentry
exists, it
must contain the DN of a valid pwdPolicy
object. If it does
not exist, the ppolicy
module will enforce
the default password policy rules on the user associated with
this authenticating DN. If there is no default, or the
referenced subentry does not exist, then no policy rules will
be enforced.
( 1.3.6.1.4.1.42.2.27.8.1.23 NAME _zsingle_quotesz_pwdPolicySubentry_zsingle_quotesz_ DESC _zsingle_quotesz_The pwdPolicy subentry in effect for this object_zsingle_quotesz_ EQUALITY distinguishedNameMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 SINGLE−VALUE NO−USER−MODIFICATION USAGE directoryOperation)
pwdChangedTime
This attribute denotes the last time that the entry_zsingle_quotesz_s
password was changed. This value is used by the password
expiration policy to determine whether the password is too
old to be allowed to be used for user authentication. If
pwdChangedTime
does
not exist, the user_zsingle_quotesz_s password will not expire.
( 1.3.6.1.4.1.42.2.27.8.1.16 NAME _zsingle_quotesz_pwdChangedTime_zsingle_quotesz_ DESC _zsingle_quotesz_The time the password was last changed_zsingle_quotesz_ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SINGLE−VALUE NO−USER−MODIFICATION USAGE directoryOperation)
pwdAccountLockedTime
This attribute contains the time that the user_zsingle_quotesz_s account
was locked. If the account has been locked, the password may
no longer be used to authenticate the user to the directory.
If pwdAccountLockedTime
is set
to 000001010000Z, the user_zsingle_quotesz_s account has been permanently
locked and may only be unlocked by an administrator. Note
that account locking only takes effect when the pwdLockout
password policy
attribute is set to TRUE.
( 1.3.6.1.4.1.42.2.27.8.1.17 NAME _zsingle_quotesz_pwdAccountLockedTime_zsingle_quotesz_ DESC _zsingle_quotesz_The time an user account was locked_zsingle_quotesz_ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SINGLE−VALUE NO−USER−MODIFICATION USAGE directoryOperation)
pwdFailureTime
This attribute contains the timestamps of each of the
consecutive authentication failures made upon attempted
authentication to this DN (i.e. account). If too many
timestamps accumulate here (refer to the pwdMaxFailure
password policy
attribute for details), and the pwdLockout
password policy
attribute is set to TRUE, the account may be locked.
(Please also refer to the pwdLockout
password policy
attribute.) Excess timestamps beyond those allowed by
pwdMaxFailure
or
pwdMaxRecordedFailure
may
also be purged. If a successful authentication is made to
this DN (i.e. to this user account), then pwdFailureTime
will be
cleansed of entries.
( 1.3.6.1.4.1.42.2.27.8.1.19 NAME _zsingle_quotesz_pwdFailureTime_zsingle_quotesz_ DESC _zsingle_quotesz_The timestamps of the last consecutive authentication failures_zsingle_quotesz_ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch NO−USER−MODIFICATION USAGE directoryOperation )
pwdHistory
This attribute contains the history of previously used passwords for this DN (i.e. for this user account). The values of this attribute are stored in string format as follows:
pwdHistory=
time # syntaxOID # length # data
time=
GeneralizedTime as specified in section 3.3.13 of [RFC4517]
syntaxOID = numericoid
This is the string representation of the dotted-decimal OID that defines the syntax used to store the password. numericoid is described in section 1.4 of [RFC4512].
length = NumericString
The number of octets in the data. NumericString is described in section 3.3.23 of [RFC4517].
data =
Octets representing the password in the format specified by syntaxOID.
This format allows the server to store and transmit a history of passwords that have been used. In order for equality matching on the values in this attribute to function properly, the time field is in GMT format.
( 1.3.6.1.4.1.42.2.27.8.1.20 NAME _zsingle_quotesz_pwdHistory_zsingle_quotesz_ DESC _zsingle_quotesz_The history of user passwords_zsingle_quotesz_ SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 EQUALITY octetStringMatch NO−USER−MODIFICATION USAGE directoryOperation)
pwdGraceUseTime
This attribute contains the list of timestamps of logins made
after the user password in the DN has expired. These
post-expiration logins are known as grace logins. If too many
grace logins have been
used (please refer to the pwdGraceLoginLimit
password
policy attribute), then the DN will no longer be allowed to
be used to authenticate the user to the directory until the
administrator changes the DN_zsingle_quotesz_s userPassword
attribute.
( 1.3.6.1.4.1.42.2.27.8.1.21 NAME _zsingle_quotesz_pwdGraceUseTime_zsingle_quotesz_ DESC _zsingle_quotesz_The timestamps of the grace login once the password has expired_zsingle_quotesz_ SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 EQUALITY generalizedTimeMatch NO−USER−MODIFICATION USAGE directoryOperation)
pwdReset
This attribute indicates whether the user_zsingle_quotesz_s password has
been reset by the administrator and thus must be changed upon
first use of this DN for authentication to the directory. If
pwdReset
is set to
TRUE, then the password was reset and the user must change
it upon first authentication. If the attribute does not
exist, or is set to FALSE, the user need not change their
password due to administrative reset.
( 1.3.6.1.4.1.42.2.27.8.1.22 NAME _zsingle_quotesz_pwdReset_zsingle_quotesz_ DESC _zsingle_quotesz_The indication that the password has been reset_zsingle_quotesz_ EQUALITY booleanMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 SINGLE−VALUE USAGE directoryOperation)
EXAMPLES
database bdb suffix dc=example,dc=com ... overlay ppolicy ppolicy_default cn=Standard,ou=Policies,dc=example,dc=com
SEE ALSO
ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).
OpenLDAP Administrator_zsingle_quotesz_s Guide (http://www.OpenLDAP.org/doc/admin/)
IETF LDAP password policy proposal by P. Behera, L. Poitou and J. Sermersheim: documented in IETF document draft-behera-ldap-password-policy-09.txt.
BUGS
The LDAP Password Policy specification is not yet an approved standard, and it is still evolving. This code will continue to be in flux until the specification is finalized.
ACKNOWLEDGEMENTS
This module was written in 2004 by Howard Chu of Symas Corporation with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.
This manual page borrows heavily and shamelessly from the specification upon which the password policy module it describes is based. This source is the IETF LDAP password policy proposal by P. Behera, L. Poitou and J. Sermersheim. The proposal is fully documented in the IETF document named draft-behera-ldap-password-policy-09.txt, written in July of 2005.
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.