Update LDAP documentation

5 files changed, 159 insertions, 133 deletions

diff --git a/doc/config.markdown b/doc/config.markdown
index f375b2fc..8ae56df6 100644
--- a/doc/config.markdown
+++ b/doc/config.markdown
@@ -2,7 +2,7 @@ Config file
 ===========
 
 You can customize the default settings of Kanboard by adding a file `config.php` at the project root.
-You can also rename the `config.default.php` and change the desired values.
+You can also rename the file `config.default.php` to `config.php` and change the desired values.
 
 Enable/Disable debug mode
 -------------------------
@@ -102,59 +102,76 @@ define('LDAP_SERVER', '');
 // LDAP server port (389 by default)
 define('LDAP_PORT', 389);
 
-// By default, require certificate to be verified for ldaps:// style URL. Set to false to skip the verification.
+// By default, require certificate to be verified for ldaps:// style URL. Set to false to skip the verification
 define('LDAP_SSL_VERIFY', true);
 
 // Enable LDAP START_TLS
 define('LDAP_START_TLS', false);
 
-// LDAP bind type: "anonymous", "user" (use the given user/password from the form) and "proxy" (a specific user to browse the LDAP directory)
+// By default Kanboard lowercase the ldap username to avoid duplicate users (the database is case sensitive)
+// Set to true if you want to preserve the case
+define('LDAP_USERNAME_CASE_SENSITIVE', false);
+
+// LDAP bind type: "anonymous", "user" or "proxy"
 define('LDAP_BIND_TYPE', 'anonymous');
 
-// LDAP username to connect with. null for anonymous bind (by default).
-// Or for user bind type, you can use a pattern: %s@kanboard.local
+// LDAP username to use with proxy mode
+// LDAP username pattern to use with user mode
 define('LDAP_USERNAME', null);
 
-// LDAP password to connect with. null for anonymous bind (by default).
+// LDAP password to use for proxy mode
 define('LDAP_PASSWORD', null);
 
-// LDAP account base, i.e. root of all user account
-// Example: ou=People,dc=example,dc=com
-define('LDAP_ACCOUNT_BASE', '');
+// LDAP DN for users
+// Example for ActiveDirectory: CN=Users,DC=kanboard,DC=local
+// Example for OpenLDAP: ou=People,dc=example,dc=com
+define('LDAP_USER_BASE_DN', '');
 
-// LDAP query pattern to use when searching for a user account
+// LDAP pattern to use when searching for a user account
 // Example for ActiveDirectory: '(&(objectClass=user)(sAMAccountName=%s))'
 // Example for OpenLDAP: 'uid=%s'
-define('LDAP_USER_PATTERN', '');
+define('LDAP_USER_FILTER', '');
 
-// Name of an attribute of the user account object which should be used as the full name of the user.
-define('LDAP_ACCOUNT_FULLNAME', 'displayname');
-
-// Name of an attribute of the user account object which should be used as the email of the user.
-define('LDAP_ACCOUNT_EMAIL', 'mail');
-
-// Name of an attribute of the user account object which should be used as the id of the user.
+// LDAP attribute for username
 // Example for ActiveDirectory: 'samaccountname'
 // Example for OpenLDAP: 'uid'
-define('LDAP_ACCOUNT_ID', 'samaccountname');
+define('LDAP_USER_ATTRIBUTE_USERNAME', 'uid');
+
+// LDAP attribute for user full name
+// Example for ActiveDirectory: 'displayname'
+// Example for OpenLDAP: 'cn'
+define('LDAP_USER_ATTRIBUTE_FULLNAME', 'cn');
 
-// LDAP Attribute for group membership
-define('LDAP_ACCOUNT_MEMBEROF', 'memberof');
+// LDAP attribute for user email
+define('LDAP_USER_ATTRIBUTE_EMAIL', 'mail');
 
-// DN for administrators
-// Example: CN=Kanboard Admins,CN=Users,DC=kanboard,DC=local
+// LDAP attribute to find groups in user profile
+define('LDAP_USER_ATTRIBUTE_GROUPS', 'memberof');
+
+// Allow automatic LDAP user creation
+define('LDAP_USER_CREATION', true);
+
+// LDAP DN for administrators
+// Example: CN=Kanboard-Admins,CN=Users,DC=kanboard,DC=local
 define('LDAP_GROUP_ADMIN_DN', '');
 
