Package com.unboundid.ldap.sdk.unboundidds.extensions

Class DeliverOneTimePasswordExtendedRequest

java.lang.Object
com.unboundid.ldap.sdk.LDAPRequest
com.unboundid.ldap.sdk.ExtendedRequest
com.unboundid.ldap.sdk.unboundidds.extensions.DeliverOneTimePasswordExtendedRequest
All Implemented Interfaces:
ProtocolOp, ReadOnlyLDAPRequest, Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class DeliverOneTimePasswordExtendedRequest extends ExtendedRequest
This class provides an implementation of an extended request that may be used to request that the Directory Server deliver a one-time password to an end user that they may use to authenticate via an UnboundIDDeliveredOTPBindRequest.
NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

Notes on the recommended use of this extended request:
  • Whenever possible, the user's static password should be provided. However, the server will allow the static password to be omitted if the authentication ID included in the request matches the authorization identity of the extended operation (either because that user is already authenticated on the connection, or because the request includes a proxied authorization or intermediate client control specifying that identity). In that case, the operation will be able to act as a "step-up" mechanism, providing further proof of the identity of an already-authenticated client rather than performing the complete authentication process.
  • The request offers two mechanisms for indicating which delivery mechanism(s) should be considered: an option to specify just the delivery mechanism names, and an option to specify the names along with recipient IDs. At most one of these elements must be present in the request. If neither is present, the server will attempt to determine which delivery mechanisms and recipient IDs should be used. If the set of preferred delivery mechanisms includes multiple items, the server will attempt them in the order provided until it is able to successfully deliver the message. The server will not attempt to use any other delivery mechanisms that may be configured if the request includes a list of preferred delivery mechanisms.
  • Although the message elements (message subject, and full and compact text before and after the OTP) are optional, it is recommended that they be supplied by the client. The server will provide a generic message if no message elements are included in the request.


The OID for this extended request is 1.3.6.1.4.1.30221.2.6.24. It must have a value, and that value should have the following encoding: 

   DeliverOTPRequest ::= SEQUENCE {
        authenticationID             [0] OCTET STRING,
        staticPassword               [1] OCTET STRING OPTIONAL,
        preferredMechNames           [2] SEQUENCE OF OCTET STRING OPTIONAL,
        preferredMechNamesAndIDs     [3] SEQUENCE OF SEQUENCE,
             mechanismName     OCTET STRING,
             recipientID       OCTET STRING OPTIONAL } OPTIONAL,
        messageSubject               [4] OCTET STRING OPTIONAL,
        fullTextBeforeOTP            [5] OCTET STRING OPTIONAL,
        fullTextAfterOTP             [6] OCTET STRING OPTIONAL,
        compactTextBeforeOTP         [7] OCTET STRING OPTIONAL,
        compactTextAfterOTP          [8] OCTET STRING OPTIONAL,
        ... }
