Skip to content

Настройка Kerberos

В этой статье описаны настройки Kerberos для интеграции Webim с Active Directory:

  • подготовка сервисной учётной записи и SPN;

  • создание и проверка keytab-файла;

  • конфигурация Kerberos на сервере Webim;

  • параметры блока kerberos в редакторе настроек аккаунта (account config);

  • базовая проверка работоспособности.

Термины

  • SPN (Service Principal Name) — имя службы в домене, по которому контроллер домена выдаёт Kerberos-билет для конкретного сервиса. В Active Directory SPN хранится как запись, привязанная к сервисной учётной записи.

  • Принципал Kerberos — полное имя субъекта в Kerberos, вида <service>/<FQDN>@<REALM>.

  • keytab — файл, содержащий ключ(и) для одного или нескольких принципалов. Keytab позволяет сервису Webim аутентифицироваться в Kerberos и расшифровывать билеты, не запрашивая пароль у администратора при каждом запуске.

  • keytab-файл Webim — конкретный файл keytab, который читает Webim на сервере: /etc/webim/krb5.keytab. В нём должны быть ключи для HTTP/<FQDN>@<REALM>.

  • FQDN — полное доменное имя сервиса Webim, по которому операторы открывают Webim в браузере (например, chat.example.com).

  • REALM — имя домена Kerberos (как правило, это имя домена Active Directory в верхнем регистре, например EXAMPLE.LOCAL).

  • KVNO (Key Version Number) — номер версии ключа принципала. При смене пароля сервисной учётной записи KVNO увеличивается, и keytab нужно обновить.

Ограничения

  • Для одного аккаунта Webim поддерживается работа с одним доменом Active Directory (одним REALM).

  • Kerberos-вход завязан на конкретный FQDN, который использует оператор при открытии Webim. Если один и тот же Webim открывают по разным именам (например, chat.example.com и chat.internal.example.com), для каждого имени потребуется корректная Kerberos-конфигурация (SPN/принципал и ключи). В рамках этой статьи предполагается, что используется один FQDN.

  • Работоспособность Kerberos зависит от инфраструктурных условий:

    • корректно работает DNS (сервер Webim должен разрешать имена домена и находить контроллер домена);

    • время на сервере Webim и на контроллере домена синхронизировано (иначе Kerberos-аутентификация будет завершаться с ошибкой).

  • Если изменился пароль сервисной учётной записи, к которой привязан SPN, keytab становится неактуальным (изменится KVNO) и его нужно пересоздать.

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

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

Минимальные требования:

  • Установлена версия Webim 10.8 или новее.

  • На сервере установлены Kerberos-утилиты и модули GSSAPI/SASL, а также утилиты LDAP.

Примеры установки пакетов:

Debian/Ubuntu

apt install krb5-user libsasl2-modules-gssapi-mit ldap-utils

RHEL/CentOS/Alma/Rocky

dnf install krb5-workstation cyrus-sasl-gssapi openldap-clients

Проверка, что утилиты доступны в системе:

command -v kinit klist ktutil

Сетевой доступ с сервера Webim к контроллеру домена (минимально необходимые порты):

  • DNS: TCP/UDP 53

  • NTP: UDP 123

  • Kerberos: TCP/UDP 88

  • LDAP: TCP 389 или LDAPS: TCP 636

Также убедитесь, что на сервере Webim включена синхронизация времени и расхождение с контроллером домена отсутствует (NTP или иной механизм).

Со стороны Active Directory

Требования:

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

  • Настроен DNS (включая записи, по которым сервер Webim сможет находить контроллер домена).

  • Создана сервисная учётная запись, которая будет использоваться для Kerberos-настройки и генерации keytab.

SPN (Service Principal Name)

SPN — это запись в Active Directory, которая связывает имя службы Kerberos с конкретной сервисной учётной записью. Когда оператор открывает Webim, браузер запрашивает у контроллера домена Kerberos-билет для службы HTTP/<FQDN> — и контроллер домена выдаёт билет только если в домене настроен соответствующий SPN. Если SPN не создан или привязан не к той учётной записи, Kerberos-аутентификация через SSO работать не будет.

Для веб-сервера Webim необходимо зарегистрировать SPN вида:

HTTP/<FQDN>

где <FQDN> — полное доменное имя, по которому операторы обращаются к Webim (например, chat.example.com).

SPN привязывается к сервисной учётной записи (например, wbm_service). На Windows Active Directory SPN можно зарегистрировать командой setspn, либо он будет зарегистрирован автоматически при генерации keytab через ktpass.

