Связаться с намиПодключиться

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

Статья создана
Обновлена 26 марта 2025 г.

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

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

Примечание

Все примеры проверялись на версии Keycloak 21.1.2.

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

Совет

Если у вас уже есть работающий сервер Keycloak, сравните настройки Keycloak с рекомендуемыми в этом руководстве и используйте ваш собственный сервер вместо создания нового. В этом случае вы можете перейти сразу к разделу Настройте сопоставление групп на стороне Keycloak.

  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-образа, то параметры входа по умолчанию:

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

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

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

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

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

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

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

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

  3. В правом верхнем углу страницы нажмите кнопку Создать федерацию. В открывшемся окне:

    1. Задайте имя федерации, например demo-federation. Имя должно быть уникальным в каталоге.

    2. При необходимости добавьте описание.

    3. В поле Время жизни cookie укажите время, в течение которого браузер не будет требовать у пользователя повторной аутентификации.

    4. В поле IdP Issuer вставьте ссылку вида:

      http://<IP_или_URL_Keycloak>:8080/realms/master

    5. В поле Ссылка на страницу для входа в IdP вставьте ссылку вида:

      http://<IP_или_URL_Keycloak>:8080/realms/master/protocol/saml

      В ссылке допустимо использовать только протоколы HTTP и HTTPS.

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

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

    7. (Опционально) Чтобы все запросы аутентификации от Yandex Cloud содержали цифровую подпись, включите опцию Подписывать запросы аутентификации. Потребуется установить SAML-сертификат Yandex Cloud на стороне поставщика удостоверений.

      В появившемся блоке Сертификаты SAML появится информация о действующем SAML-сертификате Yandex Cloud.

      Нажмите Скачать и сохраните скачанный файл сертификата. Он потребуется для установки на ваш IdP-сервер.

      Совет

      Следите за сроком действия сертификатов и устанавливайте новые сертификаты до истечения срока действия используемых. Перевыпущенный SAML-сертификат Yandex Cloud необходимо заранее скачать и установить на стороне IdP-провайдера и в вашей федерации.

      Скачать и установить сертификат Yandex Cloud вы можете и после создания федерации.

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

    8. Включите опцию Принудительная повторная аутентификация (ForceAuthn) в IdP, чтобы задать значение true для параметра ForceAuthn в запросе аутентификации SAML. При включении этой опции поставщик удостоверений (Identity Provider, IdP) запрашивает у пользователя аутентификацию по истечении сессии в Yandex Cloud.

    9. Нажмите кнопку Создать федерацию.

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

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

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

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

  3. Нажмите на строку с федерацией, для которой нужно добавить сертификат — demo-federation.

  4. Внизу страницы в блоке Сертификаты нажмите кнопку Добавить сертификат.

  5. Введите название сертификата и укажите путь к файлу keycloak-cert.cer.

  6. Нажмите кнопку Добавить.

Совет

Не забывайте своевременно перевыпускать сертификаты и добавлять их в федерацию.

Чтобы не пропустить момент окончания срока действия сертификата, подпишитесь на уведомления от организации. Уведомления направляются подписанным пользователям за 60, 30 и 5 дней до момента прекращения действия сертификата, а также после того, как сертификат становится недействительным.

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

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

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

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

  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

  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. Войдите в сервис Yandex Cloud Organization.

  2. Создайте группу пользователей yc_demo_group в Cloud Organization и выдайте ей права на просмотр ресурсов в облаке или отдельном каталоге (роль viewer).

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

  4. Выберите созданную ранее федерацию demo-federation и перейдите на вкладку IdP-группы.

  5. Включите опцию Маппинг групп в IdP.

  6. Нажмите кнопку Добавить группу.

  7. В поле Имя группы введите имя группы в Keycloak — kc_demo_group.

  8. В поле IAM-группа выберите из списка имя группы в Yandex Cloud Organization — yc_demo_group.

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

  1. Опишите в конфигурационном файле Terraform параметры создаваемых ресурсов:

    # Создание группы пользователей
resource "yandex_organizationmanager_group" "my-group" {
  name            = "yc_demo_group"
  organization_id = "demo-federation"
}

# Назначение роли viewer на каталог
resource "yandex_resourcemanager_folder_iam_member" "viewers" {
  folder_id = "<идентификатор_каталога>"
  role      = "viewer"
  member    = "group:${yandex_organizationmanager_group.my-group.id}"
}

# Включение сопоставления групп федеративных пользователей
resource "yandex_organizationmanager_group_mapping" "my_group_map" {
  federation_id = "demo-federation"
  enabled       = true
}

# Настройка сопоставления групп федеративных пользователей
resource "yandex_organizationmanager_group_mapping_item" "group_mapping_item" {
  federation_id     = "demo-federation"
  internal_group_id = yandex_organizationmanager_group.my-group.id
  external_group_id = "kc_demo_group"

  depends_on = [yandex_organizationmanager_group_mapping.group_mapping]
}

    Где:

    • folder_id — каталог, на который назначается роль.

    Подробнее см. в описаниях ресурсов yandex_organizationmanager_group_mapping и yandex_organizationmanager_group_mapping_item в документации провайдера Terraform.

  2. Создайте ресурсы:

    1. В терминале перейдите в папку, где вы отредактировали конфигурационный файл.

    2. Проверьте корректность конфигурационного файла с помощью команды:

      terraform validate

      Если конфигурация является корректной, появится сообщение:

      Success! The configuration is valid.

    3. Выполните команду:

      terraform plan

      В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.

    4. Примените изменения конфигурации:

      terraform apply

    5. Подтвердите изменения: введите в терминале слово yes и нажмите Enter.

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

  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 и у него есть права на просмотр ресурсов в соответствии с ролью, назначенной для группы.

Предыдущая
Сопоставление групп пользователей в Microsoft Entra ID
Следующая
Сервисный аккаунт с профилем OS Login для управления ВМ с помощью Ansible