[Документация Yandex Cloud](../../index.md) > [Практические руководства](../index.md) > [Безопасность](index.md) > Управление федерациями удостоверений > Сопоставление групп пользователей > Сопоставление групп пользователей в Microsoft Entra ID

# Сопоставление групп пользователей в Microsoft Entra ID

Вы можете использовать сервис [Microsoft Entra ID](https://www.microsoft.com/ru-ru/security/business/identity-access/microsoft-entra-id) (бывший Azure Active Directory) для аутентификации пользователей в организации.

Чтобы настроить сопоставление (mapping) групп пользователей в Entra ID и групп пользователей в [федерации удостоверений](../../organization/concepts/add-federation.md):

1. [Начните настройку приложения в Azure](#azure-settings-begin).
1. [Создайте федерацию в Yandex Identity Hub](#create-federation).
1. [Добавьте SAML-сертификат приложения в федерацию](#add-certificate).
1. [Завершите настройку приложения](#azure-settings-end).
1. [Настройте сопоставление групп на стороне приложения](#azure-mapping).
1. [Настройте сопоставление групп на стороне федерации](#org-mapping).
1. [Проверьте работу аутентификации](#test-auth).

## Перед началом работы {#before-you-begin}

Убедитесь, что у вас есть доступ к следующим службам на [портале Azure](https://portal.azure.com/):

* Корпоративные приложения.
* Microsoft Entra ID.

## Начните настройку приложения в Azure {#azure-settings-begin}

В роли поставщика удостоверений (IdP) выступает приложение в Microsoft Azure с настроенной технологией единого входа (Single Sign-On, SSO). Чтобы создать приложение и начать его настройку:

1. [Перейдите на портал Azure](https://portal.azure.com/).
1. В разделе **Службы Azure** выберите **Корпоративные приложения**.
1. На панели слева выберите раздел **Корпоративные приложения** → **Все приложения**.
1. Нажмите кнопку **Новое приложение**.
1. На странице **Обзор коллекции Microsoft Entra** нажмите кнопку **Создайте собственное приложение**.
1. В открывшемся окне:
    1. Введите название приложения, например `yandex-cloud-saml`.
    1. Выберите опцию **Интеграция с любыми другими приложениями, которых нет в коллекции (вне коллекции)**.
    1. Нажмите кнопку **Создать**.

    После создания приложения откроется его страница.

1. На панели слева выберите раздел **Единый вход**.
1. Выберите режим единого входа **SAML**.

    Откроется страница **Вход на основе SAML**.

1. Скачайте SAML-сертификат приложения, который используется для подписи сообщений от Entra ID:

    1. Найдите блок **Сертификаты SAML** → **Сертификат для подписи маркера**.
    1. Скачайте сертификат по ссылке в поле **Сертификат (Base64)**.

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

    1. Найдите блок **Настройка yandex-cloud-saml**.

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

    1. Сохраните необходимые реквизиты:

        * **URL-адрес входа** следующего вида:

            ```text
            https://login.microsoftonline.com/<идентификатор_тенанта>/saml2
            ```

        * **Идентификатор Microsoft Entra** следующего вида:

            ```text
            https://sts.windows.net/<идентификатор_тенанта>/
            ```

{% note info %}

Настройка входа на основе SAML для приложения будет продолжена после создания федерации удостоверений.

Не закрывайте вкладку браузера, в которой выполняется настройка.

{% endnote %}

## Создайте федерацию Yandex Identity Hub {#create-federation}

{% list tabs group=instructions %}

- Интерфейс Cloud Center {#cloud-center}

  1. Перейдите в сервис [Yandex Identity Hub](https://kz.center.yandex.cloud/organization).

  1. На панели слева выберите ![icon-federation](../../_assets/console-icons/vector-square.svg) **Федерации**.

  1. В правом верхнем углу страницы нажмите кнопку ![Circles3Plus](../../_assets/console-icons/circles-3-plus.svg) **Создать федерацию**. В открывшемся окне:

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

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

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

      1. В поле **IdP Issuer** вставьте идентификатор Microsoft Entra, [полученный в ходе настройки приложения Azure](#azure-settings-begin).

      1. В поле **Ссылка на страницу для входа в IdP** вставьте URL-адрес входа, полученный в ходе настройки приложения Azure.

      1. Включите опцию **Автоматически создавать пользователей**, чтобы автоматически добавлять пользователя в организацию после аутентификации. Если опция отключена, федеративных пользователей потребуется [добавить вручную](../../organization/operations/add-account.md#add-user-sso).

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

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

          В появившемся блоке **Сертификаты SAML** появится информация о действующем SAML-сертификате Yandex Cloud.
          
          Нажмите ![ArrowDownToLine](../../_assets/console-icons/arrow-down-to-line.svg) **Скачать** и сохраните скачанный файл сертификата. Он потребуется для установки на ваш IdP-сервер.
          
          {% note tip %}
          
          Следите за сроком действия сертификатов и устанавливайте новые сертификаты до истечения срока действия используемых. Перевыпущенный SAML-сертификат Yandex Cloud необходимо заранее [скачать и установить](../../organization/operations/renew-yc-certificate.md) на стороне IdP-провайдера и в вашей федерации.
          
          {% endnote %}

          [Скачать и установить сертификат](../../organization/operations/setup-federation.md#add-certificate-idp) Yandex Cloud вы можете и после создания федерации.

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

      1. Включите опцию **Принудительная повторная аутентификация (ForceAuthn) в IdP**, чтобы задать значение `true` для параметра [ForceAuthn](../../organization/saml/api-ref/Federation/index.md) в запросе аутентификации SAML. При включении этой опции поставщик удостоверений (Identity Provider, IdP) запрашивает у пользователя аутентификацию по истечении сессии в Yandex Cloud. Необязательный параметр.

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

{% endlist %}

## Добавьте SAML-сертификат приложения Azure в федерацию {#add-certificate}

Чтобы при аутентификации сервис Yandex Identity Hub мог проверить SAML-сертификат приложения, добавьте сертификат в федерацию:

{% list tabs group=instructions %}

- Интерфейс Cloud Center {#cloud-center}

  1. Войдите в сервис [Yandex Identity Hub](https://kz.center.yandex.cloud/organization).

  1. На панели слева выберите ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Федерации**.

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

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

  1. Введите название и описание сертификата.

  1. В поле **Способ** выберите `Текст` и вставьте содержимое [полученного ранее сертификата](#azure-settings-begin).

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

{% endlist %}

## Завершите настройку приложения Azure {#azure-settings-end}

1. Перейдите на вкладку браузера, в которой выполнялась настройка входа на основе SAML для приложения `yandex-cloud-saml`.
1. Укажите URL для перенаправления:

    1. Найдите блок **Базовая конфигурация SAML**.
    1. Нажмите кнопку **Изменить** в блоке.
    1. Укажите один и тот же URL для перенаправления в полях **Идентификатор (сущности)** и **URL-адрес ответа (URL-адрес службы обработчика утверждений)**.

        URL для перенаправления имеет вид:

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

        {% cut "Как получить идентификатор федерации" %}

        1. Войдите в сервис [Yandex Identity Hub](https://kz.center.yandex.cloud/organization).
        1. На панели слева выберите ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Федерации**.
        1. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля **Идентификатор**.

        {% endcut %}

    1. Нажмите кнопку **Сохранить** на панели справа.

1. (Опционально) Если при [создании федерации](#create-federation) в Yandex Identity Hub вы включили опцию **Подписывать запросы аутентификации**, то добавьте скачанный ранее SAML-сертификат Yandex Cloud в приложение:

    1. Найдите блок **Сертификаты SAML** → **Сертификаты для проверки (необязательно)** и нажмите кнопку **Изменить**.
    1. Включите опцию **Требовать сертификаты для проверки**.
    1. Нажмите кнопку **Отправить сертификат**.
    1. Загрузите нужный сертификат в формате PEM.
    
        Если вы не скачивали SAML-сертификат при создании федерации, вы можете скачать его на странице сведений о федерации в Yandex Identity Hub, нажав кнопку ![ArrowDownToLine](../../_assets/console-icons/arrow-down-to-line.svg) **Скачать сертификат** в поле **Подписывать запросы аутентификации**.
    1. Нажмите кнопку **Сохранить** на панели справа.

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

## Настройте сопоставление групп на стороне приложения Azure {#azure-mapping}

### Создайте пользователя {#create-user}

1. [Перейдите на портал Azure](https://portal.azure.com/).
1. В разделе **Службы Azure** выберите **Microsoft Entra ID**.
1. На панели слева выберите раздел **Пользователи** → **Все пользователи**.
1. Нажмите кнопку **Новый пользователь**. Выберите пункт **Создание нового пользователя** из выпадающего меню.
1. Перейдите на вкладку **Основные сведения**.
1. В поле **Имя субъекта-пользователя** укажите логин пользователя (например `az_demo_user`) в комбинации с доменом (например `example.com`).
1. В поле **Псевдоним почты** укажите адрес электронной почты. По умолчанию псевдоним совпадает с именем пользователя.

    Вы можете указать другой псевдоним:

    1. Отключите опцию **Сформировать на основе имени субъекта-пользователя**.
    1. Укажите нужный псевдоним.

    Например можно использовать псевдоним `ivan_ivanov` для пользователя `az_demo_user@example.com`.

1. В поле **Отображаемое имя** укажите имя пользователя, которое будет отображаться в интерфейсе, например `Ivan Ivanov`.
1. В поле **Пароль** укажите пароль пользователя, который будет использоваться при первом входе. По умолчанию пароль генерируется автоматически.

    Вы можете указать пароль вручную:

    1. Отключите опцию **Автоматическое создание пароля**.
    1. Укажите нужный пароль.

1. Убедитесь, что опция **Учетная запись включена** на вкладке **Основные сведения** включена.
1. Нажмите кнопку **Проверить и создать**.

### Создайте группу и добавьте в нее пользователя {#create-group}

1. [Перейдите на портал Azure](https://portal.azure.com/).
1. В разделе **Службы Azure** выберите **Microsoft Entra ID**.
1. Создайте группу:

    1. На панели слева выберите раздел **Группы** → **Все группы**.
    1. Нажмите кнопку **Создать группу**.
    1. Из выпадающего списка **Тип группы** выберите пункт `Группа безопасности`.
    1. В поле **Имя группы** укажите имя группы, например `az_demo_group`.
    1. В поле **Члены** нажмите ссылку **Нет выбранных участников**.
    1. В открывшемся окне отметьте пользователя `az_demo_user@example.com` и нажмите кнопку **Выбрать**.
    1. Нажмите кнопку **Создать**.

1. Получите идентификатор созданной группы:

    1. На панели слева выберите раздел **Группы** → **Все группы**.
    1. Найдите в списке группу `az_demo_group` и скопируйте ее идентификатор из столбца **ИД объекта**.

        Идентификатор имеет вид `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`.

### Настройте доступы для группы {#configure-azure-group-access}

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

1. [Перейдите на портал Azure](https://portal.azure.com/).
1. В разделе **Службы Azure** выберите **Корпоративные приложения**.
1. На панели слева выберите раздел **Корпоративные приложения** → **Все приложения**.
1. Выберите созданное ранее приложение `yandex-cloud-saml`.
1. На панели слева выберите **Пользователи и группы**.
1. Нажмите **Добавить пользователя или группу**.
1. В поле **Группы** нажмите **Не выбрано**.
1. В открывшемся окне отметьте группу `az_demo_group` и нажмите кнопку **Выбрать**.
1. Нажмите кнопку **Назначить**.
1. Нажмите кнопку **Сохранить**.

### Настройте сопоставление групп {#map-azure-group}

1. [Перейдите на портал Azure](https://portal.azure.com/).
1. В разделе **Службы Azure** выберите **Корпоративные приложения**.
1. На панели слева выберите раздел **Корпоративные приложения** → **Все приложения**.
1. Выберите созданное ранее приложение `yandex-cloud-saml`.
1. На панели слева выберите раздел **Единый вход**.
1. Найдите блок **Атрибуты и утверждения** и нажмите кнопку **Изменить**. Далее будут настроены нужные утверждения (claims).
1. Нажмите кнопку **Добавить утверждение о группе**.
1. В блоке **Какие группы, связанные с пользователем, следует возвратить в утверждении?** выберите опцию `Группы безопасности`.
1. Из выпадающего списка **Атрибут источника** выберите пункт `Идентификатор группы`.
1. Раскройте блок **Дополнительные параметры** и измените параметры:

    1. Включите опцию **Изменение имени утверждения группы**.
    1. В поле **Имя (необязательно)** введите `member`.

1. Нажмите кнопку **Сохранить** на панели справа.
1. Нажмите кнопку **Сохранить**.

## Настройте сопоставление групп на стороне федерации {#org-mapping}

{% note info %}

Чтобы настроить сопоставление [групп пользователей](../../organization/concepts/user-pools.md) на стороне Yandex Cloud, [назначьте](../../iam/operations/roles/grant.md#resource) пользователю одну из следующих [ролей](../../iam/concepts/access-control/roles.md):

* [`organization-manager.federations.editor`](../../organization/security/index.md#organization-manager-federations-editor);
* [`organization-manager.federations.admin`](../../organization/security/index.md#organization-manager-federations-admin);
* [`organization-manager.editor`](../../organization/security/index.md#organization-manager-editor);
* [`organization-manager.admin`](../../organization/security/index.md#organization-manager-admin);

Роль должна быть назначена на те группы, для которых настраивается сопоставление.

{% endnote %}

{% list tabs group=instructions %}

- Интерфейс Cloud Center {#cloud-center}

  1. Войдите в сервис [Yandex Identity Hub](https://kz.center.yandex.cloud/organization).

  1. [Создайте группу пользователей](../../organization/operations/create-group.md) `yc-demo-group` в Yandex Identity Hub и [выдайте ей права](../../organization/operations/access-group.md) на просмотр ресурсов в облаке или отдельном каталоге (роль `viewer`).

  1. На панели слева выберите ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Федерации**.

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

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

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

  1. В поле **Имя группы** введите идентификатор группы `az_demo_group`, [полученный ранее в Entra ID](#create-group).

     {% note warning %}

     При [настройке сопоставления групп на стороне Azure](#map-azure-group) был выбран идентификатор группы в качестве атрибута источника.

     Поэтому необходимо ввести именно идентификатор группы, а не ее имя.

     {% endnote %}

  1. В поле **IAM-группа** выберите из списка имя группы в Yandex Identity Hub — `yc-demo-group`.

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

- Terraform {#tf}

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

      ```hcl
      # Создание группы пользователей
      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 = "<идентификатор_ группы_az_demo_group>"

        depends_on = [yandex_organizationmanager_group_mapping.group_mapping]
      }
      ```

      Где:
      * `folder_id` — каталог, на который назначается роль.
      * `external_group_id` — идентификатор группы `az_demo_group`, [полученный ранее в Entra ID](#create-group).

         {% note warning %}

         При [настройке сопоставления групп на стороне Azure](#map-azure-group) был выбран идентификатор группы в качестве атрибута источника.

         Поэтому необходимо ввести именно идентификатор группы, а не ее имя.

         {% endnote %}

      Подробнее в описаниях ресурсов [yandex_organizationmanager_group_mapping](../../terraform/resources/organizationmanager_group_mapping.md) и [yandex_organizationmanager_group_mapping_item](../../terraform/resources/organizationmanager_group_mapping_item.md) в документации провайдера Terraform.

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

     1. В терминале перейдите в директорию с конфигурационным файлом.
     1. Проверьте корректность конфигурации с помощью команды:
     
        ```bash
        terraform validate
        ```
     
        Если конфигурация является корректной, появится сообщение:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Выполните команду:
     
        ```bash
        terraform plan
        ```
     
        В терминале будет выведен список ресурсов с параметрами. На этом этапе изменения не будут внесены. Если в конфигурации есть ошибки, Terraform на них укажет.
     1. Примените изменения конфигурации:
     
        ```bash
        terraform apply
        ```
     
     1. Подтвердите изменения: введите в терминале слово `yes` и нажмите **Enter**.

{% endlist %}

## Проверьте работу аутентификации {#test-auth}

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

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

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

    {% cut "Как получить идентификатор федерации" %}

    1. Войдите в сервис [Yandex Identity Hub](https://kz.center.yandex.cloud/organization).
    1. На панели слева выберите ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Федерации**.
    1. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля **Идентификатор**.

    {% endcut %}

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

1. Введите реквизиты пользователя `az_demo_user@example.com`, [созданного ранее в Entra ID](#create-user), и нажмите кнопку **Sign in**.

    После успешной аутентификации IdP-сервер перенаправит вас по URL `https://kz.console.yandex.cloud/federations/<идентификатор_федерации>`, который вы указали в настройках SAML для приложения Azure, а после — на главную страницу [консоли управления](https://kz.console.yandex.cloud).

1. Убедитесь, что пользователь, от имени которого был выполнен вход, входит в группу `yc-demo-group` и у него есть права на просмотр ресурсов в соответствии с ролью, назначенной для группы.