diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/config.markdown | 79 | ||||
| -rw-r--r-- | doc/index.markdown | 1 | ||||
| -rw-r--r-- | doc/ldap-authentication.markdown | 134 | ||||
| -rw-r--r-- | doc/ldap-group-sync.markdown | 47 | ||||
| -rw-r--r-- | doc/ldap-parameters.markdown | 31 |
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 |