Directory Services

ldap_bind_s

The asynchronous function, ldap_bind_s authenticates a client to the LDAP server.

ULONG ldap_bind_s(
  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. This can be a DN, a UPN, a Windows NT-style username, or other name that the directory server will accept as an identifier.
cred
[in] A pointer to a null-terminated string that contains the credentials with which to authenticate. Arbitrary credentials can be passed using this parameter. The format and content of the credentials depends on the setting of the method parameter. For more information, see Remarks.
method
[in] Indicates the authentication method to use. For a listing of valid synchronous authentication methods, see Remarks. For more information and a description of the valid asychronous authentication method, see ldap_bind.

Return Values

If the function succeeds, the return value is LDAP_SUCCESS.

If the function fails, it returns an error code. For more information, see Return Values.

Remarks

The implementation of ldap_bind_s supports the authentication methods listed in the following table. Calling ldap_bind_s with the LDAP_AUTH_SIMPLE option is equivalent to calling ldap_simple_bind_s.

Method Description Credential
LDAP_AUTH_SIMPLE Authentication with a plaintext password. A string that contains the user password.
LDAP_AUTH_DIGEST Digest authentication package. Only supported on Windows XP and Windows Server 2003 family. To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY structure with the appropriate user name, domain name, and password.
LDAP_AUTH_DPA Distributed password authentication. Used by Microsoft Membership System. To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY structure with the appropriate user name, domain name, and password.
LDAP_AUTH_MSN Microsoft Network Authentication Service. To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY structure with the appropriate user name, domain name, and password.
LDAP_AUTH_NEGOTIATE Generic security services (GSS) (Snego). Does not provide authentication, but instead chooses the most appropriate authentication method from a list of available services and passes all authentication data to that service. Use with Windows 2000. To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY or SEC_WINNT_AUTH_IDENTITY_EX structure with the appropriate user name, domain name, and password.
LDAP_AUTH_NTLM Windows NT LAN Manager To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY or SEC_WINNT_AUTH_IDENTITY_EX structure with the appropriate user name, domain name, and password.
LDAP_AUTH_SICILY Covers package negotiation to MSN servers. To log in as the current user, set the dn and cred parameters to NULL. To log in as another user, set the dn parameter to NULL and the cred parameter to a pointer to a SEC_WINNT_AUTH_IDENTITY structure with the appropriate user name, domain name, and password.
LDAP_AUTH_SSPI Obsolete. Included for backward compatibility. Using this constant selects GSS (Snego) negotiation service. same as LDAP_AUTH_NEGOTIATE

For asynchronous bind authentication, use LDAP_AUTH_SIMPLE with ldap_bind.

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 exact credentials are dependent on the authentication method used. If you pass in NULL for the credentials with ldap_bind_s() (non-simple), the current user's/service's credentials will be used. If a simple bind method (as in ldap_simple_bind_s) is specified, it is equivalent to a NULL plaintext password. For more information, see ldap_bind.

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

Multithreading: Bind calls are unsafe because they apply to the connection as a whole. Use caution if threads share connections and try to thread the bind operations with other operations.

Note  The Microsoft LDAP client uses a default timeout value of 120 seconds (2 minutes) 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, the session must be terminated by passing the LDAP session handle to the ldap_unbind function. Also, if the ldap_bind_s 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, ldap_simple_bind_s, ldap_unbind, Return Values, SEC_WINNT_AUTH_IDENTITY, Establishing an LDAP Session