-// DN for project administrators
-// Example: CN=Kanboard Project Admins,CN=Users,DC=kanboard,DC=local
-define('LDAP_GROUP_PROJECT_ADMIN_DN', '');
+// LDAP DN for managers
+// Example: CN=Kanboard Managers,CN=Users,DC=kanboard,DC=local
+define('LDAP_GROUP_MANAGER_DN', '');
 
-// By default Kanboard lowercase the ldap username to avoid duplicate users (the database is case sensitive)
-// Set to true if you want to preserve the case
-define('LDAP_USERNAME_CASE_SENSITIVE', false);
+// Enable LDAP group provider for project permissions
+// The end-user will be able to browse LDAP groups from the user interface and allow access to specified projects
+define('LDAP_GROUP_PROVIDER', false);
+
+// LDAP Base DN for groups
+define('LDAP_GROUP_BASE_DN', '');
+
+// LDAP group filter
+// Example for ActiveDirectory: (&(objectClass=group)(sAMAccountName=%s*))
+define('LDAP_GROUP_FILTER', '');
 
-// Automatically create user account
-define('LDAP_ACCOUNT_CREATION', true);
+// LDAP attribute for the group name
+define('LDAP_GROUP_ATTRIBUTE_NAME', 'cn');
 ```
 
 Google Authentication settings
diff --git a/doc/index.markdown b/doc/index.markdown
index 801a90e4..3311156f 100644
--- a/doc/index.markdown
+++ b/doc/index.markdown
@@ -118,6 +118,7 @@ Technical details
 
 - [LDAP authentication](ldap-authentication.markdown)
 - [LDAP group sync](ldap-group-sync.markdown)
+- [LDAP parameters](ldap-parameters.markdown)
 - [Google authentication](google-authentication.markdown)
 - [Github authentication](github-authentication.markdown)
 - [Gitlab authentication](gitlab-authentication.markdown)
diff --git a/doc/ldap-authentication.markdown b/doc/ldap-authentication.markdown
index f2e4869a..c932ec5a 100644
--- a/doc/ldap-authentication.markdown
+++ b/doc/ldap-authentication.markdown
@@ -1,4 +1,4 @@
-LDAP authentication
+LDAP Authentication
 ===================
 
 Requirements
@@ -19,22 +19,18 @@ When the LDAP authentication is activated, the login process work like that:
 2. If the user is not found inside the database, a LDAP authentication is performed
 3. If the LDAP authentication is successful, by default 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
-
 The full name and the email address are automatically fetched from the LDAP server.
 
-Configuration
--------------
-
-You have to create a custom config file named `config.php` (you can also use the template `config.default.php`).
-This file must be stored in the root directory of Kanboard.
+Authentication Types
+--------------------
 
-### LDAP bind type
+| Type       | Description                                                     |
+|------------|-----------------------------------------------------------------|
+| Proxy User | A specific user is used to browse LDAP directory                |
+| User       | The end-user credentials are used for browsing LDAP directory   |
+| Anonymous  | No authentication is performed for LDAP browsing                |
 
-There are 3 possible ways to browse the LDAP directory:
+**The recommended authentication method is "Proxy"**.
 
 #### Anonymous mode
 
@@ -44,7 +40,7 @@ define('LDAP_USERNAME', null);
 define('LDAP_PASSWORD', null);
 ```
 
-This is the default value but some LDAP servers don't allow that.
+This is the default value but some LDAP servers don't allow anonymous browsing for security reasons.
 
 #### Proxy mode
 
@@ -73,7 +69,26 @@ In this case, the constant `LDAP_USERNAME` is used as a pattern to the ldap user
 - `%s@kanboard.local` will be replaced by `my_user@kanboard.local`
 - `KANBOARD\\%s` will be replaced by `KANBOARD\my_user`
 
