Перейти к содержанию

Настройка SSO-аутентификации

Назначение документа

В документе описан порядок действий для настройки SSO как с использованием сервиса Keycloak, так и без него. По завершении интеграции пользователи получат возможность проходить SSO-аутентификацию внутри Почты VK WorkSpace.

SSO (Single Sign-On) — технология, позволяющая проходить при авторизации процесс аутентификации один раз и автоматически получать доступ к нескольким системам без повторного ввода учетных данных.

Предварительные условия

Чтобы начать настройку, вам потребуется:

  • Доступ на сервер Почты и в панель администратора VK WorkSpace.
  • Доступ к Active Directory.
  • Пользователь Active Directory с правами администратора.
  • Доступ в Keycloak (для интеграций с внешним сервером).
  • Навыки системного администрирования (Linux, Windows).

Настройки на сервере Active Directory

На контролере домена необходимо зарегистрировать учетную запись.

В разделе Account ввести в поле User logon name следующее:

  • Для интеграции с Keycloak — HTTP/<почтовый домен>.
  • Для интеграции без Keycloak — HTTP/auth.<почтовый домен>.

В окне Account options внутри того же раздела отметьте чекбосы:

  1. User cannot change password
  2. Password never expires
  3. This account supports Kerberos AES 128 bit encryption
  4. This account supports Kerberos AES 256 bit encryption
  5. Do not require Kerberos preauthentication

Затем в разделе управления групповыми политиками перейдите к настройке политики Configure encryption types allowed for Kerberos (настройка актуальна как для работы с Keycloak, так и без него).

Во вкладке Security Policy Setting отметьте следующие политики:

  • RC4_HMAC_MD5,
  • AES128_HMAC_SHA1,
  • AES256_HMAC_SHA1.

Сгенерируйте keytab-файлы

Команды, которые представлены ниже, необходимо выполнять на сервере Active Directory.

Пример команды, чтобы создать keytab для WEB (интеграция с Keycloak):

ktpass -princ HTTP/infra-01.dev.onprem.ru@AD2013.ON-PREMISE.RU -mapuser AD2013\kcuser3 -out C:\tmp\keycloak.keytab -mapOp set -crypto ALL -setupn -setpass -ptype KRB5_NT_PRINCIPAL /pass strongSecret

Сохраните созданный keytab-файл для HTTP на почтовом сервере.

Пример команд, чтобы создать keytab для WEB (интеграция без Keycloak):

ktpass -princ HTTP/auth.infra-01.dev.onprem.ru@AD2013.ON-PREMISE.RU -mapuser "<username>@ad2013.on-premise.ru" -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass "<userpass>" +dumpsalt -out C:\Users\Admin\Documents\keytabs_sso\http.keytab

ktpass -princ "HTTP/infra-01.dev.onprem.ru@AD2013.ON-PREMISE.RU" -mapuser "<username>@ad2013.on-premise.ru" -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass "<userpass>" -in C:\Users\Admin\Documents\keytabs_sso\http.keytab -out C:\Users\Admin\Documents\keytabs_sso\httpq.keytab -setupn -setpass -rawsalt "<Hashing password with salt из вывода прошлой команды>"

Параметры команды ktpass:

  • princ — имя SPN в Keycloak для идентификации в среде Kerberos.

    Имя состоит из: транспортного протокола (для HTTP в верхнем регистре); имени хоста сервера Keycloak (или адреса почтового сервера для интеграций внутри инсталляции); Kerberos Realm (для HTTP в верхнем регистре).

  • mapuser – имя созданной в домене учетной записи для сервера Keycloak (DOMAIN\username).

  • mapOp – если задано значение add, то новый SPN будет добавлен к существующим. Если задано значение set, то SPN будет перезаписан.
  • out – задает путь к генерируемому keytab-файлу. Например, C:\temp\spnego_spn.keytab.
  • /pass – значение пароля от учетной записи для сервера Keycloak в домене.
  • параметры crypto и ptype задают ограничения на используемые алгоритмы и тип генерируемой Kerberos-службы. Рекомендуется задать параметры, как в указанном примере: -crypto ALL -ptype KRB5_NT_PRINCIPAL.
  • параметр -setupn необходим для того, чтобы UPN не менялся.

Внимание

Отдельно сохраните значение SPN (Service Principal Name) из команды выше, оно потребуется вам позднее.

Чтобы сгенерировать keytab-файлы для SMTP и IMAP, используйте следующие команды (актуальны как для работы с Keycloak, так и без него):

dsquery * -filter sAMAccountName=kcuser3 -attr msDS-KeyVersionNumber

