Перейти к основному содержимому

SAML Keycloak

к сведению

Time поддерживает стандарт SAML (Security Assertion Markup Language) для различных провайдеров авторизации.

Ниже приведены шаги по настройке SAML 2.0 с помощью Keycloak для Time.

Требования​

  • Инсталляция Keycloak, в которой все пользователи имеют следующие атрибуты:

    • электронная почта (email)
    • имя учётной записи (username)
    • имя пользователя (first name)
    • фамилия пользователя (last name)

  • Keycloak v23.0 или выше. Работоспособность с более ранними версиями не гарантируется.

Настройка KeyCloak​

Создание Client​

  1. Откройте консоль KeyCloak и выберите Clients в левой боковой панели.

  2. Нажмите кнопку Create client.

    Create client

  3. На экране создания клиента выберите SAML в качестве Client Type.

  4. В качестве Client ID введите https://<time-url>/login/sso/saml.

    Client ID

  5. Нажмите кнопку Next. И заполните поля:

    • Valid Redirect URIs: https://<time-url>/login/sso/saml
    • Home URL: https://<time-url>/login/sso/saml

    Next and Fields

  6. Нажмите кнопку Save.

  7. Убедитесь, что переключатель Enabled включен в правом верхнем углу.

    Enabled

  8. В правом меню нажмите на SAML Capabilities и установите:

    • NameID Format: email
    • Force name ID format: On
    • Остальные параметры оставьте по умолчанию.

    SAML Capabilities

  9. В правом меню нажмите на Signature and Encryption и установите:

    • Sign Documents: Off
    • Sign Assertions: On
    • Signature algorithm: RSA_SHA256
    • Canonicalization method: EXCLUSIVE

    Signature and Encryption

  10. Нажмите кнопку Save.

  11. Переключитесь на вкладку Keys.

  12. Переключите Client signature required в положение Off.

  13. Переключите Encrypt assertions в положение On.

    Encrypt assertions

  14. В появившемся окне нажмите Generate. Keycloak попытается скачать файл, разрешите.

  15. Нажмите кнопку Confirm.

  16. Под полем Certificate нажмите кнопку Export.

    Export

  17. В появившемся окне:

    1. Archive format: PKCS12
    2. Key alias: time
    3. Key password: time
    4. Store password: time
    5. нажмите кнопку Export.

  18. Переключитесь на вкладку Client Scopes и нажмите на первый.

    Client Scopes

  19. В появившемся окне нажмите Add predefined protocol mapper и выберите:

    1. X500 email
    2. X500 givenName
    3. X500 surname
    4. Нажмите кнопку Add.

    Add predefined protocol mapper

  20. Нажмите кнопку Add mapper.

    1. Выберите By configuration.
    2. Дальше выберите User Property.
    3. Заполните поля:
      • Name: username
      • Property: username
      • SAML Attribute Name: username
    4. Нажмите кнопку Save.
    5. Перейдите по ссылке Dedicated scopes в верхнем меню.
    6. Повторите шаги для поля id.

    Add mapper

  21. Следующий шаг нужно проделать для X500 email, X500 givenName, X500 surname:

    1. Нажмите на имя поля.
    2. В появившейся форме измените SAML Attribute Name на email, firstName, lastName соответственно.
    3. Нажмите кнопку Save.
    4. Перейдите по ссылке Dedicated scopes в верхнем меню.

  22. В меню слева выберите Realm Settings.

    • Скопируйте ссылку SAML 2.0 Identity Provider Metadata и сохраните её. Realm Settings

  23. Перейдите на вкладку Keys

    1. Найдите ключ с алгоритмом RS256 и нажмите на кнопку Certificate.

    2. Скопируйте содержимое появившегося окна.

      Certificate

    3. Сохраните содержимое в файл saml-idp.crt.

Подготовка сертификатов и ключей​

  1. Соберите все сертификаты и ключи, которые создали на предыдущих шагах, в одну папку.

  2. Выполните последовательно команды:

    openssl pkcs12 -in keystore.p12 -out time.key -nodes -nocerts -legacy
    openssl pkcs12 -in keystore.p12 -out time.crt -nodes -legacy
    openssl x509 -in saml-idp.crt -out saml-idp.crt

  3. Полученные файлы time.key, time.crt, saml-idp.crt используйте в дальнейших шагах.

