Использование метода аутентификации GSSAPI (Kerberos)#

В программном компоненте есть возможность включения метода аутентификации GSSAPI (он же - Kerberos) для SMTP- и IMAP-соединений. Когда метод аутентификации GSSAPI включён, перед отправкой и чтением писем программный компонент будет обращаться к Kerberos-серверу с логином и паролем почтового ящика для получения токена. Далее этот токен будет использоваться для аутентификации с почтовым сервером.

Если метод аутентификации GSSAPI отключён, используется метод аутентификации по умолчанию - LOGIN.

Настройка метода аутентификации GSSAPI#

Чтобы настроить метод аутентификации GSSAPI, необходимо внести изменения в файлы mail-core.conf, mail-receive-letters-reader.conf и mail-egress-gateway.istio.all.conf.

mail-core.conf#

В файле mail-core.conf указываются следующие параметры для настройки метода аутентификации GSSAPI (Kerberos):

mail_core.ose.gssapi.smtp.enabled - флаг включения метода аутентификации GSSAPI для SMTP-соединений. Указывается значение true или false. Если указано false, будет использоваться метод аутентификации LOGIN;
mail_core.ose.gssapi.imap.enabled - флаг включения метода аутентификации GSSAPI для IMAP-соединений. Указывается значение true или false. Если указано false, будет использоваться метод аутентификации LOGIN;
mail_core.ose.gssapi.kerberosRealm - название Kerberos Realm’а, по которому будет происходить аутентификация через GSSAPI;
mail_core.ose.configmap.data.application_config.kerberos.virtualIp - виртуальный IP для маршрутизации трафика до Kerberos хостов;
mail_core.ose.configmap.data.application_config.retry.kerberos.count - количество попыток отправки письма (1 = одна попытка отправки без переотправки). Минимальное значение 1;
mail_core.ose.configmap.data.application_config.retry.kerberos.delay - задержка между попытками ретраев в миллисекундах;
mail_core.ose.configmap.data.application_config.retry.kerberos.errors - тексты ошибок, при которых применяется переотправка (разделитель ;;).

При каждом запросе на отправку письма выполняется два запроса к Kerberos серверу: сначала выполняется первый запрос на получение TGT-тикета (Ticket Granting Ticket), после чего с помощью этого тикета выполняется второй запрос на получение сервисного тикета. Сервисный тикет, полученный со вторым запросом, используется для авторизации к почтовому серверу.
Ниже приведены примеры ошибок, которые могут возникать при обращении к Kerberos серверу:
- «Connection refused», «Connection reset», «Cannot get a KDC reply» - если при выполнении первого запроса произошла ошибка подключения;
- «Authentication failed» - если первый запрос выполнился успешный, а второй завершился ошибкой подключения (например, если первый запрос был маршрутизирован на рабочий хост Kerberos, а второй запрос был маршрутизирован на нерабочий хост). В параметре mail_core.ose.configmap.data.application_config.retry.kerberos.errors рекомендуется указать все эти тексты ошибок.
Пример заполнения:
```
mail_core.ose.gssapi.smtp.enabled=true
mail_core.ose.gssapi.imap.enabled=true
mail_core.ose.gssapi.kerberosRealm=EXAMPLE.REALM.RU
mail_core.ose.configmap.data.application_config.kerberos.virtualIp=${mail_egress_gateway.ose.istio.egress.kerberos.virtualIp}
mail_core.ose.configmap.data.application_config.retry.kerberos.count=5
mail_core.ose.configmap.data.application_config.retry.kerberos.delay=1000
mail_core.ose.configmap.data.application_config.retry.kerberos.errors=Connection refused;;Connection reset;;Cannot get a KDC reply;;Authentication failed
```

mail-receive-letters-reader.conf#

В файле mail-receive-letters-reader.conf указываются следующие параметры для настройки метода аутентификации GSSAPI (Kerberos):

mail_receive_letters_reader.ose.gssapi.imap.enabled - флаг включения метода аутентификации GSSAPI для IMAP-соединений. Указывается значение true или false. Если указано false, будет использоваться метод аутентификации LOGIN;
mail_receive_letters_reader.ose.gssapi.kerberosRealm - название Kerberos Realm’а, по которому будет происходить аутентификация через GSSAPI.

Пример заполнения:
```
mail_receive_letters_reader.ose.gssapi.imap.enabled=true
mail_receive_letters_reader.ose.gssapi.kerberosRealm=EXAMPLE.REALM.RU
```

