Unverified Commit 45097e9c authored by Faria Masood's avatar Faria Masood Committed by gitbook-bot
Browse files

GitBook: [master] 9 pages modified

parent e53067f4
# LDAP
To configure LDAP authentication, go to LDAP section of administration settings, enable LDAP and add configurations to connect with your LDAP server.
## Settings
{% page-ref page="basic-settings.md" %}
{% page-ref page="authentication-settings.md" %}
{% page-ref page="sync-settings.md" %}
{% page-ref page="timeouts-settings.md" %}
{% page-ref page="user-search-settings.md" %}
---
description: >-
To configure LDAP authentication, go to the LDAP section of administration
settings, enable LDAP, and add configurations to connect with your LDAP
server.
---
## Examples
{% page-ref page="examples.md" %}
## FAQ / Troubleshooting
# LDAP
{% page-ref page="faq.md" %}
## Work in Progress
We're not experts on LDAP, so there might be lots of features we don't know about and we'd love to have your comments and feedback of what we can do to improve it.
{% hint style="info" %}
We're not experts on LDAP, so there might be lots of features we don't know about and we'd love to have your comments and feedback on what we can do to improve it.
{% endhint %}
# Authentication Settings
#### Enable
## Enable
Disable Authentication to skip binding the user DN and password.
#### User DN
## User DN
The LDAP user that performs user lookups to authenticate other users when they sign in.
This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as
The LDAP user that performs user lookups to authenticate other users when they sign in. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as
cn=Administrator,cn=Users,dc=Example,dc=com
```text
cn=Administrator,cn=Users,dc=Example,dc=com
```
#### Password
## Password
The password for the User DN above.
# Basic Settings
#### Enable
### Enable
Turns LDAP Authentication ON or OFF.
#### Login Fallback
### Login Fallback
Enable this option to also allow regular password users to login on Rocket.Chat. It will also let LDAP users to continue using Rocket.Chat if the LDAP server is down.
#### Find user after login
### Find user after login
After a successful login, Rocket.Chat will search for the user on the LDAP server and reject the login if it is not found. Use this to prevent anonymous logins to Rocket.Chat when the LDAP Server allows anonymous logins.
#### Host
### Host
The LDAP connection host, e.g. ldap.example.com or 10.0.0.30
### Port
## Port
The LDAP connection Port, usually 389 or 636.
#### Reconnect
### Reconnect
Try to reconnect automatically when connection is interrupted by some reason while executing operations
#### Encryption
### Encryption
The encryption method used to secure communications to the LDAP server.
......@@ -34,26 +34,27 @@ The encryption method used to secure communications to the LDAP server.
| StartTLS | Upgrade to encrypted communication once connected |
| SSL/LDAPS | Encrypted from the start |
### CA Cert
#### CA Cert
#### Reject Unauthorized
### Reject Unauthorized
Disable this option to allow certificates that can not be verified. Usually Self Signed Certificates will require this option disabled to work
#### Base DN
### Base DN
The fully qualified Distinguished Name (DN) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. Example:
The fully qualified Distinguished Name \(DN\) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. Example:
ou=Users+ou=Projects,dc=Example,dc=com
```text
ou=Users+ou=Projects,dc=Example,dc=com
```
If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use search filter to control access.
#### Internal Log Level
### Internal Log Level
What log level should be used for the internal LDAP communication logs.
#### Test Connection
### Test Connection
Use this button to test if the connection settings are valid. This will test the authentication and encryption, but not the syncing settings.
Use this button to test if the connection settings are valid. This will test the authentication and encryption, but not the syncing settings.
\ No newline at end of file
# LDAP Examples
# Examples
* Host = ldap.domain.com
* Group = CN=ROCKET\_ACCESS,CN=Users,DC=domain,DC=com \(Access Control Group\)
......@@ -71,3 +69,4 @@ Finally on the Rocket.Chat server under /admin/LDAP set
* LDAP\_Url = localhost
* LDAP\_Port = 389
# LDAP FAQ / Troubleshooting
# FAQ
## What's the "Bind successful but user was not found via search" error?
......@@ -8,7 +8,6 @@ This error means that the login attempt was successful, but a subsequent search
You need to use the "Sync User Active State" setting under Advanced Sync, but it is not yet compatible with all LDAP Servers.
### I cannot login even everything looks good
If you cannot login without getting any error messages \(the last thing in log you see is `Attempt to bind <correct dn of user>`\), make sure the username of your ldap account does not match any username of a local account. For example if you created a local user with username `joe`, then enable ldap and try to login with username `joe` \(who exists on your ldap server\), it will silently fail without any error message in your log simply saying username or password do not match. You cannot login with `joe` by your ldap password nor by your local password any more.
......
# LDAP Settings
# Settings
## Basic Settings
......@@ -36,19 +36,19 @@ The encryption method used to secure communications to the LDAP server.
| StartTLS | Upgrade to encrypted communication once connected |
| SSL/LDAPS | Encrypted from the start |
#### CA Cert
#### Reject Unauthorized
Disable this option to allow certificates that can not be verified. Usually Self Signed Certificates will require this option disabled to work
#### Base DN
The fully qualified Distinguished Name (DN) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. Example:
The fully qualified Distinguished Name \(DN\) of an LDAP subtree you want to search for users and groups. You can add as many as you like; however, each group must be defined in the same domain base as the users that belong to it. Example:
ou=Users+ou=Projects,dc=Example,dc=com
```text
ou=Users+ou=Projects,dc=Example,dc=com
```
If you specify restricted user groups, only users that belong to those groups will be in scope. We recommend that you specify the top level of your LDAP directory tree as your domain base and use search filter to control access.
......@@ -68,24 +68,23 @@ Disable Authentication to skip binding the user DN and password.
#### User DN
The LDAP user that performs user lookups to authenticate other users when they sign in.
This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as
The LDAP user that performs user lookups to authenticate other users when they sign in. This is typically a service account created specifically for third-party integrations. Use a fully qualified name, such as
cn=Administrator,cn=Users,dc=Example,dc=com
```text
cn=Administrator,cn=Users,dc=Example,dc=com
```
#### Password
The password for the User DN above.
## Advanced Sync
#### Sync User Active State
Determine if users should be enabled or disabled on Rocket.Chat based on the LDAP status. The 'pwdAccountLockedTime' attribute will be used to determine if the user is disabled. This setting is not yet compatible with all LDAP Servers, so if you don't use the 'pwdAccountLockedTime' attribute, you may want to disable it completely.
## Role Mapping (Enterprise only)
## Role Mapping \(Enterprise only\)
#### Role mapping from LDAP to Rocket.Chat.
......@@ -93,12 +92,14 @@ Use this setting to map LDAP groups into Rocket.Chat roles.
You need to use an object format where the object key must be the LDAP group and the object value must be an array of RC roles. Example:
{
'ldapRole': [
'rcRole',
'anotherRCRole'
]
}
```text
{
'ldapRole': [
'rcRole',
'anotherRCRole'
]
}
```
#### Validate mapping for each login
......@@ -118,11 +119,11 @@ LDAP query to get the LDAP groups that the user is part of.
#### Username Field
Which field will be used as username for new users. Usually `sAMAccountName` or `uid`.
Leave empty to let the user pick their own Rocket.Chat username.
You can use template tags too, for example:
Which field will be used as username for new users. Usually `sAMAccountName` or `uid`. Leave empty to let the user pick their own Rocket.Chat username. You can use template tags too, for example:
#{givenName}.#{sn}
```text
#{givenName}.#{sn}
```
#### Unique Identifier Field
......@@ -138,20 +139,22 @@ If provided the Default Domain will be used to create an unique email for users
#### Sync User Data
Keep user data in sync with server on **login** or on **background sync** (eg: name, email and custom fields).
Keep user data in sync with server on **login** or on **background sync** \(eg: name, email and custom fields\).
#### User Data Field Map
Configure how user account fields (like email) are populated from a record in LDAP (once found).
Configure how user account fields \(like email\) are populated from a record in LDAP \(once found\).
As an example, `{"cn":"name", "mail":"email"}` will choose a person's human readable name from the cn attribute, and their email from the mail attribute.
Additionally it is possible to use variables, for example, the following object will use a combination of the user's first name and last name for the rocket chat.
{
"#{givenName} #{sn}": "name",
"mail": "email"
}
```text
{
"#{givenName} #{sn}": "name",
"mail": "email"
}
```
#### Sync LDAP Groups
......@@ -175,37 +178,35 @@ The mapping of LDAP groups to Rocket.Chat roles, in JSON format.
As an example, the following object will map the rocket-admin LDAP group to Rocket.Chat's "admin" role and the "tech-support" group to the "support" role.
{
"rocket-admin":"admin",
"tech-support":"support"
}
```text
{
"rocket-admin":"admin",
"tech-support":"support"
}
```
#### Auto Sync LDAP Groups to Channels
Enable this feature to automatically add users to a channel based on their LDAP group.
#### Channel Admin
When the above setting cause a channel to be created automatically during an user sync, this setting will determine what user will become the admin of the channel.
#### LDAP Group Channel Map
The map of LDAP groups to Rocket.Chat channels, in JSON format.
As an example, the following object will add any user in the LDAP group "employee" to the general channel on Rocket.Chat.
The map of LDAP groups to Rocket.Chat channels, in JSON format. As an example, the following object will add any user in the LDAP group "employee" to the general channel on Rocket.Chat.
{
"employee":"general"
}
```text
{
"employee":"general"
}
```
#### Auto Remove Users from Channels
Enabling this will remove any users in a channel that do not have the corresponding LDAP group! This will happen in every login and background sync, so removing a group on LDAP will not instantly remove access to channels on Rocket.Chat.
#### Sync User Avatar
Toggle avatar syncing on or off.
......@@ -224,28 +225,27 @@ The interval between synchronizations, using the [Cron Text](https://bunkat.gith
#### Background Sync Import New Users
Will import all users (based on your filter criteria) that exists in LDAP and does not exists in Rocket.Chat
Will import all users \(based on your filter criteria\) that exists in LDAP and does not exists in Rocket.Chat
#### Background Sync Update Existing Users
Will sync the avatar, fields, username, etc (based on your configuration) of all users already imported from LDAP on every **Sync Interval**
Will sync the avatar, fields, username, etc \(based on your configuration\) of all users already imported from LDAP on every **Sync Interval**
#### Execute Synchronization Now
Will execute the Background Sync now rather than wait the Sync Interval even if Background Sync is False.
This Action is asynchronous, please see the logs for more information about the process.
Will execute the Background Sync now rather than wait the Sync Interval even if Background Sync is False. This Action is asynchronous, please see the logs for more information about the process.
## Timeouts
#### Timeout (ms)
#### Timeout \(ms\)
How many mileseconds to wait for a search result before returning an error.
#### Connection Timeout (ms)
#### Connection Timeout \(ms\)
#### Idle Timeout (ms)
#### Idle Timeout \(ms\)
How many milliseconds to wait after the latest LDAP operation before closing the connection. (Each operation will open a new connection)
How many milliseconds to wait after the latest LDAP operation before closing the connection. \(Each operation will open a new connection\)
## User Search
......@@ -255,11 +255,15 @@ If specified, only users that match this filter will be allowed to log in. If no
E.g. for Active Directory
memberOf=cn=ROCKET_CHAT,ou=General Groups
```text
memberOf=cn=ROCKET_CHAT,ou=General Groups
```
E.g. for OpenLDAP (extensible match search)
E.g. for OpenLDAP \(extensible match search\)
ou:dn:=ROCKET_CHAT
```text
ou:dn:=ROCKET_CHAT
```
#### Scope
......@@ -275,20 +279,17 @@ The maximum number of entries each result page will return to be processed
#### Search Size Limit
The maximum number of entries to return.
**Attention** This number must be larger than the one on **Search Page Size**
The maximum number of entries to return. **Attention** This number must be larger than the one on **Search Page Size**
## User Search (Group Validation)
## User Search \(Group Validation\)
#### Enable LDAP User Group Filter
Restrict access to users in a LDAP group
Useful for allowing OpenLDAP servers without a **memberOf** filter to restrict access by groups.
Restrict access to users in a LDAP group Useful for allowing OpenLDAP servers without a **memberOf** filter to restrict access by groups.
#### Group ObjectClass
The **objectclass** that identify the groups.
E.g. **OpenLDAP**:groupOfUniqueNames
The **objectclass** that identify the groups. E.g. **OpenLDAP**:groupOfUniqueNames
#### Group ID Attribute
......@@ -300,8 +301,9 @@ E.g. **OpenLDAP**:uniqueMember
#### Group Member Format
E.g. **OpenLDAP**:uid=#{username},ou=users,o=Company,c=com
E.g. **OpenLDAP**:uid=\#{username},ou=users,o=Company,c=com
#### Group name
Group name to which the user should belong.
\ No newline at end of file
Group name to which the user should belong.
......@@ -2,157 +2,158 @@
## Sync / Import
#### Username Field
### Username Field
Which field will be used as username for new users. Usually `sAMAccountName` or `uid`.
Leave empty to let the user pick their own Rocket.Chat username.
You can use template tags too, for example:
Which field will be used as username for new users. Usually `sAMAccountName` or `uid`. Leave empty to let the user pick their own Rocket.Chat username. You can use template tags too, for example:
#{givenName}.#{sn}
```text
#{givenName}.#{sn}
```
#### Unique Identifier Field
### Unique Identifier Field
Which field will be used to link the LDAP user and the Rocket.Chat user. You can inform multiple values separated by comma to try to get the value from LDAP record.
#### Default Domain
### Default Domain
If provided the Default Domain will be used to create an unique email for users where email was not imported from LDAP. The email will be mounted as `username@default_domain` or `unique_id@default_domain`.
#### Merge Existing Users
### Merge Existing Users
**Caution!** When importing a user from LDAP and an user with same username already exists the LDAP info and password will be set into the existing user. This will let LDAP users take over password accounts with the same username.
#### Sync User Data
### Sync User Data
Keep user data in sync with server on **login** or on **background sync** (eg: name, email and custom fields).
Keep user data in sync with server on **login** or on **background sync** \(eg: name, email and custom fields\).
#### User Data Field Map
### User Data Field Map
Configure how user account fields (like email) are populated from a record in LDAP (once found).
Configure how user account fields \(like email\) are populated from a record in LDAP \(once found\).
As an example, `{"cn":"name", "mail":"email"}` will choose a person's human readable name from the cn attribute, and their email from the mail attribute.
Additionally it is possible to use variables, for example, the following object will use a combination of the user's first name and last name for the rocket chat.
{
"#{givenName} #{sn}": "name",
"mail": "email"
}
```text
{
"#{givenName} #{sn}": "name",
"mail": "email"
}
```
#### Sync LDAP Groups
### Sync LDAP Groups
Enable this setting to activate role mapping from user groups on the community edition of Rocket.Chat.
#### Auto Remove User Roles
### Auto Remove User Roles
Enable this setting to automatically remove roles from LDAP users that don't have the corresponding group. This will only remove roles automatically that are set under the user data group map below.
#### User Group Filter
### User Group Filter
The LDAP search filter used to check if a user is in a group.
#### LDAP Group BaseDN
### LDAP Group BaseDN
The LDAP BaseDN used to lookup if users are in a group.
#### User Data Group Map
### User Data Group Map
The mapping of LDAP groups to Rocket.Chat roles, in JSON format.
As an example, the following object will map the rocket-admin LDAP group to Rocket.Chat's "admin" role and the "tech-support" group to the "support" role.
{
"rocket-admin":"admin",
"tech-support":"support"
}
```text
{
"rocket-admin":"admin",
"tech-support":"support"
}
```
#### Auto Sync LDAP Groups to Channels
### Auto Sync LDAP Groups to Channels
Enable this feature to automatically add users to a channel based on their LDAP group.
#### Channel Admin
### Channel Admin
When the above setting cause a channel to be created automatically during an user sync, this setting will determine what user will become the admin of the channel.
### LDAP Group Channel Map
#### LDAP Group Channel Map
The map of LDAP groups to Rocket.Chat channels, in JSON format.
As an example, the following object will add any user in the LDAP group "employee" to the general channel on Rocket.Chat.
The map of LDAP groups to Rocket.Chat channels, in JSON format. As an example, the following object will add any user in the LDAP group "employee" to the general channel on Rocket.Chat.
```text
{
"employee":"general"
}
```
{
"employee":"general"
}
#### Auto Remove Users from Channels
### Auto Remove Users from Channels
Enabling this will remove any users in a channel that do not have the corresponding LDAP group! This will happen in every login and background sync, so removing a group on LDAP will not instantly remove access to channels on Rocket.Chat.
#### Sync User Avatar
### Sync User Avatar
Toggle avatar syncing on or off.
#### User avatar field
### User avatar field
What LDAP field will be used as **avatar** for users. Leave empty to use `thumbnailPhoto` first and `jpegPhoto` as fallback.
#### Background Sync
### Background Sync
Enable periodic background sync
#### Background Sync interval
### Background Sync interval
The interval between synchronizations, using the [Cron Text](https://bunkat.github.io/later/parsers.html#text) format,
#### Background Sync Import New Users
### Background Sync Import New Users
Will import all users (based on your filter criteria) that exists in LDAP and does not exists in Rocket.Chat
Will import all users \(based on your filter criteria\) that exists in LDAP and does not exists in Rocket.Chat
#### Background Sync Update Existing Users
### Background Sync Update Existing Users
Will sync the avatar, fields, username, etc (based on your configuration) of all users already imported from LDAP on every **Sync Interval**
Will sync the avatar, fields, username, etc \(based on your configuration\) of all users already imported from LDAP on every **Sync Interval**
#### Execute Synchronization Now
### Execute Synchronization Now
Will execute the Background Sync now rather than wait the Sync Interval even if Background Sync is False.
This Action is asynchronous, please see the logs for more information about the process.
Will execute the Background Sync now rather than wait the Sync Interval even if Background Sync is False. This Action is asynchronous, please see the logs for more information about the process.
## Advanced Sync
#### Sync User Active State
### Sync User Active State
Determine if users should be enabled or disabled on Rocket.Chat based on the LDAP status. The 'pwdAccountLockedTime' attribute will be used to determine if the user is disabled. This setting is not yet compatible with all LDAP Servers, so if you don't use the 'pwdAccountLockedTime' attribute, you may want to disable it completely.
## Role Mapping Settings (Enterprise only)
## Role Mapping Settings \(Enterprise only\)
#### Role mapping from LDAP to Rocket.Chat.
### Role mapping from LDAP to Rocket.Chat.
Use this setting to map LDAP groups into Rocket.Chat roles.
You need to use an object format where the object key must be the LDAP group and the object value must be an array of RC roles. Example:
{
'ldapRole': [
'rcRole',
'anotherRCRole'
]
}
```text
{
'ldapRole': [