Add LDAP documentation

docs/ldap-authentication.markdown

@@ -0,0 +1,73 @@
+LDAP authentication
+===================
+
+Requirements
+------------
+
+- LDAP extension for PHP
+- LDAP server (By example: OpenLDAP or Microsoft Active Directory)
+
+Workflow
+--------
+
+When the LDAP authentication is activated, the login process work like that:
+
+1. Try to authenticate the user by using the database
+2. If the user is not found inside the database, a LDAP authentication is performed
+3. If the LDAP authentication is successful, a local user is created automatically with no password and marked as LDAP user.
+
+Differences between a local user and a LDAP user are the following:
+
+- LDAP users have no local passwords
+- LDAP users can't modify their password with the user interface
+- By default, all LDAP users have no admin privileges
+- To become administrator, a LDAP user must be promoted by another administrator
+
+Configuration
+-------------
+
+The first step is to create a custom config file named `config.php`.
+This file must be stored in the root directory.
+
+To do that, you can create an empty PHP file or copy/rename the sample file `config.default.php`.
+
+### Example for Microsoft Active Directory
+
+Let's say we have a domain `MYDOMAIN` (mydomain.local) and the primary controller is `myserver.mydomain.local`.
+
+```php
+<?php
+
+// Enable LDAP authentication (false by default)
+define('LDAP_AUTH', true);
+
+// LDAP server hostname
+define('LDAP_SERVER', 'myserver.mydomain.local');
+
+// User LDAP DN
+define('LDAP_USER_DN', 'MYDOMAIN\\%s');
+
+// Another way to do the same thing
+define('LDAP_USER_DN', '%s@mydomain.local');
+
+```
+
+### Example for OpenLDAP
+
+Here, our LDAP server is `myserver.example.com` and all users are stored in the hierarchy `ou=People,dc=example,dc=com`.
+
+```php
+<?php
+
+// Enable LDAP authentication (false by default)
+define('LDAP_AUTH', true);
+
+// LDAP server hostname
+define('LDAP_SERVER', 'myserver.example.com');
+
+// User LDAP DN
+define('LDAP_USER_DN', 'uid=%s,ou=People,dc=example,dc=com');
+
+```
+
+The `%s` is replaced by the username for the parameter `LDAP_USER_DN`, so you can define a custom Distinguished Name.