Modifying a user’s password

There are two primary ways to change user passwords in the PingDirectory server:

Perform a modify operation which replaces the value of the password attribute (often userPassword).

In some configurations, when a user attempts to change their own password, it might be necessary to perform the modification by removing the password value and adding the desired new value to demonstrate that the user knows the current password value.

Use the password modify extended operation to change the password.

If a user is changing their own password, it might be necessary to provide the current password value. If the new password is acceptable to all configured password validators, the server provides a new password, or it can automatically generate a new password for the user.

Regardless of the mechanism used to change the password, all password values should be provided in cleartext rather than pre-encoded, and the user must have sufficient access control rights to update the password attribute in the target user’s entry.

When one user attempts to change the password for another user, the requester must have the password-reset privilege.

Validating a password

About this task

A new password is valid if it:

Meets the server’s password requirements
Is assigned a password policy
Passes user authentication

The server can display requirements for a password change to users. You can use the get-password-quality-requirements extended operation to retrieve information about the requirements, which you can forward to an end user before an attempted password change. You can also use these requirements to enable client-side validation so that any password problems can be identified before it is sent to the server. The password validation details request control can be included in an add or modify request, or a password modify extended request, to identify which validation requirements were not met by the password provided in the request.

You can configure password validators with user-friendly messages that describe the password requirements, and error messages that display if a proposed password does not satisfy those requirements. The server will automatically generate these messages if they are not provided in the configuration.

Password properties include the following:

bind-password-validator: Specifies which validators to invoke on bind.
password-validator: Specifies which validators to invoke during a password change.
minimum-bind-password-validation-frequency: Specifies how frequently the server should validate a user’s password during bind. Although you can specify that the password should be validated during each bind, it’s probably sufficient to only do so periodically (for example, once a week or once a month).
bind-password-validation-failure-action: Specifies the action the server should take if a user’s password fails validation. By default, the account is placed in a "must change password" state where the user is allowed to bind, but any other operations the user attempts fail until the user changes their password. Alternatively, the account can be locked so that the password needs to be reset by an administrator, or the server can generate an account status notification to recommend that the user choose a new password.

Steps

Create a password validator.

Password validator properties include validator-requirement-description and validator-failure messages.

Example:

The following is a simple password validator configuration that requires passwords to contain a minimum of five characters and lists custom validator messages.

$ dsconfig create-password-validator \
  --validator-name "Minimum 5 Characters Password Validator" \
  --type length-based --set enabled:true \
  --set "validator-requirement-description:The password must contain
         at least 5 characters." \
  --set "validator-failure-message:The password did not contain
         at least 5 characters." \
  --set min-password-length:5

To make the newly created password validator take effect, assign it to a password policy.

Example:

$ dsconfig set-password-policy-prop \
  --policy-name "Default Password Policy" \
  --set "password-validator:Minimum 5 Characters Password Validator"

To validate the password, authenticate as a user.

When a user authenticates, password validation processing is performed so that the server has access to the user’s clear-text password.

Retiring a password

About this task

An account password can be retired and rotated out of service instead of being invalidated. Retiring a password enables a new password to be assigned to an account while keeping the original password valid for a period of time to enable a transition. This is useful for application service accounts that require uninterrupted authentication with the server.

Steps

To enable password retirement, set the password-retirement-behavior and maximum-retired-password-age properties in the password policy configuration.
To manually retire an account password or purge a password that has been retired, run the ldapmodify and ldappasswordmodify tools with subcommands -- retireCurrentPassword and --purgeCurrentPassword.

To use these commands on an account, enable the password-retirement-behavior subcommand on the password policy that governs the account.

Changing a user’s password using the Modify operation

Steps

Use ldapmodify to change a user’s password by replacing the userPassword attribute.

Example:

$ bin/ldapmodify
dn: uid=user.0,ou=People,dc=example,dc=com
changetype: modify
replace: userPassword
userPassword: newpw

Changing a user’s password using the Password Modify extended operation

About this task

To request that the Password Modify extended operation be used to modify a user’s password:

Steps

Run the ldappasswordmodify tool.

Example:

$ bin/ldappasswordmodify --authzID dn:uid=jdoe,ou=People,dc=example,dc=com \
  --newPassword newpw

Using an automatically-generated password

Steps

To automatically generate a new password for a user, run the ldappasswordmodify tool.

Example:

$ bin/ldappasswordmodify --authzID "u:user.1"

Result:

The LDAP password modify operation was successful
Generated Password: fbi27oqy