-### Example for Microsoft Active Directory
+User LDAP filter
+----------------
+
+The configuration parameter `LDAP_USER_FILTER` is used to find users in LDAP directory.
+
+Examples:
+
+- `(&(objectClass=user)(sAMAccountName=%s))` is replaced by `(&(objectClass=user)(sAMAccountName=my_username))`
+- `uid=%s` is replaced by `uid=my_username`
+
+Other examples of [filters for Active Directory](http://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx)
+
+By example you can filter access to Kanboard from the user filter:
+
+`(&(objectClass=user)(sAMAccountName=%s)(memberOf=CN=Kanboard Users,CN=Users,DC=kanboard,DC=local))`
+
+This example allow only people member of the group "Kanboard Users" to connect to Kanboard.
+
+Example for Microsoft Active Directory
+--------------------------------------
 
 Let's say we have a domain `KANBOARD` (kanboard.local) and the primary controller is `myserver.kanboard.local`.
 
@@ -93,8 +108,8 @@ define('LDAP_PASSWORD', 'my super secret password');
 define('LDAP_SERVER', 'myserver.kanboard.local');
 
 // LDAP properties
-define('LDAP_ACCOUNT_BASE', 'CN=Users,DC=kanboard,DC=local');
-define('LDAP_USER_PATTERN', '(&(objectClass=user)(sAMAccountName=%s))');
+define('LDAP_USER_BASE_DN', 'CN=Users,DC=kanboard,DC=local');
+define('LDAP_USER_FILTER', '(&(objectClass=user)(sAMAccountName=%s))');
 ```
 
 Second example with user mode:
@@ -113,11 +128,12 @@ define('LDAP_PASSWORD', null);
 define('LDAP_SERVER', 'myserver.kanboard.local');
 
 // LDAP properties
-define('LDAP_ACCOUNT_BASE', 'CN=Users,DC=kanboard,DC=local');
-define('LDAP_USER_PATTERN', '(&(objectClass=user)(sAMAccountName=%s))');
+define('LDAP_USER_BASE_DN', 'CN=Users,DC=kanboard,DC=local');
+define('LDAP_USER_FILTER', '(&(objectClass=user)(sAMAccountName=%s))');
 ```
 
-### Example for OpenLDAP
+Example for OpenLDAP
+--------------------
 
 Our LDAP server is `myserver.example.com` and all users are stored under `ou=People,dc=example,dc=com`.
 
@@ -133,13 +149,12 @@ define('LDAP_AUTH', true);
 define('LDAP_SERVER', 'myserver.example.com');
 
 // LDAP properties
-define('LDAP_ACCOUNT_BASE', 'ou=People,dc=example,dc=com');
-define('LDAP_USER_PATTERN', 'uid=%s');
+define('LDAP_USER_BASE_DN', 'ou=People,dc=example,dc=com');
+define('LDAP_USER_FILTER', 'uid=%s');
 ```
 
-The `%s` is replaced by the username for the parameter `LDAP_USER_PATTERN`, so you can define a custom Distinguished Name: ` (&(objectClass=user)(uid=%s)(!(ou:dn::=trainees)))`.
-
-### Disable automatic account creation
+Disable automatic account creation
+-----------------------------------
 
 By default, Kanboard will create automatically a user account if nothing is found.
 
@@ -152,6 +167,9 @@ Just change the value of `LDAP_ACCOUNT_CREATION` to `false`:
 define('LDAP_ACCOUNT_CREATION', false);
 ```
 
+Troubleshootings
+----------------
+
 ### SELinux restrictions
 
 If SELinux is enabled, you have to allow Apache to reach out your LDAP server.
@@ -161,68 +179,6 @@ If SELinux is enabled, you have to allow Apache to reach out your LDAP server.
 
 In any case, refer to the official Redhat/Centos documentation.
 
-### Available configuration parameters
-
-```php
-// Enable LDAP authentication (false by default)
-define('LDAP_AUTH', false);
-
-// LDAP server hostname
-define('LDAP_SERVER', '');
-
-// LDAP server port (389 by default)
-define('LDAP_PORT', 389);
+### Enable debug mode
 
-// By default, require certificate to be verified for ldaps:// style URL. Set to false to skip the verification
-define('LDAP_SSL_VERIFY', true);
-
-// Enable LDAP START_TLS
-define('LDAP_START_TLS', false);
-
-// LDAP bind type: "anonymous", "user" or "proxy"
-define('LDAP_BIND_TYPE', 'anonymous');
-
-// LDAP username to connect with. null for anonymous bind (default).
-define('LDAP_USERNAME', null);
-
-// LDAP password to connect with. null for anonymous bind (default).
-define('LDAP_PASSWORD', null);
-
-// LDAP account base, i.e. root of all user account
-// Example: ou=People,dc=example,dc=com
-define('LDAP_ACCOUNT_BASE', '');
-
-// LDAP query pattern to use when searching for a user account
-// Example for ActiveDirectory: '(&(objectClass=user)(sAMAccountName=%s))'
-// Example for OpenLDAP: 'uid=%s'
-define('LDAP_USER_PATTERN', '');
-
-// Name of an attribute of the user account object which should be used as the full name of the user.
-define('LDAP_ACCOUNT_FULLNAME', 'displayname');
-
-// Name of an attribute of the user account object which should be used as the email of the user.
-define('LDAP_ACCOUNT_EMAIL', 'mail');
-
-// Name of an attribute of the user account object which should be used as the id of the user.
-// Example for ActiveDirectory: 'samaccountname'
-// Example for OpenLDAP: 'uid'
-define('LDAP_ACCOUNT_ID', '');
-
-// LDAP Attribute for group membership
-define('LDAP_ACCOUNT_MEMBEROF', 'memberof');
-
-// DN for administrators
-// Example: CN=Kanboard Admins,CN=Users,DC=kanboard,DC=local
-define('LDAP_GROUP_ADMIN_DN', '');
-
-// DN for project administrators
-// Example: CN=Kanboard Project Admins,CN=Users,DC=kanboard,DC=local
-define('LDAP_GROUP_PROJECT_ADMIN_DN', '');
-
-// By default Kanboard lowercase the ldap username to avoid duplicate users (the database is case sensitive)
-// Set to true if you want to preserve the case
-define('LDAP_USERNAME_CASE_SENSITIVE', false);
-
-// Automatically create user account
-define('LDAP_ACCOUNT_CREATION', true);
-```
+If you are not able to setup correctly the LDAP authentication you can [enable the debug mode](config.markdown) and watch log files.
diff --git a/doc/ldap-group-sync.markdown b/doc/ldap-group-sync.markdown
index 355a1cde..29489229 100644
--- a/doc/ldap-group-sync.markdown
+++ b/doc/ldap-group-sync.markdown
@@ -7,30 +7,51 @@ Requirements
 - Have LDAP authentication properly configured
 - Use a LDAP server that supports `memberOf`
 
-Automatically define Kanboard groups based on LDAP groups
----------------------------------------------------------
+Define automatically user roles based on LDAP groups
+----------------------------------------------------
 
-In your config file, define the constants `LDAP_GROUP_ADMIN_DN` and `LDAP_GROUP_PROJECT_ADMIN_DN`. Here an example, replace the values according to your own LDAP configuration:
+Use these constants in your config file:
+
+- `LDAP_GROUP_ADMIN_DN`: Distinguished names for application administrators
+- `LDAP_GROUP_MANAGER_DN`: Distinguished names for application managers
+
+Example:
 
 ```php
 define('LDAP_GROUP_ADMIN_DN', 'CN=Kanboard Admins,CN=Users,DC=kanboard,DC=local');
-define('LDAP_GROUP_PROJECT_ADMIN_DN', 'CN=Kanboard Project Admins,CN=Users,DC=kanboard,DC=local');
+define('LDAP_GROUP_MANAGER_DN', 'CN=Kanboard Managers,CN=Users,DC=kanboard,DC=local');
 ```
 
-- People member of "Kanboard Admins" will be "Kanboard Administrators"
-- People member of "Kanboard Project Admins" will be "Kanboard Project Administrators"
-- Everybody else will be Kanboard Standard Users
+- People member of "Kanboard Admins" will have the role "Administrator"
+- People member of "Kanboard Managers" will have the role "Managers"
+- Everybody else will have the role "User"
+
+Automatically load LDAP groups for project permissions
+------------------------------------------------------
 
-Note: At the moment, that works only at account creation.
+This feature allow you to sync automatically LDAP groups with Kanboard groups.
+Each group can have a different project role assigned.
 
-Filter Kanboard access based on the LDAP group
-----------------------------------------------
+On the project permissions page, people can enter groups in the auto-complete field and Kanboard can search for groups with any provider enabled.
 
-To allow only some users to use Kanboard, use the existing `LDAP_USER_PATTERN` constant:
+If the group doesn't exists in the local database, it will be automatically synced.
+
+- `LDAP_GROUP_PROVIDER`: Enable the LDAP group provider
+- `LDAP_GROUP_BASE_DN`: Distinguished names to find groups in LDAP directory
+- `LDAP_GROUP_FILTER`: LDAP filter used to perform the query
+- `LDAP_GROUP_ATTRIBUTE_NAME`: LDAP attribute used to fetch the group name
+
+Example:
 
 ```php
-define('LDAP_USER_PATTERN', '(&(objectClass=user)(sAMAccountName=%s)(memberOf=CN=Kanboard Users,CN=Users,DC=kanboard,DC=local))');
+define('LDAP_GROUP_PROVIDER', true);
+define('LDAP_GROUP_BASE_DN', 'CN=Groups,DC=kanboard,DC=local');
+define('LDAP_GROUP_FILTER', '(&(objectClass=group)(sAMAccountName=%s*))');
 ```
 
-This example allow only people member of the group "Kanboard Users" to connect to Kanboard.
+With the filter given as example above, Kanboard will search for groups that match the query.
+If the end-user type the text "My group" in the auto-complete box, Kanboard will return all groups that match the pattern: `(&(objectClass=group)(sAMAccountName=My group*))`.
+
+Note that the special characters ***** is import here, otherwise an exact match will be done.
 
+[More examples of LDAP filters for Active Directory](http://social.technet.microsoft.com/wiki/contents/articles/5392.active-directory-ldap-syntax-filters.aspx)
diff --git a/doc/ldap-parameters.markdown b/doc/ldap-parameters.markdown
new file mode 100644
index 00000000..8dd0565b
--- /dev/null
+++ b/doc/ldap-parameters.markdown
@@ -0,0 +1,31 @@
+LDAP Configuration Parameters
+=============================
+
+Here are the list of available LDAP parameters:
+
+| Parameter                       | Default value  | Description                                    |
+|---------------------------------|----------------|------------------------------------------------|
+| `LDAP_AUTH`                     | false          | Enable LDAP authentication                     |
+| `LDAP_SERVER`                   | Empty          | LDAP server hostname                           |
+| `LDAP_PORT`                     | 389            | LDAP server port                               |
+| `LDAP_SSL_VERIFY`               | true           | Validate certificate for `ldaps://` style URL  |
+| `LDAP_START_TLS`                | false          | Enable LDAP start TLS                          |
+| `LDAP_USERNAME_CASE_SENSITIVE`  | false          | Kanboard lowercase the ldap username to avoid duplicate users (the database is case sensitive)  |
+| `LDAP_BIND_TYPE`                | anonymous      | Bind type: "anonymous", "user" or "proxy"      |
+| `LDAP_USERNAME`                 | null           | LDAP username to use with proxy mode or username pattern to use with user mode  |
+| `LDAP_PASSWORD`                 | null           | LDAP password to use for proxy mode            |
+| `LDAP_USER_BASE_DN`             | Empty          | LDAP DN for users (Example: "CN=Users,DC=kanboard,DC=local")           |
+| `LDAP_USER_FILTER`              | Empty          | LDAP pattern to use when searching for a user account (Example: "(&(objectClass=user)(sAMAccountName=%s))")            |
+| `LDAP_USER_ATTRIBUTE_USERNAME`  | uid            | LDAP attribute for username (Example: "samaccountname")            |
+| `LDAP_USER_ATTRIBUTE_FULLNAME`  | cn             | LDAP attribute for user full name (Example: "displayname")         |
+| `LDAP_USER_ATTRIBUTE_EMAIL`     | mail           | LDAP attribute for user email                                      |
+| `LDAP_USER_ATTRIBUTE_GROUPS`    | memberof       | LDAP attribute to find groups in user profile                      |
+| `LDAP_USER_CREATION`            | true           | Enable automatic LDAP user creation                                |
+| `LDAP_GROUP_ADMIN_DN`           | Empty          | LDAP DN for administrators (Example: "CN=Kanboard-Admins,CN=Users,DC=kanboard,DC=local")   |
+| `LDAP_GROUP_MANAGER_DN`         | Empty          | LDAP DN for managers (Example: "CN=Kanboard Managers,CN=Users,DC=kanboard,DC=local")   |
+| `LDAP_GROUP_PROVIDER`           | false          | Enable LDAP group provider for project permissions  |
+| `LDAP_GROUP_BASE_DN`            | Empty          | LDAP Base DN for groups   |
+| `LDAP_GROUP_FILTER`             | Empty          | LDAP group filter (Example: "(&(objectClass=group)(sAMAccountName=%s*))")   |
+| `LDAP_GROUP_ATTRIBUTE_NAME`     | cn             | LDAP attribute for the group name  |
+
+- LDAP attributes must be in lowercase