ldap_bind

The asynchronous function, ldap_bind authenticates a client to the LDAP server. The bind operation identifies a client to the directory server by providing a distinguished name and some type of authentication credential, such as a password. The authentication method used determines the type of credential that is required.

Caution  This function sends the name and password in plaintext, and therefore an unauthorized user cannot read the password. Unless a TLS (SSL) encrypted session has been set up, do not use this function. For more information about how to set up an encrypted session, see Initializing a Session.

ULONG ldap_bind(
  LDAP* ld,
  PCHAR dn,
  PCHAR cred,
  ULONG method
);

Parameters

ld

[in] The session handle.

dn

[in] A pointer to a null-terminated string that contains the distinguished name of the entry used to bind.

cred

[in] A pointer to a null-terminated string that contains the credentials to use for authentication. Arbitrary credentials can be passed using this parameter. The format and content of the credentials depend on the setting of the method parameter. For more information, see the Remarks section.

method

[in] Indicates the authentication method to use.

Return Values

If the function succeeds, the return value is the message ID of the operation that was initiated.

If the function fails, it returns –1 and sets the session error parameters in the LDAP structure.

Remarks

This implementation of ldap_bind supports the following authentication method.

LDAP_AUTH_SIMPLE is the only authentication method compatible with the asychronous version of binding; ldap_bind. Using any other authentication method with ldap_bind will result in failure and will return LDAP_PARAM_ERROR. Calling ldap_bind with the LDAP_AUTH_SIMPLE method is eqivalent to calling ldap_simple_bind. All other authentication methods require synchronous binding as provided by ldap_bind_s.

Be aware that LDAP 2 servers require an application to bind before attempting any other operations that require authentication.

Multithreading: Bind calls are not safe because they apply to the connection as a whole. Use caution if threads share connections and, when possible, thread the bind operations with other operations.

Note  The Microsoft LDAP client uses a default timeout value of 120 seconds for each bind-response roundtrip. This timeout value can be changed using the LDAP_OPT_TIMELIMIT session option. Other operations do not have a timeout unless specified using ldap_set_option.

When all of the operations on the session handle are completed, terminate the session by passing the LDAP session handle to the ldap_unbind function. Also, if the ldap_bind call fails, the session handle should be freed with a call to ldap_unbind when no longer required for error recovery.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on all platforms.
Header: Declared in Winldap.h.
Library: Use Wldap32.lib.

See Also

Functions, ldap_bind_s, ldap_simple_bind, ldap_simple_bind_s, ldap_unbind, SEC_WINNT_AUTH_IDENTITY, Establishing an LDAP Session