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

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

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

параметры sso в редакторе настроек аккаунта (account config);
режимы авторизации и их влияние на вход по паролю и по SSO;
периодическая и ручная синхронизация данных операторов с Active Directory.

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

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

Настроить Kerberos на стороне инфраструктуры Webim (см. Настройка Kerberos).
Настроить подключение к Active Directory по LDAP (см. Настройка LDAP).
Иметь доступ к Редактору настроек аккаунта (account config), чтобы внести параметры sso, ldap, kerberos (см. Редактор настроек аккаунта (account config)).

Термины

Настройки оператора — часть данных оператора, где 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 из интерфейса.

Пример:

{
  "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:

{
  "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-вход и вход по электронной почте и паролю	—

Важно!

Дополнительное правило для входа по электронной почте и паролю в режиме 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) задано 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);
служебный признак 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».

При синхронизации 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.

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

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

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

Укажите адрес Kafka в конфигурации admin-backend. Для admin-backend задайте файл configs/kafka.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 — интервал опроса очереди задач (в секундах).
Проверьте доступность Kafka из контейнера admin-backend.
1. Убедитесь, что контейнер Kafka запущен:
```
docker ps | grep kafka
```
2. Проверьте доступность порта Kafka из сети docker-compose:
```
docker exec -it <admin-backend-container> sh -lc "nc -zv kafka 29092"
```
  Если nc отсутствует в образе, выполните проверку с хоста:
```
nc -zv localhost 9092
```