Chapter 6 OpenLDAP password policy overlay

The ppolicy module provides enhanced password management capabilities that are applied to non-rootdn bind attempts in OpenLDAP. The standard ppolicy overlay provides the following user controlled capabilities:

Password aging (both minimum and maximum ages may be defined)
Password history to avoid re-use of the same password set within a time period
Password quality - new passwords may be checked for various characteristics
Maximum number of consecutive failed authentication attempts
Automatic account locking
Automatic or administrator action to unlock an account
Grace binds (allowing use of expired passwords for a limited number of attempts)
Password policies may be defined as being either DIT-wide, user or group specific or any combination.

The specification of functionality is described by an RFC draft draft-behera-ldap-password-policy-09.txt which appears to have remained in that state since since 2005.

Note: The standard ppolicy module, under certain conditions, can cause an excessive number of lockouts leading to both increased administration load and user frustration. Specifically when password aging is implemented and used in conjunction with LDAP utilities which cache passwords. If the cached password is not changed immediately the user changes their password then, on the next login attempt the previous (cached) password is used leading to a failure. In most cases the utility's error recovery makes multiple attempts (3, 5 or more attempts are not uncommon) which can lead to threshold limits being exceeded and account lockouts. Mozilla Corporation asked Zytrax to develop a modified version of ppolicy that differentiates between repeat attempts using the same password and attempts using unique passwords (likely dictionary attacks) and use different lockout strategies for each condition. The modified version is in use on production servers (on 2.4.11 and 2.4.16) and has been blogged about by Mr. Aravind Gottipati of Mozilla Corporation. Mozilla Corporation has made the modifications freely available and they be can downloaded for OpenLDAP 2.4.11 version or OpenLDAP 2.4.16 version from this site. Full instructions and a modified man page are provided. The documentation on this page covers both the standard OpenLDAP version and the modified version. The documentation specific to the modified version is identified by being enclosed in a <MODIFIED></MODIFIED> tag sequence.

Usage Overview
OpenLDAP Configuration Directives
pwdPolicy ObjectClass and Attributes
Operational Attributes
ppolicy schema
Unlocking an Account
Configuration Examples

Usage Overview

Password policy is invoked on a specific DIT by a combination of including the ppolicy.schema file, the overlay ppolicy directive, optional ppolicy configuration directives and definition of one or more password policy entries. The password policy module also generates a number of operational attributes that may be used to inspect the status of, or - in limited cases - control, password policy for user entries.

When using OLC (cn=config) the Password Policy overlay is invoked by:

Loading the ppolicy.schema file using this procedure.
If the ppolicy module is loaded dynamically it must be added using the olcModuleLoad attribute using this procedure.
The ppolicy overlay entry must be created for the relevant database using this procedure.
ppolicy overlay is created using the olcPPolicyConfig objectClass and specific attributes are then added to the entry as defined below.

The Password Policy overlay is invoked using slapd.conf for a specific DIT as shown:

...
# include the ppolicy schema
include ppolicy.schema
...
# required if the overlay is built dynamically
loadmodule ppolicy.la
# OR
loadmodule ppolicy.so
...
database bdb
suffix "dc=example,dc=com"
...
# invokes password policies for this DIT only
overlay ppolicy
# optional ppolicy directives
...
# other overlay directives or 
# next database directive

OpenLDAP Configuration Attributes/Directives

olcPPolicyDefault (ppolicy_default)

# OLC (cn=config) form
olcPPolicyDefault: DN

# slapd.conf form
ppolicy_default DN
# example
# OLC (cn=config) form
olcPPolicyDefault: cn=defaultpwpolicy,dc=example.com

# slapd.conf form
ppolicy_default "cn=defaultpwpolicy,dc=example.com"

This attribute/directive defines the DN of a default password policy that will be used in the absence of any user specific password policy.

The ppolicy_default directive thus defines a DIT-wide password policy and is the simplest way to invoke password policy capabilities. Once the default password policy is defined no further configuration is required. User entry specific password policies (defined using pwdPolicySubentry), if present, will always be used rather than the default.

If the olcPPolicyDefault/ppolicy_default directive is not defined and there is no specific password policy for the user then no password policy will be applied for that user entry It is thus possible to define all users to have a generic policy, a user specific policy for each user or apply password policy to only a limited number or class of users.

olcPPolicyHashCleartext (ppolicy_hash_cleartext)

