From 6c711f696f73bc59813f6834ec241aef3b626cbd Mon Sep 17 00:00:00 2001
From: Frederic Guillot <fred@kanboard.net>
Date: Sat, 29 Aug 2015 20:00:53 -0400
Subject: Include documentation in the application

---
 doc/ldap-authentication.markdown | 234 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 234 insertions(+)
 create mode 100644 doc/ldap-authentication.markdown

(limited to 'doc/ldap-authentication.markdown')

diff --git a/doc/ldap-authentication.markdown b/doc/ldap-authentication.markdown
new file mode 100644
index 00000000..53b3d012
--- /dev/null
+++ b/doc/ldap-authentication.markdown
@@ -0,0 +1,234 @@
+LDAP authentication
+===================
+
+Requirements
+------------
+
+- LDAP extension for PHP
+- LDAP server:
+    - OpenLDAP
+    - Microsoft Active Directory
+    - Novell eDirectory
+
+Workflow
+--------
+
+When the LDAP authentication is activated, the login process work like that:
+
+1. Try first 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, 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
+- By default, all LDAP users have no admin privileges
+- To become administrator, a LDAP user must be promoted by another administrator
+
+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.
+
+### LDAP bind type
+
+There is 3 possible ways to browse the LDAP directory:
+
+#### Anonymous browsing
+
+```php
+define('LDAP_BIND_TYPE', 'anonymous');
+define('LDAP_USERNAME', null);
+define('LDAP_PASSWORD', null);
+```
+
+This is the default value but some LDAP servers don't allow that.
+
+#### Proxy user
+
+A specific user is used to browse the LDAP directory.
+By example, Novell eDirectory use that method.
+
+```php
+define('LDAP_BIND_TYPE', 'proxy');
+define('LDAP_USERNAME', 'my proxy user');
+define('LDAP_PASSWORD', 'my proxy password');
+```
+
+#### User credentials
+
+This method use the credentials provided by the end-user.
+By example, Microsoft Active Directory doesn't allow anonymous browsing by default and if you don't want to use a proxy user you can use this method.
+
+```php
+define('LDAP_BIND_TYPE', 'user');
+define('LDAP_USERNAME', '%s@mydomain.local');
+define('LDAP_PASSWORD', null);
+```
+
+Here, the `LDAP_USERNAME` is use to define a replacement pattern:
+
+```php
+define('LDAP_USERNAME', '%s@mydomain.local');
+
+// Another way to do the same:
+
+define('LDAP_USERNAME', 'MYDOMAIN\\%s');
+```
+
+### Example for Microsoft Active Directory
+
+Let's say we have a domain `KANBOARD` (kanboard.local) and the primary controller is `myserver.kanboard.local`.
+Microsoft Active Directory doesn't allow anonymous binding by default.
+
+First example with a proxy user:
+
+```php
+<?php
+
+// Enable LDAP authentication (false by default)
+define('LDAP_AUTH', true);
+
+// Credentials to be allowed to browse the LDAP directory
+define('LDAP_BIND_TYPE', 'proxy');
+define('LDAP_USERNAME', 'administrator@kanboard.local');
+define('LDAP_PASSWORD', 'my super secret password');
+
+// LDAP server hostname
+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_ACCOUNT_FULLNAME', 'displayname');
+define('LDAP_ACCOUNT_EMAIL', 'mail');
+```
+
+Another way with no proxy user:
+
+```php
+<?php
+
+// Enable LDAP authentication (false by default)
+define('LDAP_AUTH', true);
+
+// Credentials to be allowed to browse the LDAP directory
+define('LDAP_BIND_TYPE', 'user');
+define('LDAP_USERNAME', '%s@kanboard.local'); // or 'KANBOARD\\%s'
+define('LDAP_PASSWORD', null);
+
+// LDAP server hostname
+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_ACCOUNT_FULLNAME', 'displayname');
+define('LDAP_ACCOUNT_EMAIL', 'mail');
+```
+
+### Example for OpenLDAP
+
+Our LDAP server is `myserver.example.com` and all users are stored in the hierarchy `ou=People,dc=example,dc=com`.
+
+For this example with use the anonymous binding.
+
+```php
+<?php
+
+// Enable LDAP authentication (false by default)
+define('LDAP_AUTH', true);
+
+// LDAP server hostname
+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_ACCOUNT_FULLNAME', 'displayname');
+define('LDAP_ACCOUNT_EMAIL', 'mail');
+```
+
+The `%s` is replaced by the username for the parameter `LDAP_USER_PATTERN`, so you can define a custom Distinguished Name (example: ` (&(objectClass=user)(uid=%s)(!(ou:dn::=trainees)))`).
+
+### Disable automatic account creation
+
+By default, Kanboard will create automatically a user account if nothing is found.
+
+You can disable this behavior if you prefer to create user accounts manually to restrict Kanboard to only some people.
+
+Just change the value of `LDAP_ACCOUNT_CREATION` to `false`:
+
+```php
+// Automatically create user account
+define('LDAP_ACCOUNT_CREATION', false);
+```
+
+### SELinux on RHEL-based like CentOS
+
+If SELinux is enabled, you have to allow Apache to reach out your LDAP server.
+
+- You can switch SELinux to the permissive mode or disable it (not recomemnded)
+- You can allow all network connections, by example `setsebool -P httpd_can_network_connect=1` or have a more restrictive rule
+
+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);
+
+// 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)
+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 like that %s@kanboard.local
+define('LDAP_USERNAME', null);
+
+// LDAP password to connect with. null for anonymous bind (by 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', 'samaccountname');
+
+// 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);
+```
-- 
cgit v1.2.3