Пример (Windows Active Directory):

setspn -A HTTP/chat.example.com EXAMPLE\wbm_service

Keytab-файл для сервиса Webim

Keytab — это файл с ключами Kerberos для сервисного принципала HTTP/<FQDN>@<REALM>. Webim использует keytab, чтобы принимать Kerberos-билеты от браузера и проверять, что билет выдан именно для этого сервиса, не запрашивая пароль сервисной учётной записи при каждом запуске. Если keytab отсутствует, устарел (например, после смены пароля сервисной учётной записи) или содержит ключи для другого FQDN/REALM, вход через SSO работать не будет.

Расположение keytab-файла

Webim использует keytab-файл:

/etc/webim/krb5.keytab

Файл должен содержать ключи для принципала HTTP/<FQDN>.

Внимание!

Любой пользователь, имеющий доступ на чтение keytab-файла, может использовать содержащиеся в нём ключи. Ограничьте права доступа (например, 600) и обеспечьте корректного владельца файла. Пример:

chown root:root /etc/webim/krb5.keytab
chmod 600 /etc/webim/krb5.keytab

Создание keytab на контроллере домена Windows

  1. На контроллере домена выполните ktpass для генерации keytab и привязки SPN:

    ktpass /out C:\webim.keytab ^
      /mapuser EXAMPLE\svc_webim ^
      /princ HTTP/chat.example.com@EXAMPLE.LOCAL ^
      /pass <пароль_учётной_записи> ^
      /ptype KRB5_NT_PRINCIPAL ^
      /crypto All

  2. Передайте файл webim.keytab на сервер Webim и разместите как /etc/webim/krb5.keytab.

Приведение keytab к нужному набору шифрований

Если исходный keytab содержит лишние записи/шифрования, можно сформировать итоговый keytab через ktutil.

Пример:

ktutil
rkt /path/to/webim.keytab     # чтение исходного keytab
list                          # просмотр содержимого
delent <номер_записи>         # удаление лишних записей
wkt /etc/webim/krb5.keytab    # запись итогового keytab
quit

Проверка содержимого keytab

Проверка keytab:

klist -kKe /etc/webim/krb5.keytab

Проверьте:

  • в keytab есть записи для HTTP/<FQDN>@<REALM>;

  • присутствуют ожидаемые типы шифрования;

  • KVNO (Key Version Number) актуален (после смены пароля сервисной учётной записи keytab нужно пересоздавать).

Пример вывода klist для keytab Webim:

Keytab name: FILE:/etc/webim/krb5.keytab
KVNO Principal
---- --------------------------------------------------------------------------
  19 HTTP/chat.example.com@EXAMPLE.LOCAL (DEPRECATED:arcfour-hmac)  (0x23bc77fafa89c44ca4916e1cb3c141ee)
  18 HTTP/chat.example.com@EXAMPLE.LOCAL (aes256-cts-hmac-sha1-96)  (0x76774af9c0cc185c65db51e3056b3e0898a59ead9004cbc14de3c13b20f236b4)

Конфигурация Kerberos на сервере Webim

Файл krb5.conf

Webim использует конфигурационный файл:

/etc/webim/krb5.conf

Пример содержимого:

[libdefaults]
  default_realm = EXAMPLE.LOCAL

  default_tkt_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  default_tgs_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  permitted_enctypes   = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96

  kdc_timesync = 1
  ccache_type  = 4
  forwardable  = true
  proxiable    = true
  rdns         = false
  fcc-mit-ticketflags = true

[realms]
  EXAMPLE.LOCAL = {
    kdc          = dc1.example.local
    admin_server = dc1.example.local
    supported_enctypes = aes256-cts-hmac-sha1-96 aes128-cts-hmac-sha1-96
  }

[domain_realm]
  .example.local = EXAMPLE.LOCAL
  example.local  = EXAMPLE.LOCAL

Параметры Kerberos в account config

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

Поле Тип Значение по умолчанию Описание
kerberos_service_name string — Имя Kerberos-сервиса для валидации билетов на стороне Webim (например, HTTP).
dev_mode boolean — Если true, сервер не валидирует билет и возвращает его текущее значение.

Пример:

{
  "kerberos": {
    "kerberos_service_name": "HTTP",
    "dev_mode": false
  }
}

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

Типовые ошибки (расхождение времени, неверный SPN, проблемы с keytab и т.п.) разобраны в статье «Интеграция с Active Directory: диагностика и типовые ошибки».

Также, можете ознакомиться с официальной документацией Microsoft.

Последнее обновление страницы: 21 марта 2026 г.