# OLC (cn=config) form
olcPPolicyHashCleartext: TRU | FALSE

# slapd.conf form
ppolicy_hash_cleartext
# the directive takes no parameters
ppolicy_hash_cleartext

This attribute/directive tells the server to save cleartext passwords, supplied using normal Add or Modify requests, in the DIT using the server's default hash algorithm. Without this directive the passwords would be stored in cleartext meaning that simple searches would return the cleartext password. To guard against this possibility all password attributes should deny read access for all users (generally a good policy even if hashed passwords are used). This attribute/directive is not necessary if all LDAP clients are known to use Password Modify extended operation.

olcPPolicyUseLockout (ppolicy_use_lockout)

# OLC (cn=config) form
olcPPolicyUseLockout: TRUE | FALSE

# slapd.conf form
ppolicy_use_lockout
# the directive takes no parameters
ppolicy_use_lockout

Bind attempts to locked accounts will always return an error (by default InvalidCredentials). This attribute/directive allows the server to return a specific AccountLocked error code. As a note of caution returning an AccountLocked error code may assist hackers in that they can observe effects on the server of various access attempts and derive operational settings (such as lockout thresholds) which may assist them in subsequent attacks.

olcPPolicyForwardUpdates (ppolicy_forward_updates)

# OLC (cn=config) form
olcPPolicyForwardUpdates: TRUE | FALSE

# slapd.conf form
ppolicy_forward_updates
# the directive takes no parameters
ppolicy_forward_updates

This attribute/directive is only applicable for a slave (consumer) configuration. If present the attribute/directive indicates that password policy failures will not be maintained on the slave (consumer) but will be immediately written to the master (provider). When this attribute/directive is present (TRUE) is requires the olcUpdateRef/updateref attribute/directive and chain overlay to be configured.

pwdPolicy ObjectClass and Attributes

To invoke password policies one or more pwdPolicy (AUXILIARY) ObjectClasses must be defined either for a specific account or account classes or on a DIT-wide basis. If required on account specific basis then the account entry, for example inetOrgPerson, will require addition of an pwdPolicySubentry attribute defining the DN of the specific policy to be applied. The pwdPolicy ObjectClass schema definition is available. The following sections describe each of the attributes in this ObjectClass. A number of worked examples are provided.

pwdAllowUserChange

pwdAllowUserChange TRUE | FALSE

# example
pwdAllowUserChange TRUE

This attribute controls whether users are allowed to change their own passwords. If the attribute value is TRUE (the default) then the user is allowed to change their password. If the attribute value is FALSE the user is not allowed to change their password (it can only be done for them by an administrator).

pwdAttribute

pwdAttribute attribute-name

# example
pwdAttribute secretCode

This attribute allows for future extension of the password policy to cover different password attributes. The default value (currently the only one supported) is userPassword. Thus the password policy (at this time) is applied only to bind operation using userPassword. This attribute can be safely omitted at this time.

pwdCheckModule

pwdCheckModule name-of-module

# example
pwdCheckModule pwcheck.la

This attribute defines the name to a user supplied password quality check module that will be called to perform password quality checks and is only relevant if pwdCheckQuality is either 1 or 2 and may be omitted in all other cases. Note: pwdCheckModule is a non-standard extension to the LDAP password policy.

pwdCheckQuality

pwdCheckQuality value

# example
pwdCheckQuality 0

