Настройте ключи, управляемые клиентом, в разных арендаторах.

В этой статье описывается межтенантный сценарий, в котором поставщик услуг размещает Поиск с использованием ИИ Azure в собственном клиенте и включает шифрование customer-managed key (CMK), с помощью мультитенантного приложения Microsoft Entra.

В этой конфигурации клиент использует Azure Key Vault в собственном клиенте для управления ключом шифрования. Поставщик услуг не имеет доступа к этому ключу.

Предпосылки

• Тенант A: клиент и необходимые разрешения для создания службы Поиск с использованием ИИ Azure и связанных объектов (индексы, списки синонимов, индексаторы, источники данных, векторизаторы, наборы навыков). Для поддержки управляемых клиентом ключей (CMK) требуется базовая ценовая категория или более поздняя.

• Настройте службу поиска для доступа на основе ролей (рекомендуется для повышения безопасности, а не обязательно).

• Tenant B: Отдельный клиент с Azure Key Vault и необходимыми разрешениями для этого клиента:

  • Участник Key Vault: Эта роль необходима, если вам нужно создать новое хранилище ключей.
  • Разрешение на регистрацию приложений в Microsoft Entra ID: Чтобы установить многоарендное приложение, настроенное поставщиком услуг для межарендного CMK, необходимо иметь разрешение на создание регистраций приложений в Microsoft Entra ID. Обычно для этого требуется роль разработчика приложений или более высокая административная роль, например администратор приложений или глобальный администратор.
  • Сотрудник по криптографическим операциям Key Vault: Эта роль необходима для добавления нового ключа в хранилище ключей.
  • Пользователь службы шифрования Key Vault Crypto Service: Эту роль необходимо назначить субъекту-службе, созданному для установленного мультитенантного приложения, чтобы предоставить субъекту-службе доступ к ключу, управляемому клиентом, в хранилище ключей. Для этого необходимо иметь разрешение администратора доступа пользователей . Вы можете просмотреть GUID субъекта-службы (также известный как идентификатор объекта) в разделе: Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID

• Azure Key Vault также должен быть настроен для ролевой модели доступа.

• Azure CLI для отправки запросов.

Выбор подхода проверки подлинности

Вы можете настроить мультитенантное приложение Microsoft Entra для использования ключей, управляемых клиентом, в межтенантном сценарии с помощью одного из следующих подходов:

1. Поддержка федеративной идентификации (рекомендуется): настройте учетные данные федеративной идентификации Microsoft Entra (FIC) для управляемого удостоверения, назначаемого пользователем (UAMI). Этот подход использует токены управляемой идентификации и обменивает их на токены доступа, устраняя необходимость в долгоживущих секретах и соответствуя принципам федерации удостоверений для рабочих нагрузок. Для этого подхода требуется предварительная версия свойства federatedIdentityClientId, представленного в API версии 2026-05-01-preview.

2. Секреты клиента: настройка секрета клиента с помощью accessCredentials свойства. Такой подход менее безопасен и требует дополнительных действий по управлению для ротации и защиты секрета.

Создание мультитенантного приложения Microsoft Entra в клиенте A

Используйте Azure CLI для отправки запросов. Клиент поставщика услуг, содержащий Поиск с использованием ИИ Azure, будет называться клиентом A.

1. Получите идентификатор клиента: az account show --query tenantId --output tsv

2. Убедитесь, что вы вошли в клиент A: az login --tenant \<tenant-A-id\>

3. Создайте регистрацию приложения: az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs

4. Сохраните выходные данные идентификатора приложения на этом шаге.

Использовать поддержку федеративных удостоверений личности (предварительная версия)

Чтобы использовать федеративную идентификацию для поддержки сценария CMK между арендаторами:

1. Поставщик услуг настраивает службу AI Search в своем клиенте (Tenant A). Инструкции по этому использованию см. в статье Create a Search Service (на портале Azure) или с помощью команды az search service create в Azure CLI.

2. Поставщик услуг создает мультитенантную регистрацию приложения Microsoft Entra. Сведения о том, как это сделать, см. в статье Как зарегистрировать приложение в Microsoft Entra ID или используйте команду Azure CLI: az ad app create. Запишите идентификатор приложения (клиента) после завершения регистрации приложения.

3. Поставщик услуг настраивает управляемую идентификацию, назначаемую пользователем. Инструкции о том, как это сделать, см. в статье Управление назначаемыми пользователем управляемыми удостоверениями с помощью портала Azure или Управление назначаемыми пользователем управляемыми удостоверениями с помощью Azure CLI.

