Deliver OTP 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 OTP Extended Operation Handler provides a mechanism for generating and delivering a one-time password (OTP) to a user that may be used for authentication via the UNBOUNDID-DELIVERED-OTP SASL mechanism.
A deliver one-time password extended request contains the following elements:
- An authentication identity, which identifies the user to whom the one-time password should be delivered. This must have either the form "dn:" followed by the full distinguished name for the user, or "u:" followed by the username for the user.
- The static password for the user (e.g., as used for simple authentication or certain password-based SASL mechanisms, like PLAIN, CRAM-MD5, or DIGEST-MD5). Note that this password is not obscured in any way when it is included in the extended request, so it is strongly recommended that this request only be issued over a secure connection.
- An optional list of the names of the mechanisms that may be used to deliver the one-time password 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.
Once the server identifies the user indicated by the authentication identity (using the identity mapper specified in the configuration for this extended operation handler), it will verify that the provided static password is correct for that user, and that the user is allowed to authenticate to the server (i.e., that the account is not locked out, the user's password is not expired, etc.). The server will then use the password generator indicated in the extended operation handler configuration to generate a new value to use as the one-time password for the user. This value will be combined with a timestamp and stored in the ds-auth-delivered-otp operational attribute of the user's entry, and it will also be sent to the 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 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 password has been delivered successfully. If the extended request includes a list of delivery mechanisms, but none of them can be used to send the password to the target user, then no further attempt will be made to deliver the one-time password 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 password 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 one-time password, 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 one-time password 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 one-time password to the user, then no further attempt will be made to deliver the one-time password 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 one-time password 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 one-time password has been delivered, the user may authenticate with that password using the UNBOUNDID-DELIVERED-OTP SASL mechanism. See the documentation for that SASL mechanism handler for more information about using that SASL mechanism.
Relations from This Component
The following components have a direct aggregation relation from Deliver OTP 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
|
identity-mapper
Description
| The identity mapper that should be used to identify the user(s) targeted by the authentication identity contained in the extended request. This will only be used for "u:"-style authentication identities.
|
Default Value
| None
|
Allowed Values
| The DN of any Identity Mapper. If this Deliver OTP Extended Operation Handler is enabled, then the associated identity mapper must also be enabled.
|
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 one-time password values to be delivered to the end user.
|
Default Value
| None
|
Allowed Values
| The DN of any Password Generator. If this Deliver OTP 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 one-time passwords 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 Deliver OTP 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
|
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 OTP Extended Operation Handler:
dsconfig create-extended-operation-handler
--handler-name {name}
--type deliver-otp
--set enabled:{propertyValue}
--set identity-mapper:{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}