If the value of this parameter is 0 (the default) then no policy checks are carried. If the value is 1 and the supplied password is in cleartext then a user supplied function (defined using the pwdCheckModule - if defined - will be called to check the password quality. If this function is not available then the password will be accepted (assuming it passes all the other tests defined by the various pwdPolicy attributes). If the value is 2 and the supplied password is in cleartext then a user supplied function will be called to check the password quality. If this function is not available then the password will be rejected. If a user supplied password quality module is not supplied this attribute cn be safely omitted.

pwdExpireWarning

pwdExpireWarning time-in-seconds

# example
pwdExpireWarning 3600

This attribute controls whether and when a warning message of password expiration will be returned on a bind attempt. If the value of this attribute is 0 (the default) then no warnings will be given on bind attempts while the password is still valid. If the value is >0 then it defines the start time - in seconds - prior to the password expiry that password expiry warning messages are returned in bind responses.

pwdFailureCountInterval

pwdFailureCountInterval time-in-seconds

# example
pwdFailureCountInterval 20

This attribute controls when the count of consecutive password failures is reset. If the attribute value is 0 (the default) the count of consecutive password failures is only reset on successful authentication. If the attribute value is >0 it defines the time - in seconds - after which the count of consecutive password failures is reset even if no successful bind attempt (authentication) has occurred.

pwdGraceAuthNLimit

pwdGraceAuthNLimit number

# example
pwdGraceAuthNLimit 5

This attribute controls whether to allow any further bind operation after a password has expired - frequently referred to as a grace period. If the value of this attribute is 0 (the default) then any attempt to bind using an expired password will be rejected. If the value is >0 then it defines the number of times a user is allowed to successfully bind using an expired password. If this limit is reached and the password has not been changed then all subsequent bind operations will be rejected.

pwdInHistory

pwdInHistory no-of-passwords

# example
pwdInHistory 5

This attribute controls the number of passwords that are maintained in a list of previously used passwords - a password history - for the account. When a user changes their password the new password is checked against the history list and rejected if present. If the password is accepted - it does not appear in the password history - it is added to the history and the oldest item is deleted. The net effect is to force the user to generate a previously unused password - or at least unused up the the history limit. All passwords in the history are stored using the default hash method for the server. If the value is 0 (the default) this means that no password history is maintained. The only check carried out in this case is that the new password is not the same as the current password.

pwdLockout

pwdLockout TRUE | FALSE

# example
pwdLockout TRUE

This attribute controls the action taken when an account has had more consecutive failed bind attempts with invalid passwords than is defined by pwdMaxFailure. If the value of this attribute is TRUE (the default) then the account is locked - no further bind attempts are allowed until the account is unlocked by an administrator (see Unlocking an Account for operational details). If the value is FALSE the account is not locked and any number of consecutive invalid password attempts are allowed.

pwdLockoutDuration

pwdLockoutDuration number-of-seconds

# example
pwdLockoutDuration 0

This attribute controls how long an account remains locked and is only relevant if pwdLockout is TRUE. If the value of this attribute is 0 (the default) the user will not be able to access the account until the account is unlocked by an administrator (see Unlocking an Account for operational details). If the attribute value is >0 then it contains the time - in seconds - the account remains locked. When this period expires the account is automatically unlocked.

pwdMaxAge

pwdMaxAge time-in-seconds

# example
pwdMaxAge 2592000

This is one these calculator-requiring attributes. It defines the maximum time - in seconds - a password is valid - after which it is deemed to be no longer usable and any bind operations attempted with the expired password will be treated as invalid. The horrendous value in the example is 30 days, meaning passwords must be changed every 30 days. The default value is 0 which means that passwords never expire.

pwdMaxFailure

pwdMaxFailure number-of-attempts

# example
pwdMaxFailure 5

This attribute controls how many consecutive password failures are allowed before the action defined by pwdLockout is taken. If the attribute value is 0 (the default) an unlimited number of consecutive password failure attempts are allowed. If the attribute value is >0 this defines the maximum number of consecutive failed password attempts allowed before the action defined by pwdLockout is taken. Any successful bind operation resets the count.

pwdMaxTotalAttempts

pwdMaxTotalAttempts number-of-attempts

# example
pwdMaxTotalAttempts 50

This attribute controls how many consecutive password failures, including repeat password attempts, are allowed before the action defined by pwdLockout is taken. If the attribute value is 0 (the default) no repeat password checking is performed. If the attribute value is >0 (positive number) this defines the maximum number of consecutive failed password attempts (the sum of repeat and unique failed attempts) before the action defined by pwdLockout is taken. If the attribute value is -1 a unlimited number of repeat password attempts are allowed. In all cases number of unique failed password attempts allowed is controlled by pwdMaxFailure.

</MODIFIED>

pwdMinAge

pwdMinAge time-in-seconds

# example
pwdMinAge 3600

This attribute controls the minimum time in seconds between password changes. In the example above the password may only be modified every hour (3600 seconds). Attempts to make changes prior to this will be rejected. The default value is 0 which allows the password to be changed at any time following the last change.

pwdMinLength

pwdMinLength bytes

# example
pwdMinLength 6

This attribute controls whether minimum password length checks will be enforced by the server. If the value is 0 (the default) then no password length checks are enforced. If the value is > 0 then it defines the minimum length of the user supplied password. Passwords shorter than this value will be rejected. If the supplied password is hashed no length checks can be carried out and the default actions are defined by pwdCheckQuality - if 0 (default) or 1 accept, if 2 reject).