# В следующих командах /kvno <N> – результат выполнения первой команды
ktpass -princ smtp/infra-01.dev.onprem.ru@AD2013.ON-PREMISE.RU -mapuser AD2013\kcuser3 -out C:\tmp\infra_smtp.keytab -mapOp add -crypto ALL -setupn -setpass -ptype KRB5_NT_PRINCIPAL /kvno <N> /pass strongSecret
ktpass -princ imap/infra-01.dev.onprem.ru@AD2013.ON-PREMISE.RU -mapuser AD2013\kcuser3 -out C:\tmp\infra_imap.keytab -mapOp add -crypto ALL -setupn -setpass -ptype KRB5_NT_PRINCIPAL /kvno <N> /pass strongSecret

Два файла .keytab для IMAP и SMTP нужно также сохранить на сервере Почты. В дальнейшем их нужно будет добавить в установщик.

Настройка интеграции с Active Directory

  1. Авторизуйтесь в панели администратора под учетной записью администратора.
  2. Выберите адрес сервера, для которого нужно настроить интеграцию с Keycloak. У выбранного домена должна быть настроена MX-запись.
  3. Перейдите в раздел Конфигурация -> Настройки панели администратора.

  4. Чтобы начать настройку, уберите чекбокс Не использовать AD:

    окно настроек AD

  5. Введите в поле Адрес AD адрес вашего каталога Active Directory.

  6. Каталоги пользователей — введите значение поля distinguishedName из списка атрибутов каталога. Например, OU=demoapp.DC=presale.DC=local.

    Если вам нужно указать больше одного каталога пользователей, обратитесь к представителю VK.

  7. Введите в поле Логин администратора логин администратора Active Directory.

  8. Вставьте в поле Пароль администратора пароль администратора Active Directory.

  9. Если вы используете свойство Отчество, введите его значение в Поле свойства «Отчество».

  10. Использовать шифрованное соединение (LDAPS) — есть возможность добавления сертификата LDAPS с помощью кнопки Добавить сертификат.

  11. Отметьте чекбокс Игнорировать ошибки сертификата, если у вас самоподписанный SSL-сертификат.

    Сбрасывать сессии пользователей при изменении пароля — если чекбокс отмечен, при изменении пароля пользователя в Active Directory будет сбрасываться сессия в Почте.

    Использовать в качестве логина email вместо username — в текущей версии поле не используется.

  12. Нажмите на кнопку Сохранить, чтобы применить настройки.

Если пользователи не появились в Почте, нужно проверить корректность настроек синхронизации с Active Directory с помощью консольной команды:

sudo journalctl -fu onpremise-container-adloader1.service

Проверка настроек домена

Если вы не планируете использовать Keycloak, перейдите к настройке установщика.

Далее необходимо проверить файл настроек домена, для которого будет настраиваться интеграция с Keycloak:

  1. Перейдите по URL административной панели https://biz.<domain_name>/admin/misc/configurations/adloaderclient/ и кликните по адресу домена.

    домен в суперадминке

  2. Убедитесь, что в разделе options отсутствует значение proxyAddresses.

    proxyAddresses

  3. Если значение proxyAddresses присутствует, необходимо удалить его, включая скобки: (proxyAddresses=smtp:sink.mail1@exch.on-premise.ru).

  4. Сохраните изменения.

Настройка установщика

Для перехода в веб-интерфейс в адресной строке браузера необходимо указать адрес: http://server-ip-address:8888. Нажмите на значок иконка и перейдите в раздел Продукты.