4. Поставщик службы настраивает назначаемые пользователем управляемые удостоверения как учетные данные федеративной идентификации для приложения. Инструкции о том, как это сделать, см. в разделе Настройка приложения для доверия к внешнему поставщику удостоверений.

5. Когда поставщик услуг предоставляет идентификатор мультитенантного приложения, клиент предоставляет приложению поставщика услуг доступ к Key Vault в клиенте (клиент B). Чтобы установить приложение в арендаторе B, необходимо создать субъект-службу с идентификатором многоарендного приложения. Чтобы создать субъект-службу, сформируйте URL-адрес admin-consent и предоставьте согласие для всего арендатора или используйте команду az ad sp в Azure CLI.

6. Если у клиента еще нет хранилища ключей для использования, ознакомьтесь с Краткое руководство по началу работы — создание Azure Key Vault с помощью портала Azure или Краткое руководство по началу работы — создание Azure Key Vault с помощью Azure CLI. Для Key Vault необходимо установить модель разрешений «управление доступом на основе ролей Azure (RBAC)» и предоставить мультитенантному приложению поставщика услуг разрешение, назначив ему роль Key Vault Crypto Service Encryption User. Затем клиент может создать ключ шифрования. Сведения о том, как это сделать, см. в разделе Предоставление приложениям разрешения на доступ к хранилищу ключей Azure с помощью Azure RBAC.

После завершения этих действий поставщик услуг теперь имеет следующее:

• Идентификатор приложения для мультитенантного приложения, установленного в арендаторе клиента, которому предоставлен доступ к ключу, управляемому клиентом.

• Управляемое удостоверение, настроенное в качестве федеративных учетных данных для мультитенантного приложения.

• сведения о расположении ключа в хранилище ключей клиента.

С помощью этих трех параметров поставщик услуг теперь может создавать объекты в Поиск с использованием ИИ Azure в Tenant A, которые можно зашифровать с помощью ключа, управляемого клиентом и хранящегося в Tenant B. Сведения о настройке ключей, управляемых клиентом, для новых объектов поиска см. в разделе Настройка ключей, управляемых клиентом, для зашифрованных данных Поиск с использованием ИИ Azure.

Проверьте межтенантную конфигурацию CMK для федеративной идентификации

После настройки мультитенантного приложения Microsoft Entra и подключения его к Key Vault клиента проверьте настройку, создав тестовый объект в службе поиска (клиент A). В этом примере создается индекс для подтверждения того, что служба поиска может получить доступ к ключу, управляемому клиентом, с помощью проверки подлинности федеративного удостоверения.

1. Инструкции по созданию службы поиска и нового объекта индекса в Поиск с использованием ИИ Azure с использованием ключа, управляемого клиентом, см. в статье Настройка ключей, управляемых клиентом, для зашифрованных данных Поиск с использованием ИИ Azure.

2. После создания объекта индекса необходимо заполнить следующее:

   • keyVaultUri: адрес URI, полученный от клиента.
   • keyVaultKeyName: имя ключа, предоставленное клиентом.
   • keyVaultKeyVersion: ключевая версия от клиента.
   • userAssignedIdentity: <subscription-id> и <resource-group> из вашего тенанта, а <identity-name> — это имя управляемого удостоверения, назначаемого пользователем.
   • federatedIdentityClientId: это значение свойства, <application-client-id>будет идентификатором мультитенантного приложения (клиента).

   {
     "name": "cross-tenant-cmk-test",
     "fields": [
       {
         "name": "id",
         "type": "Edm.String",
         "key": true
       }
     ],
     "encryptionKey": {
       "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
       "keyVaultKeyName": "<key-name>",
       "keyVaultKeyVersion": "<key-version>",
       "identity": {
         "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
         "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>",
         "federatedIdentityClientId": "<application-client-id>"
       }
     }
   }
   

3. Проверьте индекс, отправив GET запрос: GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

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

Если создание индекса завершается ошибкой доступа к ключу, убедитесь, что:

• Управляемая идентичность, назначаемая пользователем, настроена правильно
• В приложении заданы учетные данные федеративного удостоверения.
• Политика доступа Key Vault или назначения ролей RBAC настроены правильно

Используйте секрет клиента (если федеративная идентификация невозможна)

