com.unboundid.ldap.sdk.unboundidds.extensions

Class VerifyPasswordExtendedRequest

java.lang.Object

com.unboundid.ldap.sdk.LDAPRequest

com.unboundid.ldap.sdk.ExtendedRequest

com.unboundid.ldap.sdk.unboundidds.extensions.VerifyPasswordExtendedRequest

All Implemented Interfaces:

ProtocolOp, ReadOnlyLDAPRequest, java.io.Serializable

@NotMutable
 @ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class VerifyPasswordExtendedRequest
extends ExtendedRequest

This class provides an implementation of an extended request that may be sent to the Ping Identity Directory Server to determine whether a provided password is correct for a user without performing any other password policy processing for that user. The server will not make any attempt to determine whether the target user's account is in a usable state, nor will it update the user's password policy state information in any way as a result of the verification attempt.

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.

The extended request has an OID of 1.3.6.1.4.1.30221.2.6.72. The request must have a value, which will be encoded as a JSON object with the following fields:

• dn -- The DN of the user for whom to make the determination. This field is required to be present.
• password -- The password to verify for the user. This field is required to be present.

For security purposes, the server will only allow this request to be issued by a client with the necessary access control permission to do so, and who also has the permit-verify-password-request privilege. And by default, the server will only permit clients to issue verify password requests over a secure connection.

In response to a verify password extended request, the server will return a generic extended response with no OID or value. The result code included in that response should provide a suitable indication of the outcome, and in some cases, a diagnostic message may provide additional details about any issue that the server encountered. Some of the result codes that may be returned in response to a verify password extended request include:

• ResultCode.COMPARE_TRUE -- All processing completed successfully, and the provided password was correct for the target user.
• ResultCode.COMPARE_FALSE -- All processing completed successfully, but the provided password was not correct for the target user.
• ResultCode.NO_SUCH_OBJECT -- If the entry for the target user does not exist.
• ResultCode.INVALID_DN_SYNTAX -- If the target user DN cannot be parsed as a valid DN.
• ResultCode.INAPPROPRIATE_AUTHENTICATION -- If the target user does not have a password.
• ResultCode.INSUFFICIENT_ACCESS_RIGHTS -- If the requester does not have the necessary access control permission to issue the request, or if they do not have the permit-verify-password-request privilege.
• ResultCode.CONFIDENTIALITY_REQUIRED -- If the client is using an insecure connection, but the server requires secure communication for the request.
• ResultCode.OTHER -- If an internal error occurred while attempting to process the request.

Example

The following example demonstrates how to use the verify password extended request to determine whether a password is correct for a user without performing any password policy processing that would normally occur for a bind operation:

   public static boolean isPasswordValidForUser(
               final LDAPConnection connection,
               final String targetUserDN,
               final String passwordToVerify)
          throws LDAPException
   {
     final VerifyPasswordExtendedRequest verifyPasswordRequest =
          new VerifyPasswordExtendedRequest(targetUserDN, passwordToVerify);

     LDAPResult verifyPasswordResult;
     try
     {
       verifyPasswordResult =
            connection.processExtendedOperation(verifyPasswordRequest);
     }
     catch (final LDAPException e)
     {
       verifyPasswordResult = e.toLDAPResult();
     }

     final ResultCode resultCode = verifyPasswordResult.getResultCode();
     if (resultCode == ResultCode.COMPARE_TRUE)
     {
       // The provided password is correct for the target user.
       return true;
     }
     else if (resultCode == ResultCode.COMPARE_FALSE)
     {
       // The provided password is not correct for the target user.
       return false;
     }
     else
     {
       // An error occurred while trying to verify the password.
       throw new LDAPException(verifyPasswordResult);
     }
   }
 

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	REQUEST_FIELD_DN The name of the JSON field used to specify the DN of the user for whom to make the determination.
static java.lang.String	REQUEST_FIELD_PASSWORD The name of the JSON field used to specify the password for which to make the determination.
static java.lang.String	VERIFY_PASSWORD_REQUEST_OID The OID (1.3.6.1.4.1.30221.2.6.72) for the verify password extended request.

