Deliver Password Reset Token Extended Operation Handler
Note: this component is designated "advanced", which means that objects of this type are not expected to be created or altered in most environments. If you believe that such a change is necessary, you may want to contact support in order to understand the potential impact of that change.
The Deliver Password Reset Token Extended Operation Handler provides a mechanism for generating and delivering a password reset token to a user that may be provided to the password modify extended operation in lieu of the user's current password in order to specify a new password.
A deliver password reset token extended request contains the following elements:
- The DN of the user to whom the password reset token should be delivered.
- An optional list of the names of the mechanisms that may be used to deliver the password reset token to the user. The get supported OTP delivery mechanisms extended operation can be used to determine which one-time password delivery mechanisms are available in the server and which of those are expected to be supported for a particular user.
This extended operation is intended to be used by applications that provide their own mechanism for determining the identity of the target user. This may include simply requesting a unique identifier (e.g., a username or email address), but may also include additional verification like requesting additional information including in the user's account or answering one or more security questions. Once the application has identified the user and performed any necessary verification of that identity, it may send the deliver password reset token request to the server. The server will then use the configured password generator to create a new value to use as the password reset token for the user, will store that value in the ds-auth-password-reset-token operational attribute of the user's entry (in conjunction with a timestamp that indicates when the token will no longer be considered valid), and will provide that token to the end user through some out-of-band mechanism using an OTP delivery mechanism. The server will select the OTP delivery mechanism to accomplish this based on the following logic:
1. If the extended request received from the client includes a list of preferred delivery mechanisms, then only those mechanisms may be used. The server will try each mechanism in the order specified by the client until one of them indicates that the token has been delivered successfully. If the extended request includes a list of delivery mechanisms, but none of them can be used to send the token to the target user, then no further attempt will be made to deliver the password reset token and an error result will be returned to the client.
2. If the extended request does not include a list of delivery mechanisms, then the server will attempt to retrieve the ds-auth-preferred-otp-delivery-mechanism operational attribute from the user's entry. If this attribute exists in the user's entry, then the server will try each of those values, in the order they are listed in the user's entry, until one of them is able to successfully deliver the token to the user. If this operational attribute does not exist in the user's entry, or if none of the delivery mechanisms specified in that attribute may be used to deliver the password reset token, then processing will fall through to the third option below.
3. If the extended request does not include a list of delivery mechanisms and the server cannot deliver the password reset token using a mechanism specified in the ds-auth-preferred-otp-delivery-mechanism operational attribute in the user's entry, then the server will try the mechanisms specified in the default-otp-delivery-mechanism property of this extended operation handler, in the order in which they are listed (skipping any mechanisms that have already been tried because they were present in the set of ds-auth-preferred-otp-delivery-mechanism values). If none of these mechanisms is able to successfully deliver the token to the user, then no further attempt will be made to deliver the password reset token and an error result will be returned to the client.
The names of the delivery mechanisms that are available for use will be listed in the ds-supported-otp-delivery-mechanism operational attribute of the server's root DSE. These names correspond to the names of the configuration objects for the OTP delivery mechanisms that are defined and enabled in the server configuration.
Note that not all delivery mechanisms may be appropriate for all users. For example, a delivery mechanism that sends the password reset token to a user via e-mail would not be able to deliver a password to any user whose entry does not contain an e-mail address.
Once the password reset token has been delivered, the user may use that token as the current password in the password modify extended request, and must specify a new password. The server will not permit the new password to be empty (which normally indicates that a password generator should be used to create a new password) if a password reset token is used.
The ability to use password reset tokens is dependent on the password policy configuration for the target user. The allowed-password-reset-token-use-condition property of the user's password policy indicates the conditions under which the server will allow the user to obtain and utilize a password reset token. It can be disabled altogether (which may be desirable for administrators or other users with elevated privileges), or you can specify the conditions under which a token may be used and generated (e.g., whether to permit it for users with expired passwords or locked accounts).
Parent Component
The Deliver Password Reset Token Extended Operation Handler component inherits from the Extended Operation Handler
Relations from This Component
The following components have a direct aggregation relation from Deliver Password Reset Token Extended Operation Handlers:
Properties
The properties supported by this managed object are as follows:
Basic Properties
description
Description
| A description for this Extended Operation Handler
|
Default Value
| None
|
Allowed Values
| A string
|
Multi-Valued
| No
|
Required
| No
|
Admin Action Required
| None. Modification requires no further action
|
enabled
Description
| Indicates whether the Extended Operation Handler is enabled (that is, whether the types of extended operations are allowed in the server).
|
Default Value
| None
|
Allowed Values
| true
false
|
Multi-Valued
| No
|
Required
| Yes
|
Admin Action Required
| None. Modification requires no further action
|
password-generator
Description
| The password generator that will be used to create the password reset token values to be delivered to the end user.
|
Default Value
| None
|
Allowed Values
| The DN of any Password Generator. If this Deliver Password Reset Token Extended Operation Handler is enabled, then the associated password generator must also be enabled.
|
Multi-Valued
| No
|
Required
| Yes
|
Admin Action Required
| None. Modification requires no further action
|
default-token-delivery-mechanism
Description
| The set of delivery mechanisms that may be used to deliver password reset tokens to users for requests that do not specify one or more preferred delivery mechanisms.
|
Default Value
| None
|
Allowed Values
| The DN of any OTP Delivery Mechanism. If this Deliver Password Reset Token Extended Operation Handler is enabled, then the associated one-time password delivery mechanism must also be enabled.
|
Multi-Valued
| Yes
|
Required
| Yes
|
Admin Action Required
| None. Modification requires no further action
|
password-reset-token-validity-duration
Description
| The maximum length of time that a password reset token should be considered valid.
|
Default Value
| 5 minutes
|
Allowed Values
| A duration. Lower limit is 1 milliseconds.
|
Multi-Valued
| No
|
Required
| Yes
|
Admin Action Required
| None. Modification requires no further action
|
dsconfig Usage
To list the configured Extended Operation Handlers:
dsconfig list-extended-operation-handlers
[--property {propertyName}] ...
To view the configuration for an existing Extended Operation Handler:
dsconfig get-extended-operation-handler-prop
--handler-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Extended Operation Handler:
dsconfig set-extended-operation-handler-prop
--handler-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Deliver Password Reset Token Extended Operation Handler:
dsconfig create-extended-operation-handler
--handler-name {name}
--type deliver-password-reset-token
--set enabled:{propertyValue}
--set password-generator:{propertyValue}
--set default-token-delivery-mechanism:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Extended Operation Handler:
dsconfig delete-extended-operation-handler
--handler-name {name}