mail-egress-gateway.istio.all.conf#

В файле mail-egress-gateway.istio.all.conf указываются следующие параметры для настройки метода аутентификации GSSAPI (Kerberos):

mail_egress_gateway.ose.istio.egress.kerberos.hosts - список хостов и портов Kerberos, каждая пара хост-порт отделяется двумя точками с запятой (;;). Порт обязателен для указывания. В качестве хоста можно указать доменное имя или IP;
mail_egress_gateway.ose.istio.egress.kerberos.virtualIp - виртуальный IP для маршрутизации трафика до Kerberos хостов;
mail_egress_gateway.ose.istio.egress.kerberos.baseEjectionTime - время на которое Kerberos хост будет исключен из маршрутизации после ошибок (format: 1h/1m/1s/1ms. Допустимые значения >=1ms);
mail_egress_gateway.ose.istio.egress.kerberos.consecutive5xxErrors - количество ошибок, которые должны произойти при подключении к Kerberos хосту в течение интервала, указанного в параметре mail_egress_gateway.ose.istio.egress.kerberos.interval, чтобы хост был исключен из маршрутизации;
mail_egress_gateway.ose.istio.egress.kerberos.interval - интервал в течение которого должны произойти ошибки в количестве, указанном в параметре mail_egress_gateway.ose.istio.egress.kerberos.consecutive5xxErrors, чтобы хост был исключен из маршрутизации (format: 1h/1m/1s/1ms. Допустимые значения >=1ms);
mail_egress_gateway.ose.istio.egress.kerberos.maxEjectionPercent - максимальный процент хостов который может быть исключен из маршрутизации. Рекомендуется указать 100;
mail_egress_gateway.ose.istio.egress.kerberos.egressPort - порт Egress для Kerberos хостов.

Включение режима отладки#

Для анализа проблем с GSSAPI (и с SMTP- и IMAP-соединениями в целом) можно включить режим отладки. Режим отладки включает вывод подробных логов в поде при отправке и чтении писем, по которым можно исследовать причину ошибок.

Для включения режима отладки необходимо в манифест Deployment сервисов mail-core и mail-receive-letters-reader добавить переменную окружения SPRING_PROFILES_ACTIVE, в которой перечислить через запятую, для каких видов соединений необходимо включить режим отладки. Поддерживаются следующие значения:

SMTP_DEBUG - включает режим отладки для SMTP-соединений;
IMAP_DEBUG - включает режим отладки для IMAP-соединений;
GSSAPI_DEBUG - включает режим отладки для GSSAPI и для соединений с Kerberos-сервером.

На рисунке ниже представлен пример, когда режим отладки включён для всех трёх видов соединений:

Включение режима отладки

Возможные ошибки в логах и пути их устранения#

Скорее всего, идёт обращение к Kerberos-серверу с неправильным паролем почтового ящика. Проверьте, что в административной панели указан правильный пароль от почтового ящика.

Ошибка означает, что на Kerberos-сервере не найдена запись UPN (User Principal Name) для данного почтового ящика. Проверьте, что идёт обращение к правильному хосту Kerberos-сервера. При необходимости, обратитесь к администраторам Kerberos-сервера.

Исключение KrbException: Server not found in Kerberos database (7) - LOOKING_UP_SERVER#

Ошибка означает, что на Kerberos-сервере не найдена запись SPN (Service Principal Name) для SMTP или IMAP сервиса.

Если включить режим отладки (указать профиль GSSAPI_DEBUG), можно увидеть в логах, поиск какой записи SPN производился.

>>>KRBError:
	 cTime is Sun Aug 30 09:52:37 MSK 2015 1440917557000
	 sTime is Fri Sep 27 14:09:36 MSK 2024 1727435376000
	 suSec is 9408
	 error code is 7
	 error Message is Server not found in Kerberos database
	 crealm is EXAMPLE.REALM.RU
	 cname is mailbox1@EXAMPLE.REALM.RU
	 sname is smtp/smtp.server.hostname@EXAMPLE.REALM.RU
	 msgType is 30

Искомая запись SPN (smtp/smtp.server.hostname@EXAMPLE.REALM.RU), которая не была найдена на Kerberos-сервере, указана в поле sname.

Проверьте, что идёт обращение к правильному хосту Kerberos-сервера. При необходимости, обратитесь к администраторам Kerberos-сервера.