# Настройка LDAP

В этой статье описываются параметры подключения **Webim** к **Active Directory** по протоколу **LDAP**:

  * назначение и область применения **LDAP-подключения**;

  * состав блока `ldap` в [редакторе настроек аккаунта (account config)](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html);

  * настройка подключения к контроллеру домена;

  * настройка области поиска пользователей и групп безопасности;

  * настройка сопоставления групп безопасности;

  * примеры конфигурации;

  * базовая проверка работы **LDAP**.

## Термины

  * **LDAP** — протокол доступа к каталогу. В этой статье подразумевается подключение к **Active Directory** для поиска пользователей и получения их атрибутов.

  * **LDAPS** — подключение к **LDAP** с использованием **TLS** (защищённое соединение).

  * **DN (Distinguished Name)** — отличительное имя объекта в каталоге **LDAP/Active Directory**, которое однозначно определяет его положение в дереве. **DN** состоит из компонентов `CN`, `OU`, `DC`. Пример **DN** группы: `CN=operators,OU=roles,DC=webim,DC=local`.

  * **OU** — подразделение (организационная единица) в **Active Directory**. Используется для построения структуры каталога (например, отделы, сервисные учётные записи, группы).

  * **search_base** — **DN**, от которого начинается поиск пользователя в каталоге (область поиска).

  * **sAMAccountName** — логин пользователя внутри домена **Active Directory**. Используется при поиске пользователя в каталоге.

  * **Идентификатор SSO** — логин пользователя и имя домена в формате `sAMAccountName@DOMAIN`, где `DOMAIN` — значение поля `name` соответствующего объекта в массиве `ldap.domains` с учётом регистра, например `operator@EXAMPLE`.

  * **memberOf** — атрибут пользователя **Active Directory** со списком групп, в которые входит пользователь (в виде **DN**). Используется для сопоставления с группами безопасности Webim.

## Назначение протокола

**LDAP-подключение** в контексте интеграции с **Active Directory** используется для:

  * поиска учетной записи пользователя по его логину в домене (`sAMAccountName`);

  * получения атрибутов пользователя (отображаемое имя, адрес электронной почты);

  * получения списка групп безопасности пользователя из атрибута `memberOf` (для сопоставления с группами безопасности Webim).

**Webim** обращается к **Active Directory** по **LDAP**:

  * во время входа оператора через **Active Directory** (**SSO**);

  * при фоновой синхронизации данных операторов;

  * при ручной синхронизации из интерфейса администратора.

