Single Use Tokens 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 Single Use Tokens Extended Operation Handler provides support for the deliver single-use token extended operation, which can cause the server to generate a single-use token value, store it in a user's entry, and deliver a message containing that token to the target user through some out-of-band mechanism (e.g., email or SMS). It also provides support for the consume single-use token extended operation, which can be used to confirm that the user has received the single-use token and remove it from the user's entry to prevent it from being reused.
A deliver single-use token extended request contains the following elements:
- The DN of the user for whom the single-use token is to be generated and delivered.
- A token ID string, which identifies the server component with which the token is associated. This is used to ensure that the server can support multiple outstanding single-use tokens for the same user for different purposes. Each component that may wish to generate single-use tokens should have a unique token ID.
- The length of time that the generated token should be considered valid.
- Information that should be included along with the single-use token value in the message that is to be delivered. Different messages can be used for delivery mechanisms that might impose significant constraints on the size of the message (e.g., SMS) and for those that may allow for longer messages.
- An optional list of delivery mechanisms that should be used to convey the message with the single-use token to the user. If this is provided, then the server will only attempt to use the listed mechanisms (and will attempt them in the order provided by the client). If this is not provided, then the server will automatically select which delivery mechanism(s) to attempt. 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.
- Flags that indicate whether to generate and deliver the single-use token if the user's account is not currently usable for various reasons, including if the user's password is expired, if the account is locked, if the account has been administratively disabled, or if the account has expired.
Once the server has retrieved the target user entry and verified that it should generate and deliver the single-use token for that user, it will select the set of delivery mechanisms to use to provide the single-use token to the end user. The server will select the OTP delivery mechanism to accomplish this using the following logic:
1. If the extended request received from the client includes a list of 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 single-use 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 single-use 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 single-use 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 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 single-use 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 single-use token to the user, then no further attempt will be made to deliver the token and an error result will be returned to the client.
The names of the delivery mechanisms that are available for 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 single-use 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. The get supported OTP delivery mechanisms extended operation may be used to determine which OTP delivery mechanisms are available within the server and which are expected to be applicable to a specified user.
Once the user receives the message containing the single-use token, the consume single-use token should be used to indicate to the server that the token has been received and to prevent it from being reused. The consume single-use token extended request contains the following elements: - The DN of the user to whom the single-use token was delivered.
- A token ID string, which identifies the server component with which the token is associated.
- The single-use token that was delivered to and received by the user.
When the server receives a consume single-use token request from a client, it will retrieve the target user's entry, confirm that it contains the provided single-use token with the given token ID, and confirm that the token has not yet expired. The token will then be removed from the user's entry to ensure that it cannot be reused.
Relations from This Component
The following components have a direct aggregation relation from Single Use Tokens 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 single-use token values to be delivered to the end user.
|
Default Value
| None
|
Allowed Values
| The DN of any Password Generator. If this Single Use Tokens 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-otp-delivery-mechanism
Description
| The set of delivery mechanisms that may be used to deliver single-use tokens to users in 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 Single Use Tokens 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
|
default-single-use-token-validity-duration
Description
| The default length of time that a single-use token will be considered valid by the server if the client doesn't specify a duration in the deliver single-use token request.
|
Default Value
| 5 minutes
|
Allowed Values
| A duration. Lower limit is 1 milliseconds.
|
Multi-Valued
| No
|
Required
| No
|
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 Single Use Tokens Extended Operation Handler:
dsconfig create-extended-operation-handler
--handler-name {name}
--type single-use-tokens
--set enabled:{propertyValue}
--set password-generator:{propertyValue}
--set default-otp-delivery-mechanism:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Extended Operation Handler:
dsconfig delete-extended-operation-handler
--handler-name {name}