Для работы с Keycloak

  1. Включите опции Интеграция с Kerberos (SSO-авторизация) и Keycloak внутри инсталляции.

    SSO в деплоере

    Если вы планируете использовать внешний сервис Keycloak, нужно включить опцию Интеграция с внешним Keycloak сервером.

  2. Сохраните изменения и вернитесь к списку ролей, чтобы сгенерировать дополнительные контейнеры.

    генерация контейнеров

  3. В настройках перейдите в раздел Интеграции -> Интеграция с Kerberos (SSO-авторизация).

  4. Введите заглавными буквами адрес сервера Active Directory, который будет использоваться в интеграции, в поле Название REALM`а в Keycloak.

    В поле можно также ввести любое ключевое название, например KEYCLOAKREALM. Позже это значение будет использоваться при настройках в интерфейсе Keycloak. REALM в установщике не должен совпадать с Kerberos REALM, у них разное назначение.

  5. Сохраните изменения.

  6. Если установщик выдаст ошибку, попробуйте сохранить еще раз.

  7. Прежде чем перейти в интерфейс Keycloak, на сервере с дистрибутивом Почты выполните команду:

    grep KEYC /opt/mailOnPremise/dockerVolumes/keycloak1/keycloak.env

Для работы без Keycloak

  1. Включите опции Интеграция с Kerberos (SSO-авторизация).

    SSO в деплоере

  2. Сохраните изменения и вернитесь к списку ролей, чтобы сгенерировать дополнительные контейнеры.

    генерация контейнеров

  3. Затем в Настройках перейдите в раздел Интеграции -> Интеграция с Kerberos (SSO-авторизация).

  4. Заполните поля:

    • Адрес системы аутентификации Kerberos — адрес сервера, на котором установлен AD/Kerberos и порт 88.

    • Адрес сервера Kerberos-adm (Kerberos administration) — адрес сервера, на котором установлена административная панель Kerberos и порт 749.

    • Имя REALM в Kerberos — заглавными буквами введите имя REALM (чаще всего оно совпадает с адресом сервера AD/Kerberos).

    • Адрес сервера SPN (Service Principal Name).

  5. Добавьте keytab-файлы в соответствующие поля и сохраните изменения.

  6. Чтобы применить новую конфигурацию перейдите к списку ролей и повторите соответствующие шаги или запустите автоматическую установку.

На этом интеграцию с Kerberos без Keycloak можно считать завершенной.

Настройки интеграции с Keycloak

Для перехода в Keycloak в строке браузера введите адрес: https://biz.<mail_domain>/auth.

Если вы используете внешний сервер Keycloak, перейдите в его панель администрирования.

админка Keycloak

Шаг 1. Создайте и настройте REALM

  1. В выпадающем меню нажмите на кнопку Add realm.

    имя REALM

  2. В поле Name введите имя REALM, аналогичное указанному в интерфейсе установщика.

  3. Нажмите на кнопку Create — откроется окно настроек, раздел General.

    Keycloak General

  4. В поле Frontend URL добавьте URL вида: http://biz.<mail_domain>:80/auth.

    Примечание

    При использовании внешнего сервера Keycloak нужна дополнительная настройка на /auth с помощью параметра http-relative-path=/auth.

  5. Сохраните изменения.

  6. Во вкладке Login у параметра Require SSL необходимо выбрать значение none.

  7. Сохраните настройки.

  8. Перейдите во вкладку Keys -> Providers и удалите неподдерживаемые провайдеры (aes-generated и rsa-enc-generated).

    удалить провайдеры

Шаг 2. Добавьте Client API

  1. В разделе Clients создайте нового клиента. Для этого в поле Client ID введите значение api и нажмите на кнопку Save.

    добавить клиента

  2. Вкладку Settings нужно настроить следующим образом:

    Внимание

    Поля, настройки которых не будут изменяться, следует оставить заполненными по умолчанию.

    • Access Type — confidential (после изменения типа доступа появятся дополнительные настройки);
    • Service Accounts Enabled — ON;
    • Authorization Enabled — ON;
    • Valid Redirect URIs — * (необходимо ввести в поле символ *);

  3. Cохраните изменения.

  4. Перейдите во вкладку Credentials.

  5. Скопируйте или сохраните значение поля Secret.

    скорипуйте значение

Шаг 3. Настройте интеграцию с LDAP

  1. Перейдите в раздел User Federation и в выпадающем меню Add provider выберите ldap.

  2. Внесите данные в соотвествие с настройками LDAP в вашем каталоге Active Directory.

    Обратите внимание:

    • В строке Username LDAP attribute необходимо указать название поля в Active Directory, в котором содержатся юзернеймы пользователей.
    • В поле Bind DN нужно добавить точное местоположение пользователя для синхронизации в каталоге AD.

    заполните данные для интеграции

  3. Проверьте соединение с помощью кнопок Test connection и Bind Credential.

    тест соединения

Шаг 4. Настройте интеграцию с Kerberos при работе с Keycloak

  1. Раскройте вкладку Kerberos Integration и внесите данные для интеграции.

    интеграция с Kerberos

  2. Заполните поля:

    • Kerberos Realm — введите имя REALM из Kerberos.
    • Server Principal — укажите ранее созданный SPN Например, HTTP/biz.infra-01.dev.onprem.ru@AD2013.ON-PREMISE.ru.
    • KeyTab — добавьте в путь до keytab-файла для HTTP.

    Менять положение флагов не нужно.

  3. Сохраните изменения.

Шаг 5. Добавьте в контейнер Keycloak файла .keytab

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

cp keycloak.keytab /opt/mailOnPremise/dockerVolumes/keycloak1/keytabs/

Шаг 6. Настройте параметры интеграции с Keycloak в установщике

  1. В настройках установщика Почты необходимо перейдите в раздел Интеграции -> Интеграция с keycloak для SSO авторизации.

    настройки в деплоере

  2. В поле Secret oauth клиента в Keycloak введите код из раздела Clients -> Credentials в Keycloak, который вы сохранили ранее.

  3. Добавьте адреса сервисов Kerberos (с портами) и keytab-файлов для IMAP и SMTP.

  4. Сохраните изменения.
  5. Чтобы применить изменения перейдите к списку ролей и запустите автоматическую установку.

  6. Чтобы в интерфейсе пользователей начала отображаться кнопка Войти через SSO, выполните в контейнере mailapi1 шаг up_container.

    настройки в деплоере

  7. Проверьте успешность интеграции, войдя в систему через SSO под учетной записью пользователя.