h2. Binding and Unbinding

In *LDAP*, if one wants to access the data in the base, the common way to do it is to bind to the server. However, it is important to understand that binding is a different operation than connecting.

Creating a connection to a *LDAP* server is just about opening a socket between the client and the server. You just need to provide the hostname or address, and the port. 

The bind operation, on the other hand, creates a Session which will hold some user's information for the duration of the session. Those information are quite limited, they include the user's credentials.

It is important to know that it is possible to bind anonymously, providing no name and password, and still be able to request the server (note that the server can deny such anonymous bind).

Once the user has finished to request the server, then he can unbind, destroying his session on the server. That does not close the connection, because, one more time, _bind != connection_.

h3. Binding
You have two possible types of binds in *LDAP* :
* *Simple*
* *SASL*

The first one is based on a username/password being sent to the server, which checks that they are valid. It's also possible to proceed with an Anonymous bind explicitly.

The second one is more complex, and is used if you want to provide authentication with some specific mechanism, like *DIGEST-MD5*, *Kerberos* or certificate based.

h4. Simple Bind
One can issue three kinds of Simple bind :
* _anonymous bind_
* _username/password bind_
* _unauthenticated authentication bind_

The first one is the easiest one, but depending on the server configuration, it will be accepted or rejected (not all the servers allow anonymous binds).

Issuing an anonymous bind is very simple, you provide neither username nor password:

{code:java}
    @Test
    public void testAnonymousBindRequest() throws Exception
    {
        BindResponse bindResponse = connection.bind();

        assertNotNull( bindResponse );
        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode() );
        assertTrue( connection.isAuthenticated() );
    }
{code}

Issuing a username/password bind is just slightly more complex, you just have to provide your username and its password:

{code:java}
    @Test
    public void testSimpleBindRequest() throws Exception
    {
        BindResponse bindResponse = connection.bind( "uid=admin,ou=system", "secret" );

        assertNotNull( bindResponse );
        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode() );
        assertTrue( connection.isAuthenticated() );
    }
{code}

{note:warn}
It is important to note that the user's name is a *[DIRAPI:Dn]*, not a simple name like 'John doe"
{note}

Last but not least, there is a quite unknown feature in *LDAP* bind that allows you to issue a Bind request without providing a password. It is equivalent to an anonymous bind, except that the server can log the user's name, thus being able to trace what the user does. Servers might forbid such bind, and this will be the case if the server disallows anonymous binds.

Note that this kind of bind will be supported only if the server allows anonymous binds. It is not supported by *ApacheDS*.

{code:java}
    @Test
    public void testSimpleBindRequest() throws Exception
    {

        BindResponse bindResponse = connection.bind( "uid=admin,ou=system" );

        assertNotNull( bindResponse );
        assertEquals( ResultCodeEnum.SUCCESS, bindResponse.getLdapResult().getResultCode() );
        assertFalse( connection.isAuthenticated() );
    }
{code}

h4. SASL Bind

TO BE COMPLETED

h3. Unbinding

This is a trivial operation : you just send an *[UnbindRequest]* to the server, which will invalidate your session. 

It is important to know that when you issue an *Unbind*, the connection is dropped. However, if you immediately try another bind, the *API* will open the connection again, using the information provided when the connection was  created. You can do it this way:

{code:java}
    @Test
    public void testDoubleSimpleBindValid() throws Exception
    {
        BindResponse response = connection.bind( "uid=admin,ou=system", "secret" );
        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult().getResultCode() );
        assertTrue( connection.isConnected() );
        assertTrue( connection.isAuthenticated() );

        // Now, unbind
        connection.unBind();
        assertFalse( connection.isConnected() );
        assertFalse( connection.isAuthenticated() );

        // And bind again.
        response = connection.bind( "uid=admin,ou=system", "secret" );
        LdapResult ldapResult3 = response3.getLdapResult();
        assertEquals( ResultCodeEnum.SUCCESS, response.getLdapResult.getResultCode() );
        assertTrue( connection.isConnected() );
        assertTrue( connection.isAuthenticated() );
    }
{code}

If you issue a _bind_ on the same connection with different credentials, then the existing session will be terminated on the server, and a new one will be created. All the pending requests for the initial session will be lost.

Finally, if you close the connection the session will be terminated.