Keycloak IdP

Введение

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

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

Единый вход всегда обеспечивается совместной работой двух приложений: поставщика учетных записей и поставщика сервиса (их также называют IdP и SP). ONLYOFFICE SSO реализует только SP. В роли IdP могут выступать самые разные поставщики, но в этой статье рассматривается Keycloak.

Создание IdP в Keycloak

1. Войдите в Keycloak как администратор.

2. Перейдите в раздел Manage realms и выберите realm, в котором будет настроено подключение.

3. Перейдите в раздел Clients и нажмите кнопку Create client.

4. На открывшейся странице укажите следующее: в поле Client type выберите SAML. В поле Client ID введите https://myportal-address.com/sso/metadata, заменив myportal-address.com на доменное имя вашего рабочего пространства. В полях Name и Description введите любые название и описание клиента.

   

5. Нажмите кнопку Next.

6. Заполните следующие поля:

   примечание

   Замените myportal-address.com на доменное имя вашего рабочего пространства.

   Application Details
   Root URL	https://myportal-address.com/sso
   Home URL	https://myportal-address.com/sso
   Valid redirect URIs	https://myportal-address.com/sso/slo/callback https://myportal-address.com/sso/acs
   Valid post logout redirect URIs	https://myportal-address.com/sso/slo/callback
   Master SAML Processing URL	https://myportal-address.com/sso/acs

   

   Заполните следующие поля на вкладке Advanced:

   Assertion Consumer Service POST Binding URL	https://myportal-address.com/sso/acs
   Assertion Consumer Service Redirect Binding URL	https://myportal-address.com/sso/acs
   Logout Service POST Binding URL	https://myportal-address.com/sso/slo/callback
   Logout Service Redirect Binding URL	https://myportal-address.com/sso/slo/callback

   

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

8. В разделе SAML capabilities установите для Name ID format значение email.

9. В разделе Signature and Encryption включите параметр Sign Assertions и выберите алгоритм подписи: RSA_SHA1, RSA_SHA256 или RSA_SHA512.

   

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

11. Перейдите в раздел Client Scopes и нажмите ссылку с названием вашего рабочего пространства https://myportal-address.com/sso/metadata-dedicated.

    Нажмите кнопку Add predefined mappers и в появившемся окне выберите следующие мапперы:

    • X500 email
    • X500 givenName
    • X500 surname

    Затем нажмите кнопку Add.

    

Настройка ONLYOFFICE SP

1. Убедитесь, что вы вошли в рабочее пространство ONLYOFFICE Apps как администратор, перейдите в меню Настройки, выберите раздел Интеграция и откройте вкладку Единый вход.

2. Включите SSO с помощью переключателя Включить аутентификацию с помощью технологии единого входа (SSO) и вставьте https://<keycloakurl>/realms/<realm_name>/protocol/saml/descriptor в поле URL-адрес XML-файла метаданных. Замените <keycloakurl> и <realm_name> на адрес вашего сервера Keycloak и название realm, в котором было создано подключение. Итоговая ссылка должна быть доступна из браузера.

   

3. Нажмите кнопку со стрелкой вверх, чтобы загрузить метаданные IdP. Форма настроек поставщика сервиса ONLYOFFICE будет автоматически заполнена данными из Keycloak IdP.

4. Выберите такой же Алгоритм проверки подписи по умолчанию, как указан в Keycloak.

   

5. Измените Формат NameID на emailAddress.

   

6. Теперь необходимо создать сертификат в разделе Сертификаты поставщика сервиса. Для этого нажмите кнопку Добавить сертификат.

7. В открывшемся модальном окне нажмите ссылку Сгенерировать новый самоподписанный сертификат и выберите вариант Подпись и шифрование в списке Использовать для. Перед сохранением сертификата скопируйте текст Открытый сертификат в буфер обмена и сохраните его в файл (он понадобится для Keycloak), затем нажмите кнопку ОК.

   

8. Перейдите в раздел Сопоставление атрибутов и присвойте атрибутам следующие значения:

   • Имя: urn:oid:2.5.4.42
   • Фамилия: urn:oid:2.5.4.4
   • Адрес электронной почты: urn:oid:1.2.840.113549.1.9.1

   

   В разделе Расширенные настройки можно выбрать параметр Скрыть страницу аутентификации, чтобы скрыть страницу аутентификации по умолчанию и автоматически перенаправлять на сервис SSO.

   Если нужно восстановить страницу аутентификации по умолчанию (чтобы иметь доступ к рабочему пространству, если ваш сервер IdP выйдет из строя), можно добавить ключ /login?skipssoredirect=true после доменного имени вашего рабочего пространства в адресной строке браузера.

9. Нажмите кнопку Сохранить.

10. Вернитесь в Keycloak, чтобы настроить шифрование: откройте своего клиента и перейдите в раздел Keys. Отключите параметр Client signature required и включите Encrypt assertions. В появившемся окне выберите Import, установите для Archive format значение Certificate PEM и нажмите кнопку Browse. Укажите путь к файлу сертификата из шага 7 и нажмите Confirm.

Проверка работы ONLYOFFICE SP с Keycloak IdP

1. Перейдите на страницу аутентификации ONLYOFFICE Apps (например, https://myportal-address.com/login).

2. Нажмите кнопку Единый вход. Если кнопки нет, значит SSO не включен.

   

3. Если все параметры SP и IdP заданы правильно, вы будете перенаправлены на форму входа Keycloak IdP:

   

4. Введите логин и пароль пользователя Keycloak и нажмите кнопку Sign In.

5. Если учетные данные верны, вы будете перенаправлены на главную страницу рабочего пространства (пользователь будет создан автоматически, если его нет, или данные будут обновлены, если они изменились в IdP).