Настройка SAML Sign-On для Time​

  1. Далее настройте параметры сервера Time через ENV-переменные:

    • TIME_SAMLSETTINGS_ENABLE=true — включение авторизации через SAML.
    • TIME_SAMLSETTINGS_SERVICEPROVIDERIDENTIFIER=https://${TIME_DOMAIN}/login/sso/saml — уникальный идентификатор поставщика услуг.
    • TIME_SAMLSETTINGS_ASSERTIONCONSUMERSERVICEURL=https://${TIME_DOMAIN}/login/sso/saml — адрес для входа через поставщика услуг.
    • TIME_SAMLSETTINGS_IDPURL=https://${ссылка на Realm KeyCloak}/protocol/saml — URL-адрес, на который мессенджер отправляет SAML-запрос для входа.
    • TIME_SAMLSETTINGS_IDPDESCRIPTORURL=https://${ссылка на Realm KeyCloak} — URL-адрес издателя поставщика учетных записей для запросов SAML.
    • TIME_SAMLSETTINGS_IDPMETADATAURL=https://${ссылка SAML 2.0 Identity Provider Metadata} — URL, по которому мессенджер отправляет запрос на получение метаданных (см. документацию вашего провайдера авторизации).
    • TIME_SAMLSETTINGS_SIGNATUREALGORITHM=RSAwithSHA256 — алгоритм для подписи запроса SAML (см. Admin Guide).
    • TIME_SAMLSETTINGS_CANONICALALGORITHM=Canonical1.1 — алгоритм канонизации для XML (см. Admin Guide).
    • TIME_SAMLSETTINGS_IDPCERTIFICATEFILE=/time/certs/saml-idp.crt — путь к публичному сертификату проверки подлинности (файл, который был сгенерирован на этапе Подготовка сертификатов и ключей).
    • TIME_SAMLSETTINGS_PUBLICCERTIFICATEFILE=/time/certs/time.crt — путь к файлу сертификата, используемого для подписи запроса SAML к поставщику удостоверений (файл, который был сгенерирован на этапе Подготовка сертификатов и ключей).
    • TIME_SAMLSETTINGS_PRIVATEKEYFILE=/time/certs/time.key — путь к файлу закрытого ключа, используемый для расшифровки утверждений SAML от поставщика удостоверений (файл, который был сгенерирован на этапе Подготовка сертификатов и ключей).
    • TIME_SAMLSETTINGS_IDATTRIBUTE=id — атрибут, который будет использоваться для сопоставления пользователей из SAML.
    • TIME_SAMLSETTINGS_FIRSTNAMEATTRIBUTE=firstName — атрибут имени пользователя
    • TIME_SAMLSETTINGS_LASTNAMEATTRIBUTE=lastName — атрибут фамилии пользователя
    • TIME_SAMLSETTINGS_EMAILATTRIBUTE=email — атрибут имейла пользователя
    • TIME_SAMLSETTINGS_USERNAMEATTRIBUTE=username — атрибут юзернейма пользователя
    • TIME_SAMLSETTINGS_NICKNAMEATTRIBUTE=username - атрибут псевдонима пользователя
    • TIME_TEAMSETTINGS_TEAMMATENAMEDISPLAY=full_name — cпособ отображения имён пользователей в интерфейсе Time (в данном случае — будет отображаться имя и фамилия пользователя).
    • TIME_SAMLSETTINGS_LOGINBUTTONTEXT='SAML (KeyCloak)' — текст на кнопке для входа через SAML.
    • TIME_SAMLSETTINGS_AUTOJOINTEAMATTRIBUTE='groups=<keycloak_group>:<time_team_id>' — параметр сопоставления группы пользователей в KeyCloak (<keycloak_group>), пользователи которой будут автоматически добавляться в указанную Team ID в Time (<time_team_id>)

    где:

    • ${TIME_DOMAIN} — домен, на котором работает Time.
    • ${ссылка на Realm KeyCloak} — ссылка на Realm из KeyCloak. Например, https://keycloak.example.com/Realms/master/.
    • ${ссылка SAML 2.0 Identity Provider Metadata} — URL для отправки мессенджером запроса на получение метаданных от IdP

  2. Затем перезапустите сервер Time (все инстансы).

  3. Войдите в Time как системный администратор, перейдите в System Console → Authentication → SAML, и проверьте что все указанные выше параметры добавились в соответствующие поля. Для дополнительных настроек также используйте ENV-переменные (см. Admin Guide).

Готово! Если вы хотите убедиться, что SAML SSO успешно включен, переключите свою учетную запись системного администратора с электронной почты на аутентификацию на основе SAML с помощью изображения вашего профиля, выбрав Profile → Security → Sign-in Method → Switch to SAML SSO, а затем войдите в систему через SAML под своей учетной записью провайдера авторизации.

FAQ​

После авторизации через ADFS у пользователя нет команд для присоединения​

Также вы може видеть сообщение вида:

No teams are available to join. Please create a new team or ask your administrator for an invite.

No teams are available to join

Ответ

По умолчанию новые пользователи не добавляются в Team, для этого необходимо сделать что-то одно из перечисленного:

  • присылать инвайт-ссылку — после логина по ссылке пользователь будет добавлен в указанную Team
  • после успешной авторизации добавить пользователя в Team вручную
  • настроить автоматическое добавление в команду с помощью параметра AutoJoinTeamAttribute — см. Admin Guide