Настройка SAML в Keycloak

Keycloak это решение с открытым исходным кодом для управления идентификацией и доступом, поддерживающее федерацию пользователей, протоколы OAuth, SAML и OpenID Connect. Ниже приведены инструкции по настройке Keycloak вместе с приложением Jmix с использованием SAML, чтобы пользователи могли входить в систему с учётными данными Keycloak.

Инструкции были протестированы с Keycloak 26.5.6. В других, особенно более старых, версиях Keycloak названия элементов и расположение некоторых настроек в административной консоли могут отличаться, однако конфигурация SAML должна оставаться той же.

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

  • Приложение Jmix, доступное по стабильному URL-адресу (например, https://jmix-app.com). В инструкции URL приложения обозначено плейсхолдером your-app-url.

  • Сервер Keycloak (например, https://keycloak.test.com), к которому у вас есть административный доступ. В инструкции сервер обозначен плейсхолдером your-keycloak-server.

  • Realm в Keycloak (например, master). В инструкции realm обозначен плейсхолдером your-realm.

Настройка приложения Jmix

В вашем приложении Jmix:

  1. Установите дополнение.

  2. Настройте приложение как SAML service provider с помощью свойств Spring Security:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.entity-id=https://<your-app-url>/saml/sp
spring.security.saml2.relyingparty.registration.keycloak.acs.location=https://<your-app-url>/login/saml2/sso/keycloak
spring.security.saml2.relyingparty.registration.keycloak.assertingparty.metadata-uri=https://<your-keycloak-server>/realms/<your-realm>/protocol/saml/descriptor
spring.security.saml2.relyingparty.registration.keycloak.singlelogout.url=https://<your-keycloak-server>/realms/<your-realm>/protocol/saml
spring.security.saml2.relyingparty.registration.keycloak.singlelogout.response-url=https://<your-app-url>/logout/saml2/slo
keycloak в ключе свойства — это идентификатор провайдера. Он может иметь любое значение.

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

В Keycloak создайте или выберите realm, который будет управлять аутентификацией для вашего приложения Jmix.

  1. Выберите или создайте realm, который будет управлять аутентификацией для вашего приложения Jmix.

  2. В этом realm создайте новый клиент со следующими значениями:

    • Сlient type: SAML.

    • Client ID: https://<your-app-url>/saml/sp (то же значение, что и в свойстве entity-id).

    • Root URL: базовый URL вашего приложения, например https://jmix-app.com.

    • Valid redirect URIs: допустимые шаблоны URI перенаправления, например https://jmix-app.com/*.

    • Valid post logout redirect URIs: допустимые шаблоны URI перенаправления после выхода из приложения, например https://jmix-app.com/*.

Эти значения связывают клиент Keycloak с конфигурацией Jmix service provider из предыдущего шага.

Настройка доступа пользователей к приложению

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

Создание ролей

Создайте роли, которые должны быть назначены пользователям:

  1. Перейдите в Realm roles и создайте новую роль.

  2. Укажите Role name. Если вы используете стандартное сопоставление ролей Jmix, оно должно совпадать с кодом роли Jmix, например system-full-access.

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

Создайте пользователя Keycloak:

  1. Перейдите в Users и создайте нового пользователя.

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

  3. Перейдите на вкладку Role Mapping, чтобы назначить ранее созданные realm roles.

Добавление атрибутов SAML

Настройте отправку SAML-атрибутов, которые требуются вашему приложению. Их необходимо сопоставить с помощью мапперов:

  1. Перейдите в Client → Client Scopes → https://<your-app-url>/saml/sp-dedicated → Configure a new mapper.

  2. Выберите подходящий тип маппера. Для встроенных свойств (например, email, firstName, lastName) выберите User Property и укажите значения:

    • Name: описательное имя маппера, например FirstName mapper

    • Property: имя свойства в провайдере удостоверений: firstName

    • SAML Attribute Name: имя атрибута в SAML Assertion: FirstName

Повторите те же шаги, чтобы добавить другие атрибуты.

Настройки signing и сертификатов

Чтобы включить signing, вам понадобятся публичный и приватный ключи. Вы можете сгенерировать их вручную с помощью openssl. Также можно сгенерировать их с помощью Keycloak:

  1. Перейдите в ваш Client и откройте вкладку Keys.

  2. Включите Client signature required.

  3. Сгенерируйте новый ключ и экспортируйте его как pkcs12 keystore. Запомните store password, который вы зададите.

  4. Извлеките закрытый ключ и сертификат:

    openssl pkcs12 -in keystore.p12 -nodes -nocerts -out private.key -passin pass:<STORE_PASSWORD>
openssl pkcs12 -in keystore.p12 -nodes -nokeys -out public.crt -passin pass:<STORE_PASSWORD>

    Если извлечение не удалось, добавьте параметр -legacy к обеим командам. В этом случае вам также потребуется преобразовать извлеченный закрытый ключ в формат pkcs8:

    openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.key -out private-pkcs8.key

  5. Поместите файлы в расположение, доступное приложению, например в src/main/resources, и укажите их через свойства:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].private-key-location=classpath:private-pkcs8.key
spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].certificate-location=classpath:public.crt

(Опционально) Указание алгоритма подписи

Если требуется конкретный алгоритм подписи, укажите его явно. Например:

application.properties
spring.security.saml2.relyingparty.registration.keycloak.signing.credentials[0].algorithm=http://www.w3.org/2001/04/xmldsig-more#rsa-sha256

(Опционально) Указание сертификата проверки

В некоторых окружениях также может потребоваться сертификат проверки. Чтобы указать сертификат:

  1. Откройте дескриптор метаданных Keycloak по адресу https://<your-keycloak-server>/realms/<your-realm>/protocol/saml/descriptor

  2. Скопируйте значение X509Certificate.

  3. Сохраните его в файл, например keycloak-signing.crt, в следующем формате:

    -----BEGIN CERTIFICATE-----
<value>
-----END CERTIFICATE-----

  4. Поместите файл в расположение, доступное приложению, например в src/main/resources, и добавьте его через свойство:

    application.properties
    spring.security.saml2.relyingparty.registration.keycloak.assertingparty.verification.credentials[0].certificate-location=classpath:keycloak-signing.crt

Проверка подключения

После настройки приложения Jmix и Keycloak запустите приложение и проверьте работу SSO.

Убедитесь, что:

  • Пользователь перенаправляется на страницу входа Keycloak.

  • Аутентификация успешно выполняется.

  • Необходимые атрибуты присутствуют в SAML assertion.

  • Пользователям приложения назначаются необходимые роли.

  • Выход из системы работает корректно, если настроен SLO.