Package org.forgerock.opendj.ldap.messages

Class BindRequest

java.lang.Object
org.forgerock.opendj.ldap.messages.BindRequest
All Implemented Interfaces:
ProtocolOp, Request
public final class BindRequest extends Object implements Request
The Bind operation allows authentication information to be exchanged between the client and server. The Bind operation should be thought of as the "authenticate" operation.

  • Field Details

    • AUTHENTICATION_TYPE_SIMPLE

      public static final byte AUTHENTICATION_TYPE_SIMPLE
      The authentication type value (0x80) reserved for simple authentication.
      See Also:

    • AUTHENTICATION_TYPE_SASL

      public static final byte AUTHENTICATION_TYPE_SASL
      The authentication type value (0xA3) reserved for SASL authentication.
      See Also:

    • SASL_MECHANISM_NAME_ANONYMOUS

      public static final String SASL_MECHANISM_NAME_ANONYMOUS
      The name of the SASL mechanism that uses anonymous access and having the name "ANONYMOUS".
      See Also:

    • SASL_MECHANISM_NAME_CRAM_MD5

      public static final String SASL_MECHANISM_NAME_CRAM_MD5
      The name of the SASL mechanism that uses CRAM-MD5 authentication and having the name "CRAM-MD5".
      See Also:

    • SASL_MECHANISM_NAME_DIGEST_MD5

      public static final String SASL_MECHANISM_NAME_DIGEST_MD5
      The name of the SASL mechanism that uses DIGEST-MD5 authentication and having the name "DIGEST-MD5".
      See Also:

    • SASL_MECHANISM_NAME_PLAIN

      public static final String SASL_MECHANISM_NAME_PLAIN
      The name of the SASL mechanism that uses PLAIN authentication and having the name "PLAIN".
      See Also:

    • SASL_MECHANISM_NAME_EXTERNAL

      public static final String SASL_MECHANISM_NAME_EXTERNAL
      The name of the SASL mechanism that uses external authentication and having the name "EXTERNAL".
      See Also:

    • SASL_MECHANISM_NAME_GSSAPI

      public static final String SASL_MECHANISM_NAME_GSSAPI
      The name of the SASL mechanism that uses GSS-API authentication and having the name "GSSAPI".
      See Also:

    • SASL_MECHANISM_NAME_SCRAM_SHA_256

      public static final String SASL_MECHANISM_NAME_SCRAM_SHA_256
      The name of the SASL mechanism that uses SCRAM-SHA-256 authentication and having the name "SCRAM-SHA-256".
      See Also:

    • SASL_MECHANISM_NAME_SCRAM_SHA_512

      public static final String SASL_MECHANISM_NAME_SCRAM_SHA_512
      The name of the SASL mechanism that uses SCRAM-SHA-512 authentication and having the name "SCRAM-SHA-512".
      See Also:

  • Method Details

    • getVersion

      public int getVersion()
      Returns the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

      By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

      Returns:
      The version of the protocol to be used at the LDAP message layer.

    • setVersion

      public BindRequest setVersion(int version)
      Sets the version of the protocol to be used at the LDAP message layer. There is no version negotiation. The client sets this field to the version it desires. If the server does not support the specified version then it will respond with a result whose error code is ResultCode.PROTOCOL_ERROR.

      By default LDAP version 3 will be used which is the most recent LDAP version and the one recommended for all client applications. Furthermore, OpenDJ only has partial support for LDAPv2.

      Parameters:
      version - The version of the protocol to be used at the LDAP message layer.
      Returns:
      This bind request.
      Throws:
      IllegalArgumentException - If version is less than 1 or greater than 127.
      UnsupportedOperationException - If this bind request does not permit the version to be set.

    • getName

      public Dn getName()
      Returns the name of the Directory object that the client wishes to bind as. The name may be empty (but never null) when used for anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Returns:
      The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.

    • setName

      public BindRequest setName(Dn name)
      Sets the name of the Directory object that the client wishes to bind as. The name may be empty (but never null when used for of anonymous binds, or when using SASL authentication. The server shall not dereference any aliases in locating the named object.

      The LDAP protocol defines the Bind name to be a distinguished name, however some LDAP implementations have relaxed this constraint and allow other identities to be used, such as the user's email address.

      Parameters:
      name - The name of the Directory object that the client wishes to bind as. May be empty, but cannot be null.
      Returns:
      This bind request.
      Throws:
      UnsupportedOperationException - If this bind request does not permit the distinguished name to be set.
      NullPointerException - If name was null.

    • getAuthenticationType

      public byte getAuthenticationType()
      Returns the authentication mechanism identifier for this bind request as defined by the LDAP protocol. Note that the value AUTHENTICATION_TYPE_SIMPLE (0x80) is reserved for simple authentication and the value AUTHENTICATION_TYPE_SASL ( 0xA3) is reserved for SASL authentication.
      Returns:
      The authentication mechanism identifier.

    • getAuthenticationValue

      public byte[] getAuthenticationValue()
      Returns a defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol. For simple authentication the authentication value is the byte representation of the password. For SASL authentication the authentication value is an ASN.1 encoded sequence comprising of the SASL mechanism name and the optional SASL mechanism specific credentials.
      Returns:
      A defensive copy of the encoded authentication value for this bind request as defined by the LDAP protocol.

    • accept

      public <R, P, E extends Exception> R accept(RequestVisitor<R,P,E> v, P p) throws E
      Description copied from interface: Request
      Applies a RequestVisitor to this Request.
      Specified by:
      accept in interface Request
      Type Parameters:
      R - The return type of the visitor's methods.
      P - The type of the additional parameters to the visitor's methods.
      E - The type of the exception thrown by the visitor method if it fails, or NeverThrowsException if the visitor cannot fail.
      Parameters:
      v - The request visitor.
      p - Optional additional visitor parameter.
      Returns:
      A result as specified by the visitor.
      Throws:
      E - If the visitor failed.

    • getSimplePassword

      public byte[] getSimplePassword()
      Returns a defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.
      Returns:
      A defensive copy of the simple bind password, or null if the authentication type is not AUTHENTICATION_TYPE_SIMPLE.

    • getSaslMechanism

      public String getSaslMechanism()
      Returns the name of the SASL mechanism, e.g. SASL_MECHANISM_NAME_PLAIN, or null if the authentication type is not AUTHENTICATION_TYPE_SASL.
      Returns:
      The name of the SASL mechanism, e.g. SASL_MECHANISM_NAME_PLAIN, or null if the authentication type is not AUTHENTICATION_TYPE_SASL.

    • getSaslCredentials

      public byte[] getSaslCredentials()
      Returns a defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.
      Returns:
      A defensive copy of the optional SASL credentials, or null if the authentication type is not AUTHENTICATION_TYPE_SASL or if the SASL credentials are not present.

    • isSimpleBindRequest

      public boolean isSimpleBindRequest()
      Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SIMPLE.
      Returns:
      true if this bind request's authentication type is AUTHENTICATION_TYPE_SIMPLE.

    • isSaslBindRequest

      public boolean isSaslBindRequest()
      Return true if this bind request's authentication type is AUTHENTICATION_TYPE_SASL.
      Returns:
      true if this bind request's authentication type is AUTHENTICATION_TYPE_SASL.

    • setAuthenticationTypeAndValue

      public BindRequest setAuthenticationTypeAndValue(byte type, byte[] value) throws IOException
      Sets the authentication type and value. If type is equal to AUTHENTICATION_TYPE_SIMPLE then the value will be interpreted as the password. If type is equal to AUTHENTICATION_TYPE_SASL then the value will be interpreted as the encoded SASL mechanism and credentials. Otherwise, the value will be interpreted as an unrecognized extended authentication value.
      Parameters:
      type - The authentication mechanism identifier.
      value - The encoded authentication value for this bind request as defined by the LDAP protocol, which may be an empty array but must not be null. The value will be defensively copied.
      Returns:
      This bind request.
      Throws:
      IOException - If the authentication type is AUTHENTICATION_TYPE_SASL and the value could not be decoded as an encoded SASL mechanism and credentials.
      UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
      NullPointerException - If value was null.

    • setSimplePassword

      public BindRequest setSimplePassword(byte[] password)
      Sets the authentication type to AUTHENTICATION_TYPE_SIMPLE and the authentication value to a copy of the provided password.
      Parameters:
      password - The non-null simple bind password, which will be defensively copied.
      Returns:
      This bind request.
      Throws:
      UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
      NullPointerException - If password was null.

    • setSaslMechanismAndCredentials

      public BindRequest setSaslMechanismAndCredentials(String mechanism, byte[] credentials)
      Sets the authentication type to AUTHENTICATION_TYPE_SASL, the SASL mechanism name, and the optional SASL credentials.
      Parameters:
      mechanism - The SASL mechanism name, such as SASL_MECHANISM_NAME_PLAIN.
      credentials - The optional SASL credentials which will be defensively copied if provided.
      Returns:
      This bind request.
      Throws:
      UnsupportedOperationException - If this bind request does not permit the authentication type or value to be set.
      NullPointerException - If mechanism was null.

    • setSaslMechanismAndCredentials

      public BindRequest setSaslMechanismAndCredentials(SaslClient saslClient)
      Configures this bind request for SASL authentication using the provided SaslClient. The authentication type will be set to AUTHENTICATION_TYPE_SASL, the SASL mechanism name will be obtained from the SaslClient, and the SASL credentials will be derived from the SaslClient if it has an initial response, otherwise they will be left undefined.

      This method should be used if the application is performing SASL authentication and wishes the network layer to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application a) will not be able to control where bind requests are sent if load-balancing is active, b) nor will it be able to install a security layer upon completion of the bind sequence if one is negotiated.

      Parameters:
      saslClient - The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes.
      Returns:
      This bind request.
      Throws:
      IllegalArgumentException - If the provided SASL client has not been configured correctly.
      UnsupportedOperationException - If this bind request does not permit the SaslClient to be set.
      NullPointerException - If saslClient was null.

    • getSaslClient

      public SaslClient getSaslClient()
      Returns the SaslClient that will be responsible for continuing the SASL challenge-response sequence as well as potentially installing a SASL security layer once the bind sequence completes, or null if a no SaslClient has been provided.

      A SaslClient is only required if the application is performing SASL authentication and wishes the network layer to drive the complete challenge-response sequence. An application may choose to drive the SASL bind sequence itself, but the application:

      1. will not be able to control where bind requests are sent if load-balancing is active,
      2. nor will it be able to install a security layer upon completion of the bind sequence.
      Returns:
      The SaslClient that will be responsible for continuing the SASL challenge-response sequence, as well as potentially installing a SASL security layer once the bind sequence completes, or null if none has been provided.
      See Also:

    • evaluateSaslChallenge

      public BindRequest evaluateSaslChallenge(byte[] serverSaslCredentials) throws SaslException
      Evaluates the provided SASL credentials (challenge) returned by the server and creates the next SASL bind request that should be sent to the server in order to continue or complete the SASL authentication sequence. This method may only be called if this request has been configured to use a SaslClient.
      Parameters:
      serverSaslCredentials - The non-null SASL challenge sent from the server, which may be empty.
      Returns:
      The next SASL bind request to be sent to the server, or null if the SASL bind sequence has completed.
      Throws:
      SaslException - If an error occurred while evaluating the challenge or generating a response.
      IllegalStateException - If this bind request has not been configured to use a SaslClient.
      NullPointerException - If serverSaslCredentials was null.
      See Also:

    • hasNegotiatedSaslQop

      public boolean hasNegotiatedSaslQop()
      Returns true if the SASL bind sequence has negotiated a SASL security layer using Quality of Protection (QOP). This method may only be called if this request has been configured to use a SaslClient and the SASL bind sequence has completed (the previous call to evaluateSaslChallenge(byte[]) returned null).
      Returns:
      true if the SASL bind sequence has negotiated a SASL security layer (QOP).
      Throws:
      IllegalStateException - If this bind request has not been configured to use a SaslClient or the SASL bind sequence has not completed.
      See Also:

    • destroy

      public void destroy()
      Destroys the credentials contained within this bind request. This method does not dispose the SaslClient. Instead the underlying network layer will dispose of the SaslClient when it is no longer in use. This bind request can no longer be used once this method returns.

    • getType

      public Request.RequestType getType()
      Description copied from interface: Request
      Returns the type of this request to avoid expensive instanceof checks.
      Specified by:
      getType in interface Request
      Returns:
      the type of this request

    • toString

      public String toString()

    • addControl

      public final BindRequest addControl(Control control)
      Description copied from interface: ProtocolOp
      Adds the provided control to this protocol-op.
      Specified by:
      addControl in interface ProtocolOp
      Parameters:
      control - The control to be added to this protocol-op.
      Returns:
      This protocol-op.

    • addControls

      public final BindRequest addControls(Iterable<? extends Control> controls)
      Description copied from interface: ProtocolOp
      Adds the provided controls to this protocol-op.
      Specified by:
      addControls in interface ProtocolOp
      Parameters:
      controls - The controls to be added to this protocol-op.
      Returns:
      This protocol-op.

    • removeControls

      public final BindRequest removeControls(String oid)
      Description copied from interface: ProtocolOp
      Removes all the controls having the specified OID.
      Specified by:
      removeControls in interface ProtocolOp
      Parameters:
      oid - The numeric OID of the protocol-op control to remove.
      Returns:
      This protocol-op.

    • containsControl

      public final boolean containsControl(String oid)
      Description copied from interface: ProtocolOp
      Returns true if this protocol-op contains the specified control.
      Specified by:
      containsControl in interface ProtocolOp
      Parameters:
      oid - The numeric OID of the protocol-op control.
      Returns:
      true if this protocol-op contains the specified control.

    • getControl

      public final <C extends Control> C getControl(ControlDecoder<C> decoder, DecodeOptions options) throws DecodeException
      Description copied from interface: ProtocolOp
      Decodes and returns the first control in this protocol-op having an OID corresponding to the provided control decoder.
      Specified by:
      getControl in interface ProtocolOp
      Type Parameters:
      C - The type of control to be decoded and returned.
      Parameters:
      decoder - The control decoder.
      options - The set of decode options which should be used when decoding the control.
      Returns:
      The decoded control, or null if the control is not included with this protocol-op.
      Throws:
      DecodeException - If the control could not be decoded because it was malformed in some way (e.g. the control value was missing, or its content could not be decoded).

    • getControls

      public final List<Control> getControls()
      Description copied from interface: ProtocolOp
      Returns a List containing the controls included with this protocol-op. The returned List may be modified if permitted by this protocol-op.
      Specified by:
      getControls in interface ProtocolOp
      Returns:
      A List containing the controls.