Fields inherited from class com.unboundid.ldap.sdk.ExtendedRequest

TYPE_EXTENDED_REQUEST_OID, TYPE_EXTENDED_REQUEST_VALUE

Constructor Summary

Constructors

Constructor and Description
VerifyPasswordExtendedRequest(ExtendedRequest extendedRequest) Attempts to decode the provided generic extended request as a verify password extended request.
VerifyPasswordExtendedRequest(java.lang.String dn, java.lang.String password, Control... controls) Creates a new verify password extended request with the provided information.

Method Summary

Modifier and Type	Method and Description
VerifyPasswordExtendedRequest	duplicate() Creates a new instance of this LDAP request that may be modified without impacting this request.
VerifyPasswordExtendedRequest	duplicate(Control[] controls) Creates a new instance of this LDAP request that may be modified without impacting this request.
java.lang.String	getDN() Retrieves the DN of the user for whom to verify the password.
java.lang.String	getExtendedRequestName() Retrieves the user-friendly name for the extended request, if available.
java.lang.String	getPassword() Retrieves the password to attempt to verify for the user.
void	toString(java.lang.StringBuilder buffer) Appends a string representation of this request to the provided buffer.

Methods inherited from class com.unboundid.ldap.sdk.ExtendedRequest

encodeProtocolOp, getLastMessageID, getOID, getOperationType, getProtocolOpType, getValue, hasValue, process, responseReceived, toCode, writeTo

Methods inherited from class com.unboundid.ldap.sdk.LDAPRequest

followReferrals, getControl, getControlList, getControls, getIntermediateResponseListener, getReferralConnector, getReferralConnectorInternal, getReferralDepth, getResponseTimeoutMillis, hasControl, hasControl, setFollowReferrals, setIntermediateResponseListener, setReferralConnector, setReferralDepth, setResponseTimeoutMillis, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERIFY_PASSWORD_REQUEST_OID

@NotNull
public static final java.lang.String VERIFY_PASSWORD_REQUEST_OID

The OID (1.3.6.1.4.1.30221.2.6.72) for the verify password extended request.

See Also:

Constant Field Values

REQUEST_FIELD_DN

@NotNull
public static final java.lang.String REQUEST_FIELD_DN

The name of the JSON field used to specify the DN of the user for whom to make the determination.

See Also:

Constant Field Values

REQUEST_FIELD_PASSWORD

@NotNull
public static final java.lang.String REQUEST_FIELD_PASSWORD

The name of the JSON field used to specify the password for which to make the determination.

See Also:

Constant Field Values

Constructor Detail

VerifyPasswordExtendedRequest

public VerifyPasswordExtendedRequest(@NotNull
                                     java.lang.String dn,
                                     @NotNull
                                     java.lang.String password,
                                     @Nullable
                                     Control... controls)

Creates a new verify password extended request with the provided information.

Parameters:

dn - The DN of the user for whom to make the determination. It must not be null or empty.

password - The password for which to make the determination. It must not be null or empty.

controls - An optional set of controls to include in the extended request. It may be null or empty if no controls are needed.

VerifyPasswordExtendedRequest

public VerifyPasswordExtendedRequest(@NotNull
                                     ExtendedRequest extendedRequest)
                              throws LDAPException

Attempts to decode the provided generic extended request as a verify password extended request.

Parameters:

extendedRequest - The generic extended request to decode as a verify password request. It must not be null.

Throws:

LDAPException - If the provided request cannot be decoded as a verify password request.

Method Detail

getDN

@NotNull
public java.lang.String getDN()

Retrieves the DN of the user for whom to verify the password.

Returns:

The DN of the user for whom to verify the password.

getPassword

@NotNull
public java.lang.String getPassword()

Retrieves the password to attempt to verify for the user.

Returns:

The password to attempt to verify for the user.

duplicate

@NotNull
public VerifyPasswordExtendedRequest 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 VerifyPasswordExtendedRequest 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 java.lang.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
                     java.lang.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.