See Also:

  • Field Details

  • Constructor Details

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable String staticPassword, @Nullable String... preferredDeliveryMechanisms)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      preferredDeliveryMechanisms - The names of the preferred delivery mechanisms for the one-time password. It may be null or empty if the server should select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable byte[] staticPassword, @Nullable String... preferredDeliveryMechanisms)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      preferredDeliveryMechanisms - The names of the preferred delivery mechanisms for the one-time password. It may be null or empty if the server should select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable String staticPassword, @Nullable List<String> preferredDeliveryMechanisms, @Nullable Control... controls)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      preferredDeliveryMechanisms - The names of the preferred delivery mechanisms for the one-time password. It may be null or empty if the server should select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable byte[] staticPassword, @Nullable List<String> preferredDeliveryMechanisms, @Nullable Control... controls)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      preferredDeliveryMechanisms - The names of the preferred delivery mechanisms for the one-time password. It may be null or empty if the server should select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable String staticPassword, @Nullable String messageSubject, @Nullable String fullTextBeforeOTP, @Nullable String fullTextAfterOTP, @Nullable String compactTextBeforeOTP, @Nullable String compactTextAfterOTP, @Nullable List<ObjectPair<String,String>> preferredDeliveryMechanisms, @Nullable Control... controls)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      messageSubject - The text (if any) that should be used as the message subject if the delivery mechanism accepts a subject. This may be null if no subject is required or a subject should be automatically generated.
      fullTextBeforeOTP - The text (if any) that should appear before the generated one-time password in the message delivered to the user via a delivery mechanism that does not impose significant constraints on message size. This may be null if no text is required before the one-time password.
      fullTextAfterOTP - The text (if any) that should appear after the one-time password in the message delivered to the user via a delivery mechanism that does not impose significant constraints on message size. This may be null if no text is required after the one-time password.
      compactTextBeforeOTP - The text (if any) that should appear before the generated one-time password in the message delivered to the user via a delivery mechanism that imposes significant constraints on message size. This may be null if no text is required before the one-time password.
      compactTextAfterOTP - The text (if any) that should appear after the generated one-time password in the message delivered to the user via a delivery mechanism that imposes significant constraints on message size. This may be null if no text is required after the one-time password.
      preferredDeliveryMechanisms - An optional ordered list of preferred delivery mechanisms that should be used to deliver the one-time password to the user. It may be null or empty to allow the server to select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list. Each ObjectPair item must have a non-null value for the first element, which is the name of the target delivery mechanism. It may optionally have a non-null value for the second element, which is a recipient ID to use for that mechanism (e.g., the target mobile phone number for SMS delivery, an email address for email delivery, etc.). If no recipient ID is provided for a mechanism, then the server will attempt to select a value for the user.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull String authenticationID, @Nullable byte[] staticPassword, @Nullable String messageSubject, @Nullable String fullTextBeforeOTP, @Nullable String fullTextAfterOTP, @Nullable String compactTextBeforeOTP, @Nullable String compactTextAfterOTP, @Nullable List<ObjectPair<String,String>> preferredDeliveryMechanisms, @Nullable Control... controls)
      Creates a new deliver one-time password extended request with the provided information.
      Parameters:
      authenticationID - The authentication ID for the user to whom the one-time password should be delivered. It must not be null.
      staticPassword - The static password for the user to whom the one-time password should be delivered. It may be null if this request is intended to be used to step-up an existing authentication rather than perform a new authentication (in which case the provided authentication ID must match the operation's authorization ID).
      messageSubject - The text (if any) that should be used as the message subject if the delivery mechanism accepts a subject. This may be null if no subject is required or a subject should be automatically generated.
      fullTextBeforeOTP - The text (if any) that should appear before the generated one-time password in the message delivered to the user via a delivery mechanism that does not impose significant constraints on message size. This may be null if no text is required before the one-time password.
      fullTextAfterOTP - The text (if any) that should appear after the one-time password in the message delivered to the user via a delivery mechanism that does not impose significant constraints on message size. This may be null if no text is required after the one-time password.
      compactTextBeforeOTP - The text (if any) that should appear before the generated one-time password in the message delivered to the user via a delivery mechanism that imposes significant constraints on message size. This may be null if no text is required before the one-time password.
      compactTextAfterOTP - The text (if any) that should appear after the generated one-time password in the message delivered to the user via a delivery mechanism that imposes significant constraints on message size. This may be null if no text is required after the one-time password.
      preferredDeliveryMechanisms - An optional ordered list of preferred delivery mechanisms that should be used to deliver the one-time password to the user. It may be null or empty to allow the server to select an appropriate delivery mechanism. If it is non-null and non-empty, then only the listed mechanisms will be considered for use, even if the server supports alternate mechanisms not included in this list. Each ObjectPair item must have a non-null value for the first element, which is the name of the target delivery mechanism. It may optionally have a non-null value for the second element, which is a recipient ID to use for that mechanism (e.g., the target mobile phone number for SMS delivery, an email address for email delivery, etc.). If no recipient ID is provided for a mechanism, then the server will attempt to select a value for the user.
      controls - The set of controls to include in the request. It may be null or empty if no controls should be included.

    • DeliverOneTimePasswordExtendedRequest

      public DeliverOneTimePasswordExtendedRequest(@NotNull ExtendedRequest request) throws LDAPException
      Creates a new deliver one-time password extended request from the information contained in the provided generic extended request.
      Parameters:
      request - The generic extended request to be decoded as a deliver one-time password extended request.
      Throws:
      LDAPException - If a problem is encountered while attempting to decode the provided generic extended request as a deliver one-time password extended request.

  • Method Details

    • getAuthenticationID

      @NotNull public String getAuthenticationID()
      Retrieves the authentication ID for the user to whom the one-time password should be delivered.
      Returns:
      The authentication ID for the user to whom the one-time password should be delivered.

    • getStaticPassword

      @Nullable public ASN1OctetString getStaticPassword()
      Retrieves the static password for the user to whom the one-time password should be delivered. The returned password may be null if no
      Returns:
      The static password for the user to whom the one-time password should be delivered, or null if no static password should be included in the request.

    • getPreferredDeliveryMechanisms

      @Nullable public List<String> getPreferredDeliveryMechanisms()
      Retrieves an ordered list of the names of the preferred delivery mechanisms for the one-time password, if provided.
      Returns:
      An ordered list of the names of the preferred delivery mechanisms for the one-time password, or null if this was not provided.

    • getPreferredDeliveryMechanismNamesAndIDs

      @NotNull public List<ObjectPair<String,String>> getPreferredDeliveryMechanismNamesAndIDs()
      Retrieves an ordered list of the preferred delivery mechanisms that should be used to provide the one-time password to the user, optionally paired with a mechanism-specific recipient ID (e.g., a mobile phone number for SMS delivery, or an email address for email delivery) that can be used in the delivery. If this list is non-empty, then the server will use the first mechanism in the list that the server supports and is available for the target user, and the server will only consider mechanisms in the provided list even if the server supports alternate mechanisms that are not included. If this list is empty, then the server will attempt to select an appropriate delivery mechanism for the user.
      Returns:
      An ordered list of the preferred delivery mechanisms for the one-time password, or an empty list if none were provided.

    • getMessageSubject

      @Nullable public String getMessageSubject()
      Retrieves the text (if any) that should be used as the message subject for delivery mechanisms that can make use of a subject.
      Returns:
      The text that should be used as the message subject for delivery mechanisms that can make use of a subject, or null if no subject should be used, or if the delivery mechanism should attempt to automatically determine a subject.

    • getFullTextBeforeOTP

      @Nullable public String getFullTextBeforeOTP()
      Retrieves the text (if any) that should appear before the one-time password in the message delivered to the user via a mechanism that does not impose significant constraints on message size.
      Returns:
      The text that should appear before the one-time password in the message delivered to the user via a mechanism that does not impose significant constraints on message size, or null if there should not be any text before the one-time password.

    • getFullTextAfterOTP

      @Nullable public String getFullTextAfterOTP()
      Retrieves the text (if any) that should appear after the one-time password in the message delivered to the user via a mechanism that does not impose significant constraints on message size.
      Returns:
      The text that should appear after the one-time password in the message delivered to the user via a mechanism that does not impose significant constraints on message size, or null if there should not be any text after the one-time password.

    • getCompactTextBeforeOTP

      @Nullable public String getCompactTextBeforeOTP()
      Retrieves the text (if any) that should appear before the one-time password in the message delivered to the user via a mechanism that imposes significant constraints on message size.
      Returns:
      The text that should appear before the one-time password in the message delivered to the user via a mechanism that imposes significant constraints on message size, or null if there should not be any text before the one-time password.

    • getCompactTextAfterOTP

      @Nullable public String getCompactTextAfterOTP()
      Retrieves the text (if any) that should appear after the one-time password in the message delivered to the user via a mechanism that imposes significant constraints on message size.
      Returns:
      The text that should appear after the one-time password in the message delivered to the user via a mechanism that imposes significant constraints on message size, or null if there should not be any text after the one-time password.

    • process

      @NotNull public DeliverOneTimePasswordExtendedResult process(@NotNull LDAPConnection connection, int depth) throws LDAPException
      Sends this extended request to the directory server over the provided connection and returns the associated response.
      Overrides:
      process in class ExtendedRequest
      Parameters:
      connection - The connection to use to communicate with the directory server.
      depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
      Returns:
      An LDAP result object that provides information about the result of the extended operation processing.
      Throws:
      LDAPException - If a problem occurs while sending the request or reading the response.

    • duplicate

      @NotNull public DeliverOneTimePasswordExtendedRequest duplicate()
      Creates a new instance of this LDAP request that may be modified without impacting this request.. Subclasses should override this method to return a duplicate of the appropriate type..
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Overrides:
      duplicate in class ExtendedRequest
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • duplicate

      @NotNull public DeliverOneTimePasswordExtendedRequest duplicate(@Nullable Control[] controls)
      Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.. Subclasses should override this method to return a duplicate of the appropriate type..
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Overrides:
      duplicate in class ExtendedRequest
      Parameters:
      controls - The set of controls to include in the duplicate request.
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • getExtendedRequestName

      @NotNull public String getExtendedRequestName()
      Retrieves the user-friendly name for the extended request, if available. If no user-friendly name has been defined, then the OID will be returned.
      Overrides:
      getExtendedRequestName in class ExtendedRequest
      Returns:
      The user-friendly name for this extended request, or the OID if no user-friendly name is available.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this request to the provided buffer.
      Specified by:
      toString in interface ProtocolOp
      Specified by:
      toString in interface ReadOnlyLDAPRequest
      Overrides:
      toString in class ExtendedRequest
      Parameters:
      buffer - The buffer to which to append a string representation of this request.