# Диагностика и типовые ошибки

В статье собраны типовые ошибки при интеграции Webim с Active Directory и рекомендации по диагностике.

  * проблемы Kerberos и SSO

  * ошибки, связанные с keytab и SPN

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

  * ошибки, связанные с режимами авторизации

  * ошибки валидации операторов и данных из Active Directory

  * проблемы ручной и периодической синхронизации

## Где смотреть

### Логи Webim

Для диагностики обычно достаточно логов:

  * Admin Backend (SSO и синхронизация операторов)

  * системных логов ОС (время/NTP, сеть, TLS)

  * при необходимости — логов инфраструктуры (Kafka, контроллер домена)

**Docker / Docker Compose**

  * Логи контейнера Admin Backend:

    ```
    docker logs <admin_backend_container> --tail=200
    docker logs <admin_backend_container> -f
    ```

  * В docker compose:

    ```
    docker compose logs -f --tail=200 <service_name>
    ```

**Установка на сервер**

В установках Webim часто используются логи в каталоге `/var/log/pro/` (например, `/var/log/pro/tornado-*.log`):

  ```
  tail -n 200 /var/log/pro/<имя_лога>.log
  tail -f /var/log/pro/<имя_лога>.log
  ```

### История действий

История действий (action log) фиксирует ключевые события и изменения в аккаунте (в том числе административные действия и ошибки операций). См. статью [История действий (action log)](https://webim.ru/kb/for-admins/action-log.html).

### Логи домена и ОС

Дополнительно используются:

  * журнал безопасности/системный журнал на контроллере домена (Kerberos, SPN, учетные записи)

  * системные логи на сервере Webim (NTP, сеть, TLS/сертификаты)

## SSO и Kerberos

!!! Warning "Важно"
    Настройка доменных политик и браузеров (зоны безопасности, разрешения Kerberos/Negotiate, ограничения NTLM) зависит от инфраструктуры компании и находится вне рамок документации Webim. Со стороны Webim задача диагностики — определить, что именно приходит на сервер и какая ошибка фиксируется в логах.

### Браузер просит логин и пароль

**Симптомы**

  * автоматическая аутентификация не происходит

  * появляется диалог ввода логина/пароля

  * в логах нет признаков успешной обработки Kerberos-билета

**Причины**

  * браузер не настроен на Integrated Windows Authentication (Kerberos/Negotiate)

  * клиент отправляет не Kerberos (например, NTLM)

**Как проверить**

  1. Проверьте логи Admin Backend на ошибки Kerberos/GSSAPI.

  1. Если в параметре `kerberos_ticket` видно значение, похожее на NTLM (часто начинается с `TlRMTVNT...`), значит, Kerberos не используется.

**Как решить**

  1. Добавьте домен Webim в список доверенных для Kerberos/Negotiate (whitelist/Trusted sites — в зависимости от браузера и политики компании).

  1. Убедитесь, что доступ к Webim выполняется по FQDN, для которого настроен SPN.

### GSS error

**Симптомы**

В логах Webim встречаются сообщения вида:

  * `GSS error: GSSError(('An unsupported mechanism was requested', ...))`

**Причины**

  * клиент отправляет не Kerberos (например, NTLM)

  * Kerberos запрещён политиками домена/зоны

**Пример логов**

  ```
  [W 250826 14:54:05 +0300 access_log:35] 401 "GET /api/auth/v1/w/sso-signin HTTP/1.0" (X-Account-Name: accountname) (X-Real-Ip: 192.168.110.151) (Remote: 172.16.0.100) (Time: 0.010437)
  [E 250826 14:54:50 +0300 service:78] GSS error: GSSError(('An unsupported mechanism was requested', 65536), ('Unknown error', 0))
  [E 250826 14:54:50 +0300 access_log:35] 500 "GET /internal/admin-backend/sso/get-user-entry?kerberos_ticket=TlRMTVNTUAABAAAAl4II4gAAAAAAAAAAAAAAAAAAAAAKAGNFAAAADw%3D%3D HTTP/1.0" (X-Account-Name: accountname) (X-Real-Ip: 172.16.0.7) (Remote: 172.16.0.100) (Time: 0.003138)
  [W 250826 14:54:50 +0300 access_log:35] 403 "GET /api/auth/v1/w/sso-signin HTTP/1.0" (X-Account-Name: accountname) (X-Real-Ip: 192.168.110.151) (Remote: 172.16.0.100) (Time: 0.011826)
  ```

**Как проверить**

  1. Убедитесь, что браузер настроен на Kerberos/Negotiate для домена, на котором открыт Webim.

  1. Убедитесь, что для домена Webim корректно настроен SPN (см. раздел про SPN).

**Как решить**

  1. Настройте браузер так, чтобы он отправлял Kerberos-ticket для домена Webim.

  1. Если Kerberos запрещён политиками, согласуйте изменение политик или используйте режим `sso_and_common_auth`, чтобы оставить запасной вход по логину/паролю.

### Время и NTP

**Симптомы**

  * Kerberos-аутентификация не проходит

  * ошибки Kerberos воспроизводятся нестабильно

**Причины**

  * рассинхронизация времени между сервером Webim и контроллером домена

**Как проверить**

  1. Сравните время и часовой пояс на сервере Webim и на контроллере домена.

  1. Проверьте состояние NTP и ошибки синхронизации.

**Как решить**

  1. Настройте синхронизацию времени (NTP) на сервере Webim.

  1. Убедитесь, что сервер Webim и контроллер домена синхронизируются с согласованными источниками времени.

## Keytab и SPN

### KVNO или enctype

**Симптомы**

  * SSO не работает

  * в логах есть ошибки расшифровки ticket, KVNO или тип шифрования

**Причины**

  * KVNO изменился на стороне AD, а keytab на сервере Webim не обновили

  * в keytab нет записи с нужным типом шифрования для актуального KVNO

**Пример логов**

  ```
  Failed to decrypt AP-REQ ticket: -1765328340/Request ticket server HTTP/docker-[hosted.site.ru@WEBIM.LOCAL](mailto:hosted.site.ru@WEBIM.LOCAL) kvno 14 found in keytab but not with enctype rc4-hmac
  ```

**Как проверить**

  1. Проверьте содержимое keytab на сервере Webim:

    ```
    klist -kKe /etc/webim/krb5.keytab
    ```

  1. Проверьте наличие принципала `HTTP/<FQDN>@<REALM>` и актуальность KVNO.

**Как решить**

  1. Пересоздайте keytab на стороне AD.

  1. Обновите файл keytab на сервере Webim.

  1. Убедитесь, что keytab содержит ключи для алгоритмов, разрешённых политиками домена (например, rc4-hmac и/или aes256).

### SPN или realm

**Симптомы**

  * Kerberos-ticket не принимается сервером

  * SSO работает только по одному адресу, а по другому — нет

**Причины**

  * SPN привязан к другой учетной записи

  * в keytab другой принципал (не совпадает с тем, что использует клиент)

  * неверно задан default_realm

**Как проверить**

  1. Проверьте SPN в домене (через `setspn` или инструменты AD).

  1. Проверьте принципалы в keytab:

    ```
    klist -kKe /etc/webim/krb5.keytab
    ```

  1. Проверьте `default_realm` и блок `[realms]` в `/etc/webim/krb5.conf`.

**Как решить**

  1. Исправьте SPN так, чтобы он соответствовал FQDN, по которому открывается Webim.

  1. Пересоздайте keytab под правильный принципал и обновите его на сервере Webim.

  1. Исправьте настройки realm в `krb5.conf`.

## LDAP

### Нет подключения

**Симптомы**

  * тайм-ауты, отказ в подключении, TLS-ошибки

**Причины**

  * неверный URL/порт

  * сетевые ограничения

  * при LDAPS — недоверенный сертификат контроллера домена на сервере Webim

**Как проверить**

  1. Проверьте доступность хоста/порта с сервера Webim:

    ```
    nc -zv <ldap_host> <port>
    ```

  1. Проверьте `url` и `use_ssl` в объекте нужного домена в массиве `ldap.domains`.

**Как решить**

  1. Исправьте URL/порт в настройках LDAP.

  1. Настройте маршрутизацию/правила FW.

  1. При LDAPS добавьте CA сертификата в доверенные на сервере Webim.

### Пользователь не найден

**Симптомы**

  * в логах: пользователь не найден по имени

**Причины**

  * пользователь вне области поиска `search_base`, настроенной для его домена в `ldap.domains`

  * у пользователя не заполнен `sAMAccountName`

  * домен отсутствует в `ldap.domains` или его параметр `name` не соответствует домену пользователя

**Пример логов**

  ```
  [E 250825 18:43:11 +0300 service:132] User not found; username=Администратор
  ```

**Как проверить**

  1. Найдите объект домена в `ldap.domains` и проверьте его `name` и `search_base`: область поиска должна включать OU, где находится пользователь.

  1. Убедитесь, что у пользователя заполнен `sAMAccountName`.

**Как решить**

  1. Исправьте `name` или `search_base` в объекте соответствующего домена.

  1. Заполните или исправьте `sAMAccountName` в AD.

### Группы не совпадают

**Симптомы**

  * пользователь входит, но роли/права не назначаются

**Причины**

  * ошибка в `security_group_pattern` соответствующего объекта `ldap.domains`

  * неверный `security_group_attribute` соответствующего объекта `ldap.domains` или атрибут не заполнен

**Как проверить**

  1. Сравните DN групп, которые приходят в `memberOf`, с тем, что формирует `security_group_pattern` для нужного домена.

  1. Учитывайте регистр и формат DN (строковое сравнение должно совпадать полностью).

**Как решить**

  1. Исправьте `security_group_pattern` в объекте нужного домена так, чтобы он формировал DN в том же виде, как возвращает AD.

  1. Исправьте `security_group_attribute` в объекте нужного домена (обычно `memberOf`).

## Режимы входа

### SSO выключен

**Симптомы**

  * на странице входа нет SSO или он не запускается

**Причины**

  * `sso.enabled = false`

  * `sso.auth_mode = only_common_auth`

**Как проверить**

  1. Проверьте настройки SSO в account-config.

  1. Проверьте `sso.auth_mode`.

**Как решить**

  1. Включите `sso.enabled`.

  1. Установите `sso.auth_mode` в `only_sso` или `sso_and_common_auth`.

### Оператор не допускается к SSO

**Симптомы**

  * SSO включён, но конкретный оператор не входит

**Причины**

  * у оператора выключен `sso.allow_sso`

  * не задан `sso_username`

**Как проверить**

  1. В карточке оператора (вкладка настроек SSO) проверьте:

    * `sso.allow_sso`

    * `sso_username`

**Как решить**

  1. Включите `sso.allow_sso` для оператора.

  1. Заполните `sso_username` значением в формате `sAMAccountName@DOMAIN`, например `operator@EXAMPLE`. Часть `DOMAIN` должна совпадать с полем `name` соответствующего объекта в массиве `ldap.domains`.

## Валидация оператора

### sso_bad_request

**Симптомы**

  * при создании/обновлении оператора через SSO возвращается 400

  * в логах есть ошибки валидации полей

**Причины**

  * из AD приходят неполные или некорректные данные (например, нет имени)

  * email некорректный или конфликтует с существующим оператором

**Пример логов**

  ```
  [W 250901 18:44:52 +0300 service:620] Validating name; Value: None ; Type: <class 'NoneType'>
  [W 250901 18:44:52 +0300 service:620] Validating email; Value: [test@test.ru](mailto:test@test.ru) ; Type: <class 'str'>
  [W 250901 18:44:52 +0300 access_log:35] 400 "PUT /internal/admin-backend/sso/agents/8 HTTP/1.0" (X-Account-Name: accountname) (X-Real-Ip: 172.16.0.5) (Remote: 172.16.0.100) (Time: 0.002736)
  [W 250901 18:44:52 +0300 service:64] SSOAgentService: Validation error: {'code': 'agent_validation_error', 'attributes': {'fields_errors': {'name': [{'rule': 'has_suitable_type', 'attributes': None}]}}}
  ```

**Как проверить**

  1. Проверьте, что в AD заполнены `displayName` и `mail`.

  1. Проверьте, что email уникален среди операторов Webim.

**Как решить**

  1. Заполните/исправьте данные пользователя в AD.

  1. Устраните дубликаты email в Webim или исправьте email в AD.

## Синхронизация

### Не работает периодическая

**Симптомы**

  * изменения в AD не отражаются в Webim

**Причины**

  * `sso.enable_periodic_synchronization = false`

  * Kafka не настроена/недоступна

  * Admin Backend запущен без `--kafka-connection`

**Как проверить**

  1. В account-config проверьте `sso.enable_periodic_synchronization`.

  1. Проверьте параметры запуска Admin Backend: есть ли `--kafka-connection=<connection_name>`.

  1. Проверьте `/etc/webim/kafka.json` и наличие соединения `<connection_name>`.

**Как решить**

  1. Включите `sso.enable_periodic_synchronization`.

  1. Настройте Kafka и соединение в `/etc/webim/kafka.json`.

  1. Перезапустите Admin Backend с параметром `--kafka-connection`.

### Ошибка Sync data with Active Directory

**Симптомы**

  * при нажатии Sync появляется ошибка

  * в логах есть traceback обработки запроса

**Причины**

  * не задано подключение к Kafka, поэтому синхронизация не может быть поставлена в очередь

**Пример логов**

  ```
  [E 250721 11:43:22 +0300 exception_handler:63] Request processing failed with exception
  Traceback (most recent call last):
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/admin_backend/entrypoints/web/root/middlewares/exception_handler.py", line 35, in _catch_agent_api_exceptions
  return await handler(request)
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/admin_backend/entrypoints/web/root/middlewares/extract_request_data.py", line 39, in extract_request_data
  response = await handler(request)
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/admin_backend/entrypoints/web/root/middlewares/prepare_context.py", line 107, in **call**
  return await handler(request)
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/admin_backend/entrypoints/web/root/shared/middlewares/default_headers.py", line 20, in **call**
  response = await handler(request)
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/admin_backend/entrypoints/web/root/middlewares/redirect_to_login_domain.py", line 44, in **call**
  return await handler(request)
  File "/opt/webim/envs/eta/admin_backend/lib/python3.10/site-packages/aiohttp/web_middlewares.py", line 117, in impl
  return await handler(request)
  ```

**Как проверить**

  1. Проверьте, что Admin Backend запущен с `--kafka-connection=<connection_name>`.

  1. Проверьте, что `/etc/webim/kafka.json` содержит соединение `<connection_name>`.

  1. Проверьте доступность Kafka с хоста/контейнера Admin Backend.

**Как решить**

  1. Настройте Kafka и файл `/etc/webim/kafka.json`.

  1. Перезапустите Admin Backend с корректным `--kafka-connection`.

  1. Повторите Sync.

---

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