slapo-ppolicy - Password Policy overlay to slapd
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 options apply to the ppolicy overlay. They
should appear after the overlay
- ppolicy_default <policyDN>
- Specify the DN of the pwdPolicy object to use when no
specific policy is set on a given user's entry. If there is no specific
policy for an entry and no default is given, then no policies will be
- 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's local database. This setting is only useful on a replication
consumer, and also requires the updateref setting and chain
overlay to be appropriately configured.
- 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'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.
- 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 the
AccountLocked error code. Note that sending the
AccountLocked error code provides useful information to an
attacker; sites that are sensitive to security issues should not enable
overlay depends on the pwdPolicy
object class. The
definition of that class is as follows:
MUST ( pwdAttribute )
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).
MAY ( pwdCheckModule ) )
Every account that should be subject to password policy control should have a
attribute containing the DN of a valid
entry, or they can simply use the configured default. In this
way different users may be managed according to different policies.
Each one of the sections below details the meaning and use of a particular
attribute of this pwdPolicy
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
Note: in this implementation, the only value accepted for pwdAttribute
SYNTAX 18.104.22.168.4.1.1422.214.171.124.38 )
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).
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.
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
, although the password is saved in the history.
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.
When syntax checking is enabled (see also the pwdCheckQuality
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)).
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.
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.
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
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
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.
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
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.
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
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's DN. (See also pwdLockout
This attribute contains the maximum number of failed bind attempts to store in a
user'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.
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
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
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.
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
Note: this implies that when pwdAllowUserChange
is set to
"TRUE", users will still be able to change the password of another
user, subjected to access control. This restriction only applies to
modifications of ones's own password. It should also be noted that
was defined in the specification to provide rough
access control to the password attribute in implementations that do not allow
fine-grain access control. Since OpenLDAP provides fine-grain access control,
the use of this attribute is discouraged; ACLs should be used instead (see
(5) for details).
This attribute denotes whether the user's existing password must be sent along
with their new password when changing a password. If pwdSafeModify
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.
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);
parameter contains the clear-text user password, the
parameter contains a double pointer that allows the function
to return human-readable details about any error it encounters. The optional
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()'d by slapd.
Note: The user-defined loadable module named by pwdCheckModule
must be in
standard executable search PATH.
is a non-standard extension to the LDAP password
The operational attributes used by the ppolicy
module are stored in the
user'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
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'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
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.
This attribute refers directly to the pwdPolicy
subentry that is to be
used for this particular directory user. If pwdPolicySubentry
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
DESC 'The pwdPolicy subentry in effect for
This attribute denotes the last time that the entry'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
does not exist, the user's password will not expire.
DESC 'The time the password was last changed'
This attribute contains the time that the user'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's account has been permanently locked and may only be
unlocked by an administrator. Note that account locking only takes effect when
password policy attribute is set to "TRUE".
DESC 'The time an user account was locked'
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
policy attribute for details), and the pwdLockout
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
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.
DESC 'The timestamps of the last consecutive
USAGE directoryOperation )
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:
time "#" syntaxOID "#"
length "#" data
GeneralizedTime as specified in section 3.3.13
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].
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.
DESC 'The history of user passwords'
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
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
DESC 'The timestamps of the grace login once the password has expired'
This attribute indicates whether the user'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
DESC 'The indication that the password has
"OpenLDAP Administrator'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
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.
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.
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.