Update LDAP documentation
This commit is contained in:
Frederic Guillot
parent
28c8af70f4
commit
6d4286ec66
|
|
@ -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)
|
||||
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
|
||||
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');
|
||||
|
||||
// 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);
|
||||
// LDAP bind type: "anonymous", "user" or "proxy"
|
||||
define('LDAP_BIND_TYPE', 'anonymous');
|
||||
|
||||
// LDAP username to use with proxy mode
|
||||
// LDAP username pattern to use with user mode
|
||||
define('LDAP_USERNAME', null);
|
||||
|
||||
// LDAP password to use for proxy mode
|
||||
define('LDAP_PASSWORD', null);
|
||||
|
||||
// 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 pattern to use when searching for a user account
|
||||
// Example for ActiveDirectory: '(&(objectClass=user)(sAMAccountName=%s))'
|
||||
// Example for OpenLDAP: 'uid=%s'
|
||||
define('LDAP_USER_FILTER', '');
|
||||
|
||||
// LDAP attribute for username
|
||||
// Example for ActiveDirectory: 'samaccountname'
|
||||
// Example for OpenLDAP: 'uid'
|
||||
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 user email
|
||||
define('LDAP_USER_ATTRIBUTE_EMAIL', 'mail');
|
||||
|
||||
// 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', '');
|
||||
|
||||
// LDAP DN for managers
|
||||
// Example: CN=Kanboard Managers,CN=Users,DC=kanboard,DC=local
|
||||
define('LDAP_GROUP_MANAGER_DN', '');
|
||||
|
||||
// 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', '');
|
||||
|
||||
// LDAP attribute for the group name
|
||||
define('LDAP_GROUP_ATTRIBUTE_NAME', 'cn');
|
||||
```
|
||||
|
||||
Google Authentication settings
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
-------------
|
||||
Authentication Types
|
||||
--------------------
|
||||
|
||||
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.
|
||||
| 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 |
|
||||
|
||||
### LDAP bind type
|
||||
|
||||
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
|
||||
### Enable debug mode
|
||||
|
||||
```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" 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.
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
||||
Note: At the moment, that works only at account creation.
|
||||
Automatically load LDAP groups for project permissions
|
||||
------------------------------------------------------
|
||||
|
||||
Filter Kanboard access based on the LDAP group
|
||||
----------------------------------------------
|
||||
This feature allow you to sync automatically LDAP groups with Kanboard groups.
|
||||
Each group can have a different project role assigned.
|
||||
|
||||
To allow only some users to use Kanboard, use the existing `LDAP_USER_PATTERN` constant:
|
||||
On the project permissions page, people can enter groups in the auto-complete field and Kanboard can search for groups with any provider enabled.
|
||||
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
Loading…
Reference in New Issue