Конкретные механизмы авторизации и синхронизации описаны в статье [«SSO и режимы авторизации»](https://webim.ru/kb/devops/active-directory/sso-configuration.html).

## Пререквизиты

### Со стороны Active Directory

  * Развёрнут контроллер домена **Active Directory**.

  * Настроен **DNS** домена (разрешение имён контроллеров домена).

  * Определены:

    * контроллер(ы) домена, к которым будет подключаться **Webim**;

    * сервисная учетная запись (например, `svc_webim`), под которой будут выполняться **LDAP-запросы**;

    * подразделения (**OU**), в которых размещены пользователи и группы, связанные с **Webim**.

  * Сервисной учетной записи предоставлены права на чтение атрибутов пользователей и групп в пределах области поиска.

### Со стороны сервера Webim

  * Сервер **Webim** имеет сетевой доступ к контроллеру домена по **TCP**:

    * **389** (**LDAP**) — если используется незащищённое подключение;

    * **636** (**LDAPS**) — если используется защищённое подключение.

  * На сервере **Webim** установлен **LDAP-клиент** для диагностики (достаточно наличия утилит `ldapsearch`/`ldapwhoami`):

    * **Debian/Ubuntu**: `ldap-utils`

    * **RHEL-подобные**: `openldap-clients`

  * Настроена **Kerberos-конфигурация** (для **SSO**), если используется единый вход. См. [«настройка Kerberos»](https://webim.ru/kb/devops/active-directory/kerberos-configuration.html).

## Блок LDAP в редакторе настроек аккаунта

Параметры подключения к **LDAP** задаются в [редакторе настроек аккаунта (account config)](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html) в виде отдельного блока `ldap` в формате `JSON`. Подключения к доменам перечисляются в массиве `ldap.domains`. Для каждого домена необходимо задать все поля из таблицы.

| Поле                       | Тип       | Значение по умолчанию | Описание                                                                                                                                                                                                                                  |
| -------------------------- | --------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                     | `string`  | —                     | Имя домена. Используется в идентификаторе SSO в формате `sAMAccountName@DOMAIN`, например `operator@EXAMPLE`.                                                                                                                              |
| `url`                      | `string`  | —                     | Адрес **LDAP-сервера** (хост/порт). Используется для подключения (вместе с `use_ssl`).                                                                                                                                                    |
| `user`                     | `string`  | —                     | Учётная запись для привязки (**LDAP DN / UPN** — в зависимости от настроек **Active Directory/LDAP**).                                                                                                                                    |
| `password`                 | `string`  | —                     | Пароль учётной записи для привязки.                                                                                                                                                                                                       |
| `search_base`              | `string`  | —                     | База поиска (**DN**) в соответствующем домене, например `DC=example,DC=local`.                                                                                                                                                            |
| `security_group_pattern`   | `string`  | —                     | Шаблон **DN** группы безопасности в соответствующем домене. В строке используется плейсхолдер `{}` — вместо него подставляется **имя группы безопасности Webim** (`Security group name`). Пример: `CN={},OU=roles,DC=example,DC=local`. |
| `security_group_attribute` | `string`  | —                     | Атрибут пользователя, из которого берётся список групп безопасности.                                                                                                                                                                      |
| `use_ssl`                  | `boolean` | —                     | Использовать ли **SSL** при подключении к **LDAP**.                                                                                                                                                                                        |

Пример:

  ```json
  {
    "ldap": {
      "domains": [
        {
          "name": "EXAMPLE",
          "url": "ldap://dc1.example.local:389",
          "user": "CN=svc_webim,OU=ServiceAccounts,DC=example,DC=local",
          "password": "********",
          "search_base": "OU=WebimUsers,DC=example,DC=local",
          "security_group_pattern": "CN={},OU=WebimGroups,OU=WebimUsers,DC=example,DC=local",
          "security_group_attribute": "memberOf",
          "use_ssl": false
        },
        {
          "name": "BRANCH",
          "url": "ldap://dc1.branch.local:389",
          "user": "CN=svc_webim,OU=ServiceAccounts,DC=branch,DC=local",
          "password": "********",
          "search_base": "OU=WebimUsers,DC=branch,DC=local",
          "security_group_pattern": "CN={},OU=WebimGroups,OU=WebimUsers,DC=branch,DC=local",
          "security_group_attribute": "memberOf",
          "use_ssl": false
        }
      ]
    }
  }
  ```

Чтобы настроить один домен, добавьте в `domains` один объект.

## Настройка подключения к LDAP

### Параметр `name`

`name` задаёт имя домена, которое используется для различения одноимённых пользователей из разных доменов. Например, пользователи с `sAMAccountName=operator` из доменов `EXAMPLE` и `BRANCH` получают разные идентификаторы SSO: `operator@EXAMPLE` и `operator@BRANCH`.

Webim не проверяет уникальность имён: при одинаковых `name` пользователи с одним и тем же `sAMAccountName` из этих доменов получат одинаковый идентификатор SSO и будут сопоставлены с одним оператором.

### Параметр `url`

Параметр `url` задает адрес контроллера домена и тип подключения:

  * пример для **LDAP**:

    ```json
    "url": "ldap://dc1.example.local:389"
    ```

  * пример для **LDAPS**:

    ```json
    "url": "ldaps://dc1.example.local:636"
    ```

!!! Note "N.B."
    При использовании **LDAPS** необходимо:

      * убедиться, что сертификат контроллера домена выдан доверенным центром (корневой сертификат установлен на сервере Webim);

      * убедиться, что имя в сертификате совпадает с именем, указанным в `url`.

### Параметры `user` и `password`

`user` — **DN** сервисной учетной записи, под которой выполняются **LDAP-запросы**.

Пример:

  ```json
  "user": "CN=svc_webim,OU=ServiceAccounts,DC=example,DC=local"
  ```

`password` — пароль данной учетной записи.

### Параметр `use_ssl`

  * `true` — подключение выполняется в режиме **LDAPS**.

  * `false` — подключение выполняется в режиме **LDAP**.

## Настройка области поиска

Параметр `search_base` определяет корневой **DN**, в пределах которого **Webim** выполняет поиск пользователей **Active Directory** в конкретном домене.

Примеры:

  ```json
  "search_base": "DC=example,DC=local"
  ```

  ```json
  "search_base": "OU=WebimUsers,DC=example,DC=local"
  ```

## Настройка сопоставления групп безопасности

### Параметр `security_group_pattern`

`security_group_pattern` задаёт шаблон **DN** групп безопасности **Active Directory**, которые **Webim** сопоставляет с группами безопасности **Webim**. В шаблоне вместо имени группы используется подстановка `{}`. Пример:

  ```json
  "security_group_pattern": "CN={},OU=WebimGroups,OU=WebimUsers,DC=example,DC=local"
  ```

Как работает сопоставление:

  1. Администратор создаёт в **Webim** группу безопасности с именем `Operators`.

  1. При обработке данных из **Active Directory Webim** формирует ожидаемый **DN** группы как:

    ```text
    CN=Operators,OU=WebimGroups,OU=WebimUsers,DC=example,DC=local
    ```

  1. **Webim** сравнивает этот **DN** со значениями, полученными из `memberOf` доменного пользователя.

!!! Warning "Важно!"
    Значение `security_group_pattern` должно соответствовать формату **DN**, который возвращает **Active Directory** в `memberOf`.

### Параметр `security_group_attribute`

`security_group_attribute` — имя атрибута объекта пользователя, содержащего список **DN** групп, в которые входит пользователь. Для **Active Directory** должен использоваться атрибут:

  ```json
  "security_group_attribute": "memberOf"
  ```

## Проверка работы LDAP

### Проверка подключения с сервера Webim

Для базовой проверки подключения к **LDAP** с сервера **Webim** используйте `ldapwhoami` и `ldapsearch`.

#### Проверка LDAP-подключения

  * **LDAP**:

    ```bash
    ldapwhoami \
      -H "ldap://dc1.example.local:389" \
      -D "CN=svc_webim,OU=ServiceAccounts,DC=example,DC=local" \
      -W
    ```

  * **LDAPS**:

    ```bash
    ldapwhoami \
      -H "ldaps://dc1.example.local:636" \
      -D "CN=svc_webim,OU=ServiceAccounts,DC=example,DC=local" \
      -W
    ```

#### Проверка поиска пользователя по sAMAccountName

  ```bash
  ldapsearch \
    -H "ldap://dc1.example.local:389" \
    -D "CN=svc_webim,OU=ServiceAccounts,DC=example,DC=local" \
    -W \
    -b "OU=WebimUsers,DC=example,DC=local" \
    "(sAMAccountName=test.user)" \
    sAMAccountName mail displayName memberOf
  ```

Проверьте, что:

  * запись пользователя найдена;

  * атрибут `memberOf` содержит **DN** групп, которые должны сопоставляться с группами безопасности **Webim**.

### Проблемы и возможные ошибки

При возникновении ошибок смотрите статью [«Интеграция с Active Directory: диагностика и типовые ошибки»](https://webim.ru/kb/devops/active-directory/troubleshooting.html).

---

Источник: https://webim.ru/kb/devops/active-directory/ldap-configuration.html