ldap_bind_s function (winldap.h)
The ldap_bind_s function synchronously authenticates a client to the LDAP server.
Syntax
WINLDAPAPI ULONG LDAPAPI ldap_bind_s(
[in] LDAP *ld,
[in] const PSTR dn,
[in] const PCHAR cred,
[in] ULONG method
);
Parameters
[in] ld
The session handle.
[in] dn
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 WinNT style user name, or other name that the directory server will accept as an identifier.
[in] cred
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.
[in] method
Indicates the authentication method to use. For more information and a listing of valid asynchronous authentication methods, see the Remarks section. For more information and a description of the valid asynchronous authentication method, see ldap_bind.
Return value
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 introduction of User Account Control in Windows Server 2008 and Windows Vista has a very important consequence with regard to making modifications or additions in LDAP. When a user is logged on to a DC with a restricted UAC Administrator token and using NULL credentials, any modification or addition to the directory, or any schema change operation, will fail. This includes DirSync searches, retrieving the SACL from an object's ntSecurityDescriptor attribute when using SecurityDescriptorFlags, and many other operations.
These will all fail with insufficient access rights.
If User Account Control is in effect when an administrator logs on to a DC, the administrator will get a restricted token in the logon session. If he or she then uses ldap_bind_s with NULL credentials, then operations that make modifications or additions will fail.
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. | 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. | 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 | 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 or service 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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista |
| Minimum supported server | Windows Server 2008 |
| Target Platform | Windows |
| Header | winldap.h |
| Library | Wldap32.lib |
| DLL | Wldap32.dll |