Up to Contents

Back to Working with Controls

Authenticating to the directory

The following functions are used to authenticate an LDAP client to an LDAP directory server. Authentication is optional if the client wishes to anonymously access an LDAPv3 server.

The ldap_sasl_bind() and ldap_sasl_bind_s() functions can be used to do general and extensible authentication over LDAP through the use of the Simple Authentication Security Layer. The routines both take the dn to bind as, the method to use, and a struct berval holding the credentials. The special constant value LDAP_SASL_SIMPLE (NULL) can be passed to request simple authentication, or the simplified routines ldap_simple_bind() or ldap_simple_bind_s() can be used for unencrypted password-based authentication.

           int ldap_sasl_bind(
                   LDAP            *ld,
                   char            *dn,
                   char            *mechanism,
                   struct berval   *cred,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   int             *msgidp
           );

           int ldap_sasl_bind_s(
                   LDAP            *ld,
                   char            *dn,
                   char            *mechanism,
                   struct berval   *cred,
                   LDAPControl     **serverctrls,
                   LDAPControl     **clientctrls,
                   struct berval   **servercredp
           );

           int ldap_simple_bind(
                   LDAP            *ld,
                   char            *dn,
                   char            *passwd
           );

           int ldap_simple_bind_s(
                   LDAP            *ld,
                   char            *dn,
                   char            *passwd
           );

The use of the following routines is deprecated:

           int ldap_bind( LDAP *ld, char *dn, char *cred, int method );

           int ldap_bind_s( LDAP *ld, char *dn, char *cred, int method );

Parameters are:

ld

The session handle.

dn

The name of the entry to bind as.

mechanism

Either LDAP_SASL_SIMPLE to get simple authentication, or a text string identifying the SASL method.

cred

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 mechanism parameter.

passwd

For ldap_simple_bind(), the password to compare to the entry's userPassword attribute.

serverctrls

List of LDAP server controls.

clientctrls

List of client controls.

msgidp

This result parameter will be set to the message id of the request if the ldap_sasl_bind() call succeeds.

servercredp

This result parameter will be set to the credentials returned by the server. This should be freed by calling ldap_memfree(). If no credentials are returned it will be set to NULL.

method

This can take one of the following values: LDAP_AUTH_NONE or LDAP_AUTH_SIMPLE.

Additional parameters for the deprecated routines are not described.

The ldap_sasl_bind() function initiates an asynchronous bind operation and returns the constant LDAP_SUCCESS if the request was successfully sent, or another LDAP error code if not. See the section below on error handling for more information about possible errors and how to interpret them. If successful, ldap_sasl_bind() places the message id of the request in *msgidp. A subsequent call to ldap_result(), described below, can be used to obtain the result of the bind.

The ldap_simple_bind() function initiates a simple asynchronous bind operation and returns the message id of the operation initiated. A subsequent call to ldap_result(), described below, can be used to obtain the result of the bind. In case of error, ldap_simple_bind() will return -1, setting the session error parameters in the LDAP structure appropriately.

The synchronous ldap_sasl_bind_s() and ldap_simple_bind_s() functions both return the result of the operation, either the constant LDAP_SUCCESS if the operation was successful, or another LDAP error code if it was not. See the section below on error handling for more information about possible errors and how to interpret them.

Note that if an LDAPv2 server is contacted, no other operations over the connection should be attempted before a bind call has successfully completed.

Subsequent bind calls can be used to re-authenticate over the same connection, and multistep SASL sequences can be accomplished through a sequence of calls to ldap_sasl_bind() or ldap_sasl_bind_s().

Up to Contents

Forward to Closing the Session