== The LDAP auth provider implementation

This is an auth provider implementation that authenticates via LDAP. 

=== Getting started

To use this project, add the following dependency to the _dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
 <groupId>io.vertx</groupId>
 <artifactId>vertx-auth-ldap</artifactId>
 <version>4.0.0.Beta2</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
compile 'io.vertx:vertx-auth-ldap:4.0.0.Beta2'
----


=== Instantiation

To create an instance of the Ldap auth provider, use `link:../../apidocs/io/vertx/ext/auth/ldap/LdapAuthentication.html#create-io.vertx.core.Vertx-io.vertx.ext.auth.ldap.LdapAuthenticationOptions-[LdapAuthentication.create]` as follows:

=== Configuration

The class `link:../../apidocs/io/vertx/ext/auth/ldap/LdapAuthenticationOptions.html[LdapAuthenticationOptions]` is used to configure the Ldap authentication provider:

`authenticationQuery`:: this query is used when looking up a user with a particular id. An example is `uid={0},ou=users,dc=foo,dc=com` - the element `{0}` is substituted with the user id to create the
actual lookup. This setting is mandatory.

`url`:: the url to the LDAP server. The url must start with `ldap://` and a port must be specified.
An example is `ldap://myldapserver.mycompany.com:10389`

`authenticationMechanism`:: Sets the type of LDAP authentication mechanism to use when connecting to the LDAP server.

`referral`:: Sets the LDAP referral behavior when creating a connection.  Defaults to `follow`.  See the Sun/Oracle LDAP
referral documentation for more: http://java.sun.com/products/jndi/tutorial/ldap/referral/jndi.html

=== Notes

Note that when authenticating using this implementation, it assumes `username` and `password` fields are present in the authentication info