pwdMustChange

pwdMustChange TRUE | FALSE

# example
pwdMustChange TRUE

This attribute controls whether the user must change their password after an account is reset by an administrator following an account lockout and is only relevant if pwdLockout is TRUE. If the attribute value is FALSE (the default) then the user does not have to change their password when the account is unlocked. If the attribute value is TRUE then the user MUST change their password when the account is unlocked. If pwdReset is used to unlock an account its value will override this attribute.

pwdSafeModify

pwdSafeModify TRUE | FALSE

# example
pwdSafeModify TRUE

This attribute controls whether a user must send the current password during a password modification operation. If the attribute value is FALSE (the default) then the user does not have to send their current password. If the attribute value is TRUE the user MUST send their current password when modifying the password value.

Operational Attributes

The ppolicy module uses a number of operational attributes in the user entry to indicate account status and to allow the administrator to unlock the account following a lockout condition.

pwdAccountLockedTime

pwdAccountLockedTime account-locked-time

This attribute indicates the time the account was locked and will only appear if pwdLockout is TRUE. If this attribute is deleted by an administrator then the account is unlocked and the existing password (assuming it has not expired) can be used. See Unlocking an Account.

pwdChangedTime

pwdChangedTime last-password-change-time

Read only attribute. This attribute indicates the last time the password for the entry was changed.

pwdFailureTime

pwdFailureTime invalid-password-attempt-time

Read only attribute. This multi-value attribute indicates the time of each failed password attempt

pwdGraceUseTime

pwdGraceUseTime grace-auth-time

Read only attribute. This multi-value attribute contains the time of each succesful bind (authentication) after the password has expired and is only present if pwdGraceAuthNLimit is present and has a value >0.

pwdHistory

pwdHistory hashed-user-password

Read only attribute. This multi-value attribute contains the hashed value of previously used passwords (including the current password) up the the limit defined by pwdInHistory. It is only present if pwdInHistory is present and has a value >0.

pwdPolicySubentry

pwdPolicySubentry DN

# example
pwdPolicySubentry "cn=adminusers,ou=ppolicies,dc=example,dc=com"

This attribute controls whether a user entry invokes a unique, or the default, password policy (pwdPolicy ObjectClass). If password policy checking is active for this DIT (overlay ppolicy is defined) and this attribute does not exist then the default policy defined by ppolicy_default is used for the entry. If ppolicy_default is not present then no password policy is applied to this entry. If this attribute is present then the password policy (pwdPolicy) defined by the DN is used for the entry. Note: The above assumes that the configuration entry overlay ppolicy has been defined for the DIT. If this is not the case then no password checking is invoked for the DIT irrespective of the value of this attribute.

pwdReset

pwdReset TRUE | FALSE

#example 
pwdReset TRUE

This attribute may be used by the administrator to reset the account. If TRUE the user must change their password prior to the next bind attempt. If FALSE then the account is unlocked but the user does not have to change their password. The value of this attribute overrides the setting of pwdMustChange.

pwdUniqueAttempts

pwdUniqueAttempts hashed-invalid-password

Read only attribute. This multi-value attribute contains the hashed value and the time of each unique failed password attempt. This entry will only appear if pwdMaxTotalAttempts is present and non-zero (non 0). The maximum number of attributes is defined by pwdMaxFailure. The entry will also contain a count of uses of each invalid password if pwdMaxTotalAttempts is >0.

</MODIFIED>

Unlocking an Account

If the user account is locked (pwdLockout is TRUE) then it may be unlocked by an administrator using either of the following procedures:

Delete the operational attribute pwdAccountLockedTime. This procedure allows the user to continue to use the current password and is only effective if the password has not expired.
Add the operational attribute pwdReset with a value of either TRUE or FALSE. FALSE is only effective if the password has not expired and has the same effect as deleting pwdAccountLockedTime.

Configuration Examples

To illustrate the use of ppolicy two scenarios are covered. The first uses a single default policy for all user entries. The second uses an account specific policy.

Default Only Password Policy

The default pwdPolicy is created and added to the DIT using an LDIF fragment as shown below:

