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

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

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

Настройка стендозависимых параметров#

Чтобы настроить метод аутентификации 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.gssapi.smtp.enabled=true
mail_core.ose.gssapi.imap.enabled=true
mail_core.ose.gssapi.kerberosRealm=EXAMPLE.REALM.RU

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 необходимо добавить настройки подключения к серверу Kerberos. В параметр mail_egress_gateway.ose.istio.egress.entries необходимо добавить новую запись в JSON-массив:

{
	"name": "kerberos", // Название записи. Должно равняться "kerberos", учитывая регистр
	"host": "kerberos.server.hostname", // Хост Kerberos-сервера, с которым будет устанавливаться соединение
	"virtualIp": "***.***.***.***", // Виртуальный IP-адрес (нужно придумать любой уникальный внутри сети кластера)
	"egressPort": 2950, // Порт Egress, по которому происходит маршрутизация. Должен быть уникальным среди Istio-настроек других внешних хостов
	"externalPort": 88, // Порт Kerberos-сервера
	"isTlsOnEgress": "false", // Флаг использования TLS при подключении к Kerberos-серверам. Чтобы указать правильное значение, уточните, используется ли TLS на Kerberos-сервере, с которым идёт соединение 
	"meshProtocol": "tcp", // Протокол, используемый внутри Service Mesh. Укажите "tcp"
	"externalProtocol": "tcp", // Протокол, используемый для соединения с Kerberos-сервером. Укажите "tcp"
	"tlsParamsUpgrade": "false", // Флаг создания Envoy-фильтра, обеспечивающего нужную версию TLS. Укажите то же значение, что и в параметре isTlsOnEgress
	"pkiEngine": "NAMESPACE/PKI/fetch/user-role", // PKI-движок, используемый для выпуска TLS-сертификатов. Если сертификаты подгятиваются из KV-хранилища SecMan, не указывайте это поле
	"toggleGetChainFromKvEnabled": "false", // Флаг получения цепочки доверенных сертификатов из KV-хранилища SecMan. Указывается, только если указан непустой параметр pkiEngine
	"certCommonName": "kerberos" // CN клиентского TLS-сертификата, выпускаемого PKI-движком
}

После добавления этой записи, при установке дистрибутива будут созданы Istio-сущности, необходимые для правильной маршрутизации трафика до Kerberos-сервера.

Hot Reload используемого метода аутентификации (GSSAPI или LOGIN)#

Выполнять переключение между методами аутентификации GSSAPI и LOGIN можно на ходу, не выполняя заново инсталляцию дистрибутива на стенд. Для этого необходимо в ConfigMap для сервисов mail-core и mail-receive-letters-reader, в поле application-config.yml поменять параметры smtp.gssApiEnabled и imap.gssApiEnabled на нужные значения (параметр smtp.gssApiEnabled присутствует только в mail-core, параметр imap.gssApiEnabled присутствует в обоих сервисах.). После этого среда оркестрации увидит изменения в ConfigMap и перемонтирует конфигурационный файл на подах.

Подробнее о том, как работает Hot Reload через изменение ConfigMap, написано в Hot reload для сертификатов и конфигураций.

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

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

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

  • SMTP_DEBUG - включает режим отладки для SMTP-соединений;

  • IMAP_DEBUG - включает режим отладки для IMAP-соединений;

  • GSSAPI_DEBUG - включает режим отладки для GSSAPI и для соединений с Kerberos-сервером.

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

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

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

Исключение javax.security.auth.login.LoginException: Checksum failed#

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

Исключение javax.security.auth.login.LoginException: Client not found in Kerberos database (6) - CLIENT_NOT_FOUND#

Ошибка означает, что на 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-сервера.