Password reset tokens

If a user loses access to their account for some reason, such as if they forget their password or let it expire, then they must have their password reset by an administrator to regain access to it.

This can be costly for the organization because they might have to employ additional help desk staff, and it can be frustrating for users who might have to wait on someone to become available to help them.

Many organizations have attempted to deal with this by automating the password reset process: their application can provide an “I forgot my password” link option that identifies the user and sends them a new password that can be used to authenticate. PingDirectory server provides support for password reset tokens that can be used to provide much of the heavy lifting.

Much like delivered one-time passwords, a password reset token is a single-use password that is generated by the server and delivered to the user through an out-of-band mechanism like email or SMS. However, rather than allowing the user to authenticate, a password reset token can only be used in the current password field of a password modify extended request so that they can choose a new password.

After an application has obtained whatever it considers sufficient evidence of the user’s identity, such as by asking them for their username, email address, or phone number, it can use the deliver password reset token extended request to have the server generate a single-use password reset token and deliver it to the user through some out-of-band mechanism, and then it can allow the user to enter that token and their desired new password to send a password modify extended request to actually change the password.

The following password policy configuration property can be used to indicate the conditions under which a password reset token can be used:

allowed-password-reset-token-use-condition

The set of conditions under which a password reset token can be used. Allowed values include:

account-usable — Indicates that a password reset token can be used if the user’s account is in a usable state and would permit them to authenticate if they provided the correct credentials.
account-locked-due-to-failures — Indicates that a password reset token can be used to recover access to an account that has been locked after too many failed authentication attempts.
account-locked-due-to-idle-time-limit — Indicates that a password reset token can be used to recover access to an account that has been locked because it has been too long since the user last authenticated.
account-locked-due-to-admin-reset-timeout — Indicates that a password reset token can be used to recover access to an account that has been locked because they failed to choose a new password in a timely manner after an administrative password reset.
account-locked-due-to-validation-failure — Indicates that a password reset token can be used to recover access to an account that has been locked because their password failed to satisfy one or more bind password validators.
password-expired — Indicates that a password reset token can be used to recover access to an account with an expired password.

In addition to the password policy configuration, you must configure one or more one-time password delivery mechanisms in the server and create an instance of the deliver password reset token extended operation handler. The server offers out-of-box support delivering one-time passwords as SMS (using the Twilio service) or email messages, and the Server SDK provides support for developing custom delivery mechanisms.

The deliver password reset tokens extended operation handler offers the following configuration options:

password-generator: The password generator that should be used to create the password reset tokens.
default-token-delivery-mechanism: An ordered list of one-time password delivery mechanisms that should be tried if the extended request does not indicate which methods to attempt.
password-reset-token-validity-duration: The length of time that password reset tokens should be valid. They are valid for five minutes by default.

See the config/sample-dsconfig-batch-files/support-password-reset-tokens.dsconfig batch file for more information about configuring the server to support password reset tokens.