# add default policy to DIT
# attributes preceded with # indicate the defaults and
# can be omitted
# passwords must be reset every 30 days, 
# have a minimum length of 6 and users will
# get a expiry warning starting 1 hour before
# expiry, when the consecutive fail attempts exceed 5
# the count will be locked and can only be reset by an 
# administrator, users do not need to supply the old 
# password when changing
dn: cn=default,ou=pwpolicies,dc=example,dc=com
objectClass: pwdPolicy
cn: default
pwdMaxAge: 2592000
pwdExpireWarning: 3600
#pwdInHistory: 0
#pwdCheckQuality: 0
pwdMaxFailure: 5
pwdLockout: TRUE
#pwdLockoutDuration: 0
#pwdGraceAuthNLimit: 0
#pwdFailureCountInterval: 0
pwdMustChange: TRUE
pwdMinLength: 6
#pwdAllowUserChange: TRUE
pwdSafeModify: FALSE

The ppolicy overlay is invoked for the DIT by the following additions to the configuration file (or using the equivalent olc values if cn=config is active):

...
# include the ppolicy schema
include ppolicy.schema
...
# required if the overlay is built dynamically
loadmodule ppolicy.la
# OR
loadmodule ppolicy.so
...
database bdb
suffix "dc=example,dc=com"
...
# invokes password policies for this DIT only
overlay ppolicy
# define the default policy
ppolicy_default "cn=default,cn=pwpolicies,dc=example,dc=com"
# optional ppolicy directives
...
# other overlay directives or 
# next database directive

Password policy is turned on for all accounts in this DIT. No other actions are required.

Default and User Specific Password Policy

The default and user specific pwdPolicy is created and added to the DIT using an LDIF fragment as shown below:

# add default policy to DIT
# attributes preceded with # indicate the defaults and
# can be omitted
# passwords must be reset every 30 days, 
# have a minimum length of 6 and users will
# get a expiry warning starting 1 hour before
# expiry, when the consecutive fail attempts exceed 5
# the count will be locked and can only be reset by an 
# administrator, users do not need to supply the old 
# password when changing
dn: cn=default,ou=pwpolicies,dc=example,dc=com
objectClass: pwdPolicy
cn: default
pwdMaxAge: 2592000
pwdExpireWarning: 3600
#pwdInHistory: 0
#pwdCheckQuality: 0
pwdMaxFailure: 5
pwdLockout: TRUE
#pwdLockoutDuration: 0
#pwdGraceAuthNLimit: 0
#pwdFailureCountInterval: 0
pwdMustChange: TRUE
pwdMinLength: 6
#pwdAllowUserChange: TRUE
pwdSafeModify: FALSE

# add a user specific policy to DIT
# attributes preceded with # indicate the defaults and
# can be omitted
# passwords must be reset every 7 days, 
# have a minimum length of 10 and users will not
# get a expiry warning before
# expiry, when the consecutive fail attempts exceed 3
# the count will be locked and can only be reset by an 
# administrator, users need to supply the old 
# password when changing
dn: cn=user,ou=pwpolicies,dc=example,dc=com
objectClass: pwdPolicy
cn: user
pwdMaxAge: 604800
# pwdExpireWarning: 0
pwdInHistory: 3
#pwdCheckQuality: 0
pwdMaxFailure: 3
pwdLockout: TRUE
#pwdLockoutDuration: 0
#pwdGraceAuthNLimit: 0
#pwdFailureCountInterval: 0
pwdMustChange: TRUE
pwdMinLength: 10
#pwdAllowUserChange: TRUE
pwdSafeModify: TRUE

The ppolicy overlay is invoked for the DIT by the following additions to the configuration file (or using the equivalent olc values if cn=config is active):

...
# include the ppolicy schema
include ppolicy.schema
...
# required if the overlay is built dynamically
loadmodule ppolicy.la
# OR
loadmodule ppolicy.so
...
database bdb
suffix "dc=example,dc=com"
...
# invokes password policies for this DIT only
overlay ppolicy
# define the default policy
ppolicy_default "cn=default,cn=pwpolicies,dc=example,dc=com"
# optional ppolicy directives
...
# other overlay directives or 
# next database directive

Finally the account entry for the user(s) to whom this policy applies are modified to point to the specific policy using the following LDIF fragment:

# point the users entry to the specific policy
dn: cn=John Smith,ou=people,dc=example,dc=com
changetype: modify
add: pwdPolicySubentry
pwdPolicySubentry: "cn=user,ou=pwpolicies,dc=example,dc=com"

Password policy is turned on for all accounts in this DIT except John Smith who uses the policy defined at "cn=user,ou=pwpolicy,dc=example,dc=com". No other actions are required.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.