Если федеративная идентификация не подходит, можно добавить секрет клиента в мультитенантное приложение, чтобы поддерживать сценарий CMK между арендаторами:

1. Чтобы добавить секрет клиента в мультитенантное приложение в клиенте A, выполните следующую команду:

   az ad app credential reset --id <multitenant-app-id>

2. Сохраните выходные данные паролей на этом шаге. Вывод пароля является обязательным входным параметром для настройки CMK в службе "Поиск ИИ Azure".

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

   az ad app credential reset --id <multitenant-app-id> --end-date <end-date>

   Параметр end-date принимает дату в формате ISO 8601. Например: az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31.

Создание субъекта-службы в клиенте B для мультитенантного приложения

Мы называем клиента, содержащего Azure Key Vault, клиентом B. В клиенте B создайте учетную запись службы для многопользовательского приложения в клиенте A.

1. Войдите в клиент B:

   az login --tenant <tenant-B-id>

2. Создайте субъект-службу с помощью выходных данных идентификатора мультитенантного приложения на первом шаге:

   az ad sp create --id <multitenant-app-id>

   Этот субъект-служба является экземпляром мультитенантного приложения в клиенте A. Роли, назначенные этому субъекту-службе в клиенте B, также назначаются мультитенантным приложениям в клиенте A.

3. Проверьте связь между арендатором A и B, проверьте "appOwnerOrganizationId" в следующей команде:

   az ad sp show --id <multitenant-app-id>

   Эта команда отображает сведения о субъекте-службе в ФОРМАТЕ JSON. Найдите поле appOwnerOrganizationId в выходных данных, чтобы подтвердить соответствие идентификатора клиента A.

4. Сохраните идентификатор объекта основной учетной записи службы (из поля "id") на этом шаге. Идентификатор объекта — это обязательный вход для настройки CMK в службе "Поиск ИИ Azure".

5. Получите идентификатор ресурса для Azure Key Vault:

   az keyvault show --name <key-vault-name> --query id --output tsv

6. Назначьте роль пользователя шифрования службы Key Vault в хранилище ключей клиента B новому служебному принципалу.

   az role assignment create --assignee <service-principal-object-id> --role "Key Vault Crypto Service Encryption User" --scope <key-vault-resource-id>

   Пример этого назначения может выглядеть следующим образом:

   az role assignment create --assignee 00001111-aaaa-2222-bbbb-3333cccc4444 --role "Key Vault Crypto Service Encryption User" --scope /subscriptions/87654321-4321-4321-4321-210987654321/resourceGroups/myKeyVaultRG/providers/Microsoft.KeyVault/vaults/myCompanyKeyVault

Проверьте межтенантную конфигурацию CMK для секрета клиента

После настройки мультитенантного приложения Microsoft Entra и подключения его к Key Vault клиента проверьте настройку, создав тестовый объект в службе поиска (клиент A). В этом примере создается индекс для подтверждения того, что служба поиска может получить доступ к ключу, управляемому клиентом, с помощью секрета клиента.

1. Инструкции по созданию службы поиска и нового объекта индекса в Поиск с использованием ИИ Azure с использованием ключа, управляемого клиентом, см. в статье Настройка ключей, управляемых клиентом, для зашифрованных данных Поиск с использованием ИИ Azure.

2. Портал Azure можно использовать для добавления индекса и предоставления этого JSON-файла или использования клиента REST для отправки запроса Create Index. После создания объекта индекса необходимо заполнить следующее:

   • keyVaultUri: адрес URI, полученный от клиента.
   • keyVaultKeyName: имя ключа, предоставленное клиентом.
   • keyVaultKeyVersion: ключевая версия от клиента.
   • accessCredentials: applicationId — это что-то вроде 00001111-aaaa-2222-bbbb-3333cccc4444, а applicationSecret — это значение, которое вы только что создали.

{
  "name": "cross-tenant-cmk-test",
  "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true
        }
      ],
 "encryptionKey": {
        "keyVaultUri": "https://<key-vault-name>.vault.azure.net/",
        "keyVaultKeyName": "<key-name>",
        "keyVaultKeyVersion": "<key-version>",
    "accessCredentials": {
      "applicationId": "<application-client-id>",
      "applicationSecret": "<application-client-secret>"
    }
  }
}

Убедитесь, что индекс был успешно создан:

GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-04-01

Дополнительные сведения о смене ключей или управлении ими см. в разделе "Настройка ключей, управляемых клиентом" для шифрования данных.