# Настройка Kerberos В этой статье описаны настройки Kerberos для интеграции **Webim** с **Active Directory**: * подготовка сервисной учётной записи и **SPN**; * создание и проверка **keytab-файла**; * конфигурация Kerberos на сервере **Webim**; * параметры блока `kerberos` в [редакторе настроек аккаунта (account config)](https://webim.ru/kb/for-admins/service-pages/account-config-editor.html); * базовая проверка работоспособности. ## Термины * **SPN (Service Principal Name)** — имя службы в домене, по которому контроллер домена выдаёт **Kerberos-билет** для конкретного сервиса. В Active Directory **SPN** хранится как запись, привязанная к сервисной учётной записи. * **Принципал Kerberos** — полное имя субъекта в **Kerberos**, вида `/@`. * **keytab** — файл, содержащий ключ(и) для одного или нескольких принципалов. **Keytab** позволяет сервису **Webim** аутентифицироваться в **Kerberos** и расшифровывать билеты, не запрашивая пароль у администратора при каждом запуске. * **keytab-файл Webim** — конкретный файл `keytab`, который читает **Webim** на сервере: `/etc/webim/krb5.keytab`. В нём должны быть ключи для `HTTP/@`. * **FQDN** — полное доменное имя сервиса **Webim**, по которому операторы открывают **Webim** в браузере (например, `chat.example.com`). * **REALM** — имя домена **Kerberos** (как правило, это имя домена **Active Directory** в верхнем регистре, например `EXAMPLE.LOCAL`). * **KVNO (Key Version Number)** — номер версии ключа принципала. При смене пароля сервисной учётной записи `KVNO` увеличивается, и `keytab` нужно обновить. ## Ограничения * **Kerberos-конфигурация** сервиса **Webim** привязана к **одному** `REALM`: `SPN` регистрируется в одном домене, а `keytab` содержит ключи для принципала этого домена. Само по себе это не ограничивает количество доменов, из которых приходят операторы: домены перечисляются в массиве `ldap.domains` (см. [«настройка LDAP»](https://webim.ru/kb/devops/active-directory/ldap-configuration.html)). Чтобы операторы из остальных доменов могли входить через **SSO**, между этими доменами и доменом сервиса должны быть настроены доверительные отношения (**trust**). * 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** ```bash apt install krb5-user libsasl2-modules-gssapi-mit ldap-utils ``` **RHEL/CentOS/Alma/Rocky** ```bash dnf install krb5-workstation cyrus-sasl-gssapi openldap-clients ``` Проверка, что утилиты доступны в системе: ```bash 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 } **SPN** — это запись в **Active Directory**, которая связывает имя службы **Kerberos** с конкретной сервисной учётной записью. Когда оператор открывает **Webim**, браузер запрашивает у контроллера домена **Kerberos-билет** для службы `HTTP/` — и контроллер домена выдаёт билет только если в домене настроен соответствующий **SPN**. Если **SPN** не создан или привязан не к той учётной записи, **Kerberos-аутентификация** через **SSO** работать не будет. Для веб-сервера **Webim** необходимо зарегистрировать **SPN** вида: ```text HTTP/ ``` где `` — полное доменное имя, по которому операторы обращаются к **Webim** (например, `chat.example.com`). **SPN** привязывается к сервисной учётной записи (например, `wbm_service`). На Windows **Active Directory SPN** можно зарегистрировать командой `setspn`, либо он будет зарегистрирован автоматически при генерации `keytab` через `ktpass`. Пример (Windows Active Directory): ```cmd setspn -A HTTP/chat.example.com EXAMPLE\wbm_service ``` ## Keytab-файл для сервиса Webim **Keytab** — это файл с ключами **Kerberos** для сервисного принципала `HTTP/@`. **Webim** использует `keytab`, чтобы принимать **Kerberos-билеты** от браузера и проверять, что билет выдан именно для этого сервиса, не запрашивая пароль сервисной учётной записи при каждом запуске. Если `keytab` отсутствует, устарел (например, после смены пароля сервисной учётной записи) или содержит ключи для другого **FQDN/REALM**, вход через **SSO** работать не будет. ### Расположение keytab-файла **Webim** использует **keytab-файл**: ```text /etc/webim/krb5.keytab ``` Файл должен содержать ключи для принципала `HTTP/`. !!! Warning "Внимание!" Любой пользователь, имеющий доступ на чтение **keytab-файла**, может использовать содержащиеся в нём ключи. Ограничьте права доступа (например, `600`) и обеспечьте корректного владельца файла. Пример: ```bash chown root:root /etc/webim/krb5.keytab chmod 600 /etc/webim/krb5.keytab ``` ### Создание keytab на контроллере домена Windows 1. На контроллере домена выполните `ktpass` для генерации `keytab` и привязки **SPN**: ```cmd ktpass /out C:\webim.keytab ^ /mapuser EXAMPLE\svc_webim ^ /princ HTTP/chat.example.com@EXAMPLE.LOCAL ^ /pass <пароль_учётной_записи> ^ /ptype KRB5_NT_PRINCIPAL ^ /crypto All ``` 1. Передайте файл `webim.keytab` на сервер **Webim** и разместите как `/etc/webim/krb5.keytab`. ### Приведение keytab к нужному набору шифрований Если исходный `keytab` содержит лишние записи/шифрования, можно сформировать итоговый `keytab` через `ktutil`. Пример: ```bash ktutil rkt /path/to/webim.keytab # чтение исходного keytab list # просмотр содержимого delent <номер_записи> # удаление лишних записей wkt /etc/webim/krb5.keytab # запись итогового keytab quit ``` ### Проверка содержимого keytab Проверка `keytab`: ```bash klist -kKe /etc/webim/krb5.keytab ``` Проверьте: * в `keytab` есть записи для `HTTP/@`; * присутствуют ожидаемые типы шифрования; * **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** использует конфигурационный файл: ```text /etc/webim/krb5.conf ``` Пример содержимого: ```ini [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`, сервер **не валидирует** билет и возвращает его текущее значение. | Пример: ```json { "kerberos": { "kerberos_service_name": "HTTP", "dev_mode": false } } ``` ## Проблемы и возможные ошибки Типовые ошибки (расхождение времени, неверный **SPN**, проблемы с `keytab` и т.п.) разобраны в статье [«Интеграция с Active Directory: диагностика и типовые ошибки»](https://webim.ru/kb/devops/active-directory/troubleshooting.html). Также, можете ознакомиться с официальной [документацией](https://docs.microsoft.com/en-us/troubleshoot/developer/webapps/iis/www-authentication-authorization/troubleshoot-kerberos-failures-ie#things-to-check-if-kerberos-authentication-fails) Microsoft. --- Источник: https://webim.ru/kb/devops/active-directory/kerberos-configuration.html