# SSO и режимы авторизации

**SSO** (сквозная авторизация) в **Webim 10.8** — это механизм входа операторов в интерфейсы **Webim** без ввода логина/пароля, за счёт интеграции с **Active Directory**.

В этой статье описаны:

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

  * режимы авторизации и их влияние на вход по паролю и по **SSO**;

  * периодическая и ручная синхронизация данных операторов с **Active Directory**.

## Перед началом

Для полноценной работы **SSO** и синхронизации необходимо:

  1. Настроить **Kerberos** на стороне инфраструктуры **Webim** (см. [Настройка Kerberos](https://webim.ru/kb/devops/active-directory/kerberos-configuration.html)).

  1. Настроить подключение к **Active Directory** по **LDAP** (см. [Настройка LDAP](https://webim.ru/kb/devops/active-directory/ldap-configuration.html)).

  1. Иметь доступ к **Редактору настроек аккаунта (account config)**, чтобы внести параметры `sso`, `ldap`, `kerberos` (см. [Редактор настроек аккаунта (account config)](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html)).

## Термины

  * **Настройки оператора** — часть данных оператора, где **Webim** хранит служебные и **SSO-параметры**. Эти значения находятся в объекте `config`.

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

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

  * **`displayName`** — отображаемое имя пользователя в **Active Directory**.

  * **`mail`** — адрес электронной почты пользователя в **Active Directory**.

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

## Настройка SSO в account-config

Настройки **SSO** задаются в `account-config` в параметре `sso`. Значение — **JSON-объект**. Параметр должен быть задан полностью.

### Параметры `sso`

| Параметр                                |    Тип |       По умолчанию | Описание                                                                                                                                 |
| ----------------------------------------| ------ | ------------------ | -----------------------------------------------------------------------------------------------------------------------------------------|
| `enabled`                               |   bool |            `false` | Включает/выключает **SSO**.                                                                                                              |
| `type`                                  | string | `active_directory` | Тип **SSO**. В **Webim 10.8** поддерживается значение `active_directory`.                                                                |
| `auth_mode`                             | string | `only_common_auth` | Режим авторизации: `only_sso`, `sso_and_common_auth`, `only_common_auth`.                                                                |
| `default_status_after_sso_login`        | string |        `invisible` | Статус оператора после входа через **SSO**. Применяется только при `auth_mode=only_sso`. Допустимые значения: `invisible`, `online`, `offline`. |
| `create_new_agent_if_not_exist`         |   bool |            `false` | Создавать оператора в **Webim** при первом успешном входе через **SSO**, если он ещё не существует.                                      |
| `disable_editing_agents_updated_by_sso` |   bool |            `false` | Ограничивает редактирование некоторых полей оператора в интерфейсе **Webim**, если оператор был обновлён из **Active Directory**.        |
| `enable_periodic_synchronization`       |   bool |            `false` | Разрешает периодическую синхронизацию данных операторов с **Active Directory** (по расписанию).                                          |
| `allow_manual_synchronization`          |   bool |            `false` | Разрешает ручную синхронизацию данных операторов с **Active Directory** из интерфейса.                                                   |

Пример:

  ```json
  {
    "sso": {
      "enabled": true,
      "type": "active_directory",
      "disable_editing_agents_updated_by_sso": false,
      "enable_periodic_synchronization": true,
      "create_new_agent_if_not_exist": true,
      "auth_mode": "sso_and_common_auth",
      "allow_manual_synchronization": true
    }
  }
  ```

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

Параметр `sso.default_status_after_sso_login` задаёт статус оператора, который применяется после входа через **SSO**.

Допустимые значения:

  * `invisible`;

  * `online`;

  * `offline`.

Как работает параметр в режимах авторизации:

  * при `auth_mode=only_sso` параметр применяется, значение по умолчанию — `invisible`;

  * при `auth_mode=sso_and_common_auth` параметр не применяется: оператор выбирает статус сам на форме входа через чекбокс «Войти через AD»;

  * при `auth_mode=only_common_auth` параметр не применяется, потому что **SSO-вход** отключён.

Пример для режима `only_sso`:

  ```json
  {
    "sso": {
      "enabled": true,
      "type": "active_directory",
      "auth_mode": "only_sso",
      "default_status_after_sso_login": "invisible"
    }
  }
  ```

## Режимы авторизации

Параметр `auth_mode` задаёт, какие способы входа доступны операторам:

  * **SSO** — вход через **Kerberos/Active Directory**;

  * **Common auth** — стандартный вход по электронной почте и паролю.

| `auth_mode`           | Что разрешено                                     | Что запрещено                      |
| ----------------------| --------------------------------------------------| -----------------------------------|
| `only_sso`            | Только **SSO-вход**                               | Вход по электронной почте и паролю |
| `only_common_auth`    | Только вход по электронной почте и паролю         | **SSO-вход**                       |
| `sso_and_common_auth` | **SSO-вход** и вход по электронной почте и паролю | —                                  |

!!! Warning "Важно!"
    Дополнительное правило для входа **по электронной почте и паролю** в режиме `sso_and_common_auth`: если у оператора заполнен `sso_username` и выключен флаг `allow_common_auth`, то вход по электронной почте и паролю для него будет запрещён (останется только **SSO**).

## Настройки SSO на стороне оператора

В карточке оператора используются поля:

  * `sso_username` — идентификатор оператора в **Active Directory** в формате `sAMAccountName@DOMAIN`, например `operator@EXAMPLE`. В профиле сотрудника поле подписано как «Идентификатор пользователя, используемый для схемы аутентификации SSO»;

  * `allow_sso` — разрешает оператору входить через **SSO**. В профиле сотрудника поле подписано как «Разрешить аутентификацию пользователя через SSO»;

  * `allow_common_auth` — разрешает оператору входить по электронной почте и паролю (работает только с настройкой `auth_mode=sso_and_common_auth`). В профиле сотрудника поле подписано как «Разрешить аутентификацию по электронной почте и паролю»;

  * `is_updated_by_sso` — служебный флаг, который выставляется при обновлении оператора из **Active Directory**.

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

Параметр управляет тем, можно ли вручную редактировать в **Webim** сотрудников, чьи данные пришли из **Active Directory**.

Если одновременно выполняются условия:

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

  * у оператора установлен служебный признак `config.is_updated_by_sso=true`;

то в карточке оператора **Webim** отключается редактирование данных, которые должны приходить из **Active Directory** и групп безопасности:

  * **Имя** (значение, получаемое из `displayName`);

  * **Электронная почта** (значение, получаемое из `mail`);

  * **Роли** (назначаются через сопоставленные группы безопасности **Webim**);

  * **Отделы** и **наблюдаемые отделы** (также назначаются через сопоставленные группы безопасности **Webim**).

Параметр не отключает саму синхронизацию. Он влияет только на возможность ручного редактирования в интерфейсе **Webim**.

## Синхронизация данных из Active Directory

Синхронизация выполняется:

  * при входе оператора через **SSO**;

  * при периодической синхронизации (если включена);

  * при ручной синхронизации из интерфейса (если разрешена).

## Сопоставление оператора Webim с пользователем Active Directory

**Webim** связывает доменного пользователя **Active Directory** с оператором **Webim** по полю `sso_username`.

Как формируется и используется `sso_username`:

  * по имени домена, полученному при входе через **SSO**, **Webim** выбирает соответствующий объект из массива `ldap.domains`;

  * в выбранном домене **Webim** ищет пользователя по атрибуту `sAMAccountName`;

  * идентификатор в формате `sAMAccountName@DOMAIN` сохраняется у оператора в `config.sso_username`;

  * при последующих входах через **SSO** и при синхронизации **Webim** находит оператора по `config.sso_username`.

Благодаря имени домена пользователи с одинаковым `sAMAccountName` из разных доменов сопоставляются с разными операторами. Например, `operator@EXAMPLE` и `operator@BRANCH` — разные идентификаторы.

### Автоматическое создание оператора

Если включён параметр `sso.create_new_agent_if_not_exist=true`, то при первом успешном входе через **SSO Webim** создаёт оператора и дополнительно устанавливает в настройках оператора (внутренний блок `config`):

  * `config.allow_sso=true` — разрешён вход через **SSO**;

  * `config.allow_common_auth=true` — разрешён вход по электронной почте и паролю.

Если автоматическое создание отключено, оператор должен быть создан заранее, а его `sso_username` должен быть заполнен администратором в карточке оператора.

### Данные Webim получаемые из Active Directory

При обращении к **LDAP Webim** получает:

  * `sAMAccountName` — логин пользователя внутри домена;

  * `mail` — электронная почта;

  * `displayName` — имя;

  * список групп пользователя — из атрибута, заданного в `security_group_attribute` соответствующего объекта `ldap.domains` (`memberOf`), в виде **DN**.

### Данные обновляемые у оператора

По результатам **SSO**/синхронизации **Webim** обновляет данные оператора:

  * **Имя** (`name`) — по `displayName`;

  * **Электронную почту** (`email`) — по `mail`;

  * **Идентификатор SSO** (`config.sso_username`) — из `sAMAccountName` и имени домена в формате `sAMAccountName@DOMAIN`;

  * **Роли, отделы и наблюдаемые отделы** — по сопоставленным группам безопасности **Webim** (см. [Операторы и Active Directory](https://webim.ru/kb/for-admins/active-directory-operators-and-security-groups.html));

  * служебный признак `config.is_updated_by_sso=true` (чтобы **Webim** мог отличать учётные записи, которые управляются через **Active Directory**).

## Периодическая и ручная синхронизация

### Периодическая синхронизация

Если `sso.enable_periodic_synchronization = true`, **Webim** запускает фоновую синхронизацию данных операторов с **Active Directory**.

  * Интервал фиксированный: **1 раз в час**.

  * Изменить интервал нельзя.

### Ручная синхронизация

Если `sso.allow_manual_synchronization = true`, в интерфейсе появляется команда ручной синхронизации: в разделе **Операторы** → кнопка с подсказкой **«Синхронизация данных с Active Directory»**.

![Синхронизация данных с Active Directory](https://webim.ru/kb/img/for-admins/active-directory/operator-sso-synchronization.webp){ style="width: 1350px; max-width: 100%" }

При синхронизации **Webim** определяет домен по части идентификатора после символа `@` и использует настройки соответствующего объекта `ldap.domains`. Поэтому у каждого синхронизируемого оператора `sso_username` должен быть задан в формате `sAMAccountName@DOMAIN`.

## Требование Kafka для синхронизации

Периодическая/ручная синхронизация реализована через внутренние периодические задачи **Kafka**.

Если включена `sso.enable_periodic_synchronization` или `sso.allow_manual_synchronization`, убедитесь, что **Kafka** подключена в вашем стенде.

### Минимальная конфигурация для Kafka

**Kafka** требуется, только если в account config включены:

  * `sso.enable_periodic_synchronization=true` — периодическая синхронизация;

  * и/или `sso.allow_manual_synchronization=true` — ручная синхронизация.

Ниже приведён минимальный пример для стенда на `docker-compose`.

  1. Включите **Kafka** для сайта. Добавьте строку `kafka` в файл `.bucket`, чтобы сервисы Webim стартовали с поддержкой **Kafka-задач**.

  1. Добавьте сервисы **Kafka** и **ZooKeeper** в `docker-compose.yml`. В минимальной конфигурации **Kafka** запускается вместе с **ZooKeeper**. Пример:

    ```yaml
    services:
      zookeeper:
        container_name: "zookeeper"
        image: confluentinc/cp-zookeeper:7.2.1
        environment:
          ZOOKEEPER_CLIENT_PORT: 2181
          ZOOKEEPER_TICK_TIME: 2000
        ports:
          - "2181:2181"

      kafka:
        container_name: "kafka"
        image: confluentinc/cp-kafka:7.2.1
        depends_on:
          - zookeeper
        ports:
          - "9092:9092"
        environment:
          KAFKA_BROKER_ID: 1
          KAFKA_ZOOKEEPER_CONNECT: "zookeeper:2181"

          KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "PLAINTEXT:PLAINTEXT,PLAINTEXT_INTERNAL:PLAINTEXT"
          KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://localhost:9092,PLAINTEXT_INTERNAL://kafka:29092"
          KAFKA_LISTENERS: "PLAINTEXT://0.0.0.0:9092,PLAINTEXT_INTERNAL://0.0.0.0:29092"
          KAFKA_INTER_BROKER_LISTENER_NAME: "PLAINTEXT_INTERNAL"

          KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
          KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
          KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
    ```

  1. Укажите адрес **Kafka** в конфигурации `admin-backend`. Для `admin-backend` задайте файл `configs/kafka.json`. Пример:

    ```json
    {
      "kafka": {
        "address": "kafka:29092",
        "periodic_task_timeout_seconds": 10,
        "periodic_task_poll_interval_seconds": 1
      }
    }
    ```

    Поля:

      * `address` — адрес брокера **Kafka**, который будет использовать **Admin Backend**.

      * `periodic_task_timeout_seconds` — таймаут выполнения задачи (в секундах).

      * `periodic_task_poll_interval_seconds` — интервал опроса очереди задач (в секундах).

  1. Проверьте доступность **Kafka** из контейнера `admin-backend`.

    1. Убедитесь, что контейнер **Kafka** запущен:

        ```bash
        docker ps | grep kafka
        ```

    1. Проверьте доступность порта **Kafka** из сети `docker-compose`:

        ```bash
        docker exec -it <admin-backend-container> sh -lc "nc -zv kafka 29092"
        ```

        Если `nc` отсутствует в образе, выполните проверку с хоста:

        ```bash
        nc -zv localhost 9092
        ```

---

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