PingDirectory

Self password changes requiring current passwords

If you set the password-change-requires-current-password property to true, users must provide their current password when choosing a new password.

You can make these password changes using either a regular LDAP modify operation or a password modify extended operation.

For either method:

  • If the user doesn’t provide the correct current password, the server rejects the password modify request.

  • Password submissions must be in plain text, not encoded.

Refer to the config/sample-dsconfig-batch-files/require-current-password-when-changing-passwords.dsconfig batch file for more information about requiring users to provide their current password when performing self password changes.

LDAP modify operation

For a regular LDAP modify operation, the password change request must include modifications to delete the user’s current password and add their new password.

The following example uses the ldapmodify tool to change a user’s password:

$ bin/ldapmodify --hostname server.example.com --port 636 --useSSL \
--bindDN "cn=admin,dc=example,dc=com" --bindPassword <bindPassword>
dn: uid=jdoe,ou=People,dc=example,dc=com
changetype: modify
delete: userPassword
userPassword: <currentPassword>
-
add: userPassword
userPassword: <newPassword>
-

The following example uses the ldappasswordmodify tool with the --passwordChangeMethod ldap-modify argument to change a user’s password:

$ bin/ldappasswordmodify --hostname server.example.com --port 636 --useSSL \
  --bindDN "cn=admin,dc=example,dc=com" --bindPassword <bindPassword> \
  --userIdentity uid=jdoe,ou=People,dc=example,dc=com \
  --oldPassword <currentPassword> \
  --newPassword <newPassword> \
  --passwordChangeMethod ldap-modify

In the previous example, the ldappasswordmodify tool creates the required modifications for an LDAP modify operation.

Password modify extended operation

Alternatively, you can use the password modify extended operation, as described in RFC 3062, to update user passwords. There are two implementation methods:

  • For integration with a custom user account management application, use the UnboundID LDAP SDK for Java or another LDAP client API.

  • For the server CLI implementation, use the ldappasswordmodify tool with the --passwordChangeMethod password-modify-extended-operation argument.

Advantages over LDAP modify

The password modify extended operation has several advantages over a regular LDAP modify operation, including:

  • The user doesn’t have to know their full DN or the name of the attribute used to store their encoded password.

  • If the user’s password policy is configured with allow-expired-password-changes set to true, the user can reset their expired password.

    This type of request must include a value for userIdentity.

  • The server can automatically generate a new password for the target user.

  • A user can recover access to their account by providing a server-generated password reset token instead of their current password.

    You need to configure the server to support this operation.

Using the extended operation

The following table describes the attributes related to the password modify extended operation:

Attribute Description

userIdentity

Indicates the user whose password you are changing.

You can supply one of the following values:

  • The full DN of the user entry, with or without the dn: prefix

  • The string u:<user_value>, where <user_value> represents a value that the server can use to return a single user entry

    The server uses the identity mapper specified in the password modify extended operation handler to match the u value to the user entry. The server rejects the password modify request if a search returns more than one entry.

    By default, the extended operation handler’s identity mapper expects an exact match of either the uid or mail attributes. For example, if you provide the argument --userIdentity u:jdoe, the server searches using a filter of "(|(mail=jdoe)(uid=jdoe))".

If the connection making the password modify request is authenticated as the target user, you can omit userIdentity.

oldPassword

Indicates the current user password.

newPassword

Indicates the new user password.

To have the server generate a new password, omit newPassword from the request. The server uses the password generator defined in the password policy and returns the new password in the extended operation response.

The following example uses ldappasswordmodify to target a user by DN and set a new password:

$ bin/ldappasswordmodify --hostname ds.example.com --port 636 --useSSL \
  --bindDN "uid=admin,dc=example,dc=com" --bindPasswordFile admin-password.txt \
  --userIdentity uid=jdoe,ou=People,dc=example,dc=com \
  --oldPassword <currentPassword> \
  --newPasword <newPassword> \
  --passwordChangeMethod password-modify-extended-operation