Сопоставление групп пользователей в Keycloak

Чтобы настроить сопоставление групп пользователей в Keycloak и групп пользователей в федерации удостоверений:

1. Создайте федерацию в Yandex Cloud Organization.
2. Добавьте сертификат Keycloak в федерацию
3. Создайте и настройте SAML-приложение в Keycloak.
4. Настройте сопоставление групп на стороне Keycloak
5. Настройте сопоставление групп на стороне федерации.
6. Проверьте работу аутентификации.

Перед началом работыПеред началом работы

1. Настройте локальный сервер Keycloak для тестирования:

   1. Если у вас не установлен Docker, установите его. Убедитесь, что Docker Engine запущен.

   2. Установите и запустите 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.

2. Получите сертификат, который используется для подписи в службе Keycloak:

   1. Войдите в аккаунт администратора Keycloak по адресу: http://<IP_или_URL_Keycloak>:8080/admin.

      Если вы используете локальный сервер из Docker-образа, то параметры входа по умолчанию:

      • URL: http://0.0.0.0:8080/admin.
      • User name or email: admin.
      • Password: Pa55w0rd.

   2. В разделе Realm Settings выберите вкладку Keys.

   3. В строке RS256 нажмите Certificate и скопируйте значение сертификата.

   4. Сохраните сертификат в файле keycloak-cert.cer в следующем формате:

   -----BEGIN CERTIFICATE-----
   <значение_сертификата>
   -----END CERTIFICATE-----
   

   Сертификат потребуется в дальнейшем при настройке федерации удостоверений.

Создайте федерацию Yandex Cloud OrganizationСоздайте федерацию Yandex Cloud Organization

Добавьте сертификат Keycloak в федерациюДобавьте сертификат Keycloak в федерацию

Чтобы при аутентификации сервис Cloud Organization мог проверить сертификат сервера Keycloak, добавьте сертификат в федерацию:

Создайте и настройте SAML-приложение в KeycloakСоздайте и настройте SAML-приложение в Keycloak

В роли поставщика удостоверений (IdP) выступает SAML-приложение в Keycloak. Чтобы создать и настроить SAML-приложение:

1. Войдите в аккаунт администратора Keycloak по адресу: http://<IP_или_URL_Keycloak>:8080/admin.

   Если вы используете локальный сервер из Docker-образа, то параметры входа по умолчанию:

   • URL: http://0.0.0.0:8080/admin.
   • User name or email : admin.
   • Password : Pa55w0rd.

2. Создайте SAML-приложение:

   1. На панели слева выберите Clients. Нажмите кнопку Create client.

   2. В поле Client type выберите вариант SAML.

   3. В поле Client ID укажите ACS URL, на который пользователи будут перенаправляться после аутентификации.

      Как получить идентификатор федерации

      1. Войдите в сервис Yandex Cloud Organization.
      2. На панели слева выберите Федерации.
      3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
      Как получить ACS URL федерации

      1. Войдите в сервис Yandex Cloud Organization.

      2. На панели слева выберите Федерации.

      3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.

   4. Нажмите Next.

   5. Укажите ACS URL для перенаправления, в полях:

      • Home URL;
      • Valid Redirect URIs;
      • IDP Initiated SSO Relay State.
      Как получить ACS URL федерации

      1. Войдите в сервис Yandex Cloud Organization.

      2. На панели слева выберите Федерации.

      3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.

   6. Нажмите Save.

3. Настройте параметры SAML-приложения на вкладке Settings:

   1. Включите опции:

      • Include AuthnStatement;
      • Sign Assertions;
      • Force name ID format;
      • Force POST Binding;
      • Front Channel Logout.

   2. В поле Signature Algorithm выберите RSA_SHA256.

   3. В поле SAML Signature Key Name выберите CERT_SUBJECT.

   4. В качестве Name ID Format выберите username.

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

4. (Опционально) Если при создании федерации в Yandex Cloud Organization вы включили опцию Подписывать запросы аутентификации, настройте в SAML-приложении проверку цифровой подписи:

   1. На вкладке Keys SAML-приложения убедитесь, что опция Client Signature Required включена.

   2. Нажмите кнопку Import key под автоматически сгенерированным сертификатом и в поле Archive Format выберите Certificate PEM.

   3. Нажмите кнопку Browse и выберите скачанный ранее SAML-сертификат Yandex Cloud для подписи запросов аутентификации.

      Если вы не скачивали SAML-сертификат при создании федерации, вы можете скачать его на странице сведений о федерации в Yandex Cloud Organization, нажав кнопку Скачать сертификат в поле Подписывать запросы аутентификации.

   4. Нажмите Import.

   5. Включите опцию Encrypt Assertions.

   6. В появившемся окне выберите метод Generate и нажмите Confirm.

   7. Нажмите кнопку Import key под сгенерированным сертификатом и в поле Archive Format выберите Certificate PEM.

   8. Нажмите кнопку Browse и выберите сертификат для подписи запросов аутентификации. Сертификат доступен для скачивания на странице сведений о федерации в Yandex Cloud Organization в поле Подписывать запросы аутентификации.

   9. Нажмите Import.

Настройте сопоставление групп на стороне KeycloakНастройте сопоставление групп на стороне Keycloak

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

   1. На панели слева выберите Users.
   2. Нажмите Add user и введите имя пользователя, например demo_user1.
   3. Нажмите кнопку Create.
   4. На вкладке Credentials нажмите Set Password и задайте пароль. Для удобства тестирования отключите опцию Temporary.

2. Создайте группу и добавьте в нее пользователя:

   1. На панели слева выберите Groups.
   2. Нажмите Create group и введите имя группы, например kc_demo_group.
   3. Нажмите на имя группы, на вкладке Members нажмите Add member и добавьте в группу пользователя demo_user1 из списка.

3. Добавьте маппер в приложение Keycloak:

   1. На панели слева выберите Clients и выберите ранее созданное приложение из списка.

   2. Перейдите на вкладку Client scopes и выберите из списка ACS URL с постфиксом -dedicated: <ACS_URL>-dedicated.

      Как получить ACS URL федерации

      1. Войдите в сервис Yandex Cloud Organization.

      2. На панели слева выберите Федерации.

      3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.

   3. На вкладке Mappers нажмите Configure a new mapper. Выберите из списка Group list.

   4. Укажите следующие настройки маппера:

      • Name — group_mapper;
      • Group attribute name — member;
      • SAML Attribute NameFormat — Basic;
      • Single Group Attribute — On.
      • Full group path — Off.

   5. Нажмите Save.

Настройте сопоставление групп на стороне федерацииНастройте сопоставление групп на стороне федерации

Проверьте работу аутентификацииПроверьте работу аутентификации

1. Откройте браузер в гостевом режиме или режиме инкогнито.

2. Перейдите по URL для входа в консоль:

   https://console.yandex.cloud/federations/<идентификатор_федерации>
   

   Как получить идентификатор федерации

   1. Войдите в сервис Yandex Cloud Organization.
   2. На панели слева выберите Федерации.
   3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.

   Если все настроено правильно, браузер перенаправит вас на страницу аутентификации в Keycloak.

3. Введите имя пользователя и пароль тестового федеративного пользователя demo_user1 и нажмите кнопку Sign in.

   После успешной аутентификации IdP-сервер перенаправит вас по ACS URL, который вы указали в настройках Keycloak, а после — на главную страницу консоли управления.

4. Убедитесь, что созданный пользователь demo_user1 входит в группу yc_demo_group и у него есть права на просмотр ресурсов в соответствии с ролью, назначенной для группы.