Сопоставление групп пользователей в Keycloak
Чтобы настроить сопоставление групп пользователей в Keycloak
- Создайте федерацию в Yandex Cloud Organization.
- Добавьте сертификат Keycloak в федерацию
- Создайте и настройте SAML-приложение в Keycloak.
- Настройте сопоставление групп на стороне Keycloak
- Настройте сопоставление групп на стороне федерации.
- Проверьте работу аутентификации.
Примечание
Все примеры проверялись на версии Keycloak 21.1.2
.
Перед началом работы
Совет
Если у вас уже есть работающий сервер Keycloak, сравните настройки Keycloak с рекомендуемыми в этом руководстве и используйте ваш собственный сервер вместо создания нового. В этом случае вы можете перейти сразу к разделу Настройте сопоставление групп на стороне Keycloak.
-
Настройте локальный сервер Keycloak для тестирования:
-
Если у вас не установлен Docker, установите его
. Убедитесь, что Docker Engine запущен. -
Установите и запустите Docker-контейнер с Keycloak версии 21.1.2:
docker run -p 8080:8080 \ -e KEYCLOAK_ADMIN=admin \ -e KEYCLOAK_ADMIN_PASSWORD=Pa55w0rd \ quay.io/keycloak/keycloak:21.1.2 start-dev
Пока контейнер запущен, аккаунт администратора Keycloak будет доступен по адресу http://localhost:8080/admin или http://0.0.0.0:8080/admin
. Параметры входа по умолчанию:- User name or email:
admin
. - Password:
Pa55w0rd
.
Примечание
Чтобы сотрудники в корпоративной сети или интернете могли использовать Keycloak для аутентификации в вашем приложении, разверните IdP-сервер Keycloak в сети и настройте публичный адрес. Подробнее читайте в документации Keycloak
. -
-
Получите сертификат, который используется для подписи в службе Keycloak:
-
Войдите в аккаунт администратора Keycloak по адресу:
http://<IP_или_URL_Keycloak>:8080/admin
.Если вы используете локальный сервер из Docker-образа, то параметры входа по умолчанию:
- URL: http://0.0.0.0:8080/admin
. - User name or email:
admin
. - Password:
Pa55w0rd
.
- URL: http://0.0.0.0:8080/admin
-
В разделе Realm Settings выберите вкладку Keys.
-
В строке RS256 нажмите Certificate и скопируйте значение сертификата.
-
Сохраните сертификат в файле
keycloak-cert.cer
в следующем формате:
-----BEGIN CERTIFICATE----- <значение_сертификата> -----END CERTIFICATE-----
Сертификат потребуется в дальнейшем при настройке федерации удостоверений.
-
Создайте федерацию Yandex Cloud Organization
-
Перейдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
В правом верхнем углу страницы нажмите кнопку
Создать федерацию. В открывшемся окне:-
Задайте имя федерации, например
demo-federation
. Имя должно быть уникальным в каталоге. -
При необходимости добавьте описание.
-
В поле Время жизни cookie укажите время, в течение которого браузер не будет требовать у пользователя повторной аутентификации.
-
В поле IdP Issuer вставьте ссылку вида:
http://<IP_или_URL_Keycloak>:8080/realms/master
-
В поле Ссылка на страницу для входа в IdP вставьте ссылку вида:
http://<IP_или_URL_Keycloak>:8080/realms/master/protocol/saml
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
Включите опцию Автоматически создавать пользователей, чтобы автоматически добавлять пользователя в организацию после аутентификации. Если опция отключена, федеративных пользователей потребуется добавить вручную.
Автоматически федеративный пользователь создается только при первом входе пользователя в облако. Если вы исключили пользователя из федерации, вернуть его туда можно будет только вручную.
-
(Опционально) Чтобы все запросы аутентификации от Yandex Cloud содержали цифровую подпись, включите опцию Подписывать запросы аутентификации.
-
Включите опцию Принудительная повторная аутентификация (ForceAuthn) в IdP, чтобы задать значение
true
для параметра ForceAuthn в запросе аутентификации SAML. При включении этой опции поставщик удостоверений (Identity Provider, IdP) запрашивает у пользователя аутентификацию по истечении сессии в Yandex Cloud. -
Нажмите кнопку Создать федерацию.
-
-
(Опционально) Скачайте сертификат по ссылке в поле Подписывать запросы аутентификации, если ранее вы включили соответствующую опцию. Сертификат потребуется в дальнейшем при настройке клиента в Keycloak.
Добавьте сертификат Keycloak в федерацию
Чтобы при аутентификации сервис Cloud Organization мог проверить сертификат сервера Keycloak, добавьте сертификат в федерацию:
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Нажмите на строку с федерацией, для которой нужно добавить сертификат —
demo-federation
. -
Внизу страницы в блоке Сертификаты нажмите кнопку Добавить сертификат.
-
Введите название сертификата и укажите путь к файлу
keycloak-cert.cer
. -
Нажмите кнопку Добавить.
Совет
Не забывайте своевременно перевыпускать сертификаты и добавлять их в федерацию.
Чтобы не пропустить момент окончания срока действия сертификата, подпишитесь на уведомления от организации. Уведомления направляются подписанным пользователям за 60, 30 и 5 дней до момента прекращения действия сертификата, а также после того, как сертификат становится недействительным.
Создайте и настройте SAML-приложение в Keycloak
В роли поставщика удостоверений (IdP) выступает SAML-приложение в Keycloak. Чтобы создать и настроить SAML-приложение:
-
Войдите в аккаунт администратора Keycloak по адресу:
http://<IP_или_URL_Keycloak>:8080/admin
.Если вы используете локальный сервер из Docker-образа, то параметры входа по умолчанию:
- URL: http://0.0.0.0:8080/admin
. - User name or email :
admin
. - Password :
Pa55w0rd
.
- URL: http://0.0.0.0:8080/admin
-
Создайте SAML-приложение:
-
На панели слева выберите Clients. Нажмите кнопку Create client.
-
В поле Client type выберите вариант SAML.
-
В поле Client ID укажите ACS URL, на который пользователи будут перенаправляться после аутентификации.
Как получить идентификатор федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
-
Нажмите Next.
-
Укажите ACS URL для перенаправления, в полях:
- Home URL;
- Valid Redirect URIs;
- IDP Initiated SSO Relay State.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
Нажмите Save.
-
-
Настройте параметры SAML-приложения на вкладке Settings:
-
Включите опции:
- Include AuthnStatement;
- Sign Assertions;
- Force name ID format;
- Force POST Binding;
- Front Channel Logout.
-
В поле Signature Algorithm выберите RSA_SHA256.
-
В поле SAML Signature Key Name выберите CERT_SUBJECT.
-
В качестве Name ID Format выберите
username
. -
Нажмите кнопку Save.
-
-
(Опционально) Если при создании федерации в Yandex Cloud Organization вы включили опцию Подписывать запросы аутентификации, настройте в SAML-приложении проверку цифровой подписи:
- На вкладке Keys SAML-приложения убедитесь, что опция Client Signature Required включена.
- Нажмите кнопку Import key под автоматически сгенерированным сертификатом и в поле Archive Format выберите Certificate PEM.
- Нажмите кнопку Browse и выберите сертификат для подписи запросов аутентификации. Сертификат доступен на странице сведений о федерации в Yandex Cloud Organization в поле Подписывать запросы аутентификации.
- Нажмите Import.
- Включите опцию Encrypt Assertions.
- В появившемся окне выберите метод Generate и нажмите Confirm.
- Нажмите кнопку Import key под сгенерированным сертификатом и в поле Archive Format выберите Certificate PEM.
- Нажмите кнопку Browse и выберите сертификат для подписи запросов аутентификации. Сертификат доступен на странице сведений о федерации в Yandex Cloud Organization в поле Подписывать запросы аутентификации.
- Нажмите Import.
Настройте сопоставление групп на стороне Keycloak
-
Создайте пользователя:
- На панели слева выберите Users.
- Нажмите Add user и введите имя пользователя, например
demo_user1
. - Нажмите кнопку Create.
- На вкладке Credentials нажмите Set Password и задайте пароль. Для удобства тестирования отключите опцию Temporary.
-
Создайте группу и добавьте в нее пользователя:
- На панели слева выберите Groups.
- Нажмите Create group и введите имя группы, например
kc_demo_group
. - Нажмите на имя группы, на вкладке Members нажмите Add member и добавьте в группу пользователя
demo_user1
из списка.
-
Добавьте маппер в приложение Keycloak:
-
На панели слева выберите Clients и выберите ранее созданное приложение из списка.
-
Перейдите на вкладку Client scopes и выберите из списка ACS URL с постфиксом
-dedicated
:<ACS_URL>-dedicated
.Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
-
На вкладке Mappers нажмите Configure a new mapper. Выберите из списка Group list.
-
Укажите следующие настройки маппера:
- Name —
group_mapper
; - Group attribute name —
member
; - SAML Attribute NameFormat —
Basic
; - Single Group Attribute —
On
. - Full group path —
Off
.
- Name —
-
Нажмите Save.
-
Настройте сопоставление групп на стороне федерации
-
Войдите в сервис Yandex Cloud Organization
. -
Создайте группу пользователей
yc_demo_group
в Cloud Organization и выдайте ей права на просмотр ресурсов в облаке или отдельном каталоге (рольviewer
). -
На панели слева выберите
Федерации. -
Выберите созданную ранее федерацию
demo-federation
и перейдите на вкладку IdP-группы. -
Включите опцию Маппинг групп в IdP.
-
Нажмите кнопку Добавить.
-
В поле Имя группы введите имя группы в Keycloak —
kc_demo_group
. -
В поле IAM-группы выберите из списка имя группы в Yandex Cloud Organization —
yc_demo_group
. -
Нажмите Сохранить.
Проверьте работу аутентификации
-
Откройте браузер в гостевом режиме или режиме инкогнито.
-
Перейдите по URL для входа в консоль:
https://console.yandex.cloud/federations/<идентификатор_федерации>
Как получить идентификатор федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Если все настроено правильно, браузер перенаправит вас на страницу аутентификации в Keycloak.
-
-
Введите имя пользователя и пароль тестового федеративного пользователя
demo_user1
и нажмите кнопку Sign in.После успешной аутентификации IdP-сервер перенаправит вас по ACS URL, который вы указали в настройках Keycloak, а после — на главную страницу консоли управления
. -
Убедитесь, что созданный пользователь
demo_user1
входит в группуyc_demo_group
и у него есть права на просмотр ресурсов в соответствии с ролью, назначенной для группы.