跨不同租户配置客户托管的密钥

本文介绍一种跨租户场景：服务提供商在自己的租户中托管 Azure AI 搜索，并使用多租户 Microsoft Entra 应用程序启用客户管理的密钥 (CMK) 加密。

在此配置中，客户在其自己的租户中使用Azure 密钥保管库来管理其加密密钥。服务提供商无权访问此密钥。

先决条件

Tenant A：租户和创建Azure AI 搜索服务和关联对象所需的权限（索引、同义词列表、索引器、数据源、向量器、技能集）。对客户管理的密钥（CMK）的支持需要基本定价层级或更高层级。
为基于角色的访问配置搜索服务（建议增强安全性，不需要）。
租户 B：具有 Azure 密钥保管库的单独客户租户以及对该租户的必要权限：
- 密钥保管库参与者：如果需要创建新的key vault，则需要此角色。
- 在 Microsoft Entra ID 中注册应用程序的权限：若要安装由服务提供商为跨租户 CMK 配置的多租户应用，您必须具有在 Microsoft Entra ID 中创建应用注册的权限。这通常需要应用程序开发人员角色或更高的管理角色，例如应用程序管理员或全局管理员。
- 密钥保管库 Crypto Officer：此角色是向key vault添加新密钥所必需的。
- 密钥保管库加密服务加密用户：必须将此角色分配给为已安装的多租户应用程序创建的服务主体，以便向服务主体授予对key vault中客户管理的密钥的访问权限。必须具有用户访问管理员权限才能执行此操作。您可以在以下位置查看服务主体 GUID（也称为对象 ID）：Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID。
Azure 密钥保管库还必须配置为基于角色的访问。
用于发送请求的 Azure CLI。

选择身份验证方法

可以使用以下方法之一将多租户Microsoft Entra应用程序配置为在跨租户方案中使用客户管理的密钥：

联合标识支持（推荐）：配置 Microsoft Entra 联合标识凭据 (FIC) 以使用用户分配的托管标识 (UAMI)。此方法使用托管标识令牌并将其交换为访问令牌，无需长期机密并符合工作负荷标识联合原则。此方法需要 API 版本federatedIdentityClientId中引入的预览2026-05-01-preview属性。
客户端机密：使用 accessCredentials 属性配置客户端密码。这种方法不太安全，需要额外的管理来轮换和保护机密。

注释

Azure 密钥保管库和Azure 密钥保管库托管 HSM 对客户管理的密钥使用相同的 API 和管理接口。 Azure 密钥保管库 Managed HSM 也支持 Azure 密钥保管库支持的任何操作。

在租户 A 中创建多租户Microsoft Entra应用程序

使用Azure CLI发送请求。包含Azure AI 搜索的服务提供商租户将称为租户 A。

获取租户 ID： az account show --query tenantId --output tsv
请确保你已登录到租户 A：az login --tenant \<tenant-A-id\>
创建应用程序注册： az ad app create --display-name cross-tenant-auth --sign-in-audience AzureADMultipleOrgs
保存此步骤中的应用 ID 输出。

将客户端密码添加到多租户应用程序

使用客户端密码（如果使用联合标识不是选项）

如果联合标识不是选项，可以将客户端密码添加到多租户应用程序以支持跨租户 CMK 方案：

若要将客户端密码添加到租户 A 中的多租户应用程序，请运行以下命令：

az ad app credential reset --id <multitenant-app-id>
保存此步骤中的密码输出。密码输出是Azure AI 搜索中设置 CMK所需的输入。
若要指定客户端密码过期的时间，可以指定此命令的结束日期参数。

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

结束日期参数接受 ISO 8601 格式的日期。例如： az ad app credential reset --id <multitenant-app-id> --end-date 2026-12-31。

在租户 B 中为多租户应用程序创建服务主体

我们将包含Azure 密钥保管库的租户称为 tenant B。在租户 B 中，为租户 A 中的多租户应用程序创建服务主体。

登录到租户 B：

az login --tenant <tenant-B-id>
使用第一步中的多租户应用 ID 输出创建服务主体：

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

此服务主体是租户 A 中多租户应用程序的实例。分配给租户 B 中此服务主体的角色也分配给租户 A 中的多租户应用程序。
在以下命令中查看“appOwnerOrganizationId”，验证租户 A 和 B 之间的链接：

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

此命令以 JSON 格式显示服务主体详细信息。在输出中查找“appOwnerOrganizationId”字段，确认它与租户 A 的 ID 匹配。
保存此步骤中服务主体的对象 ID（来自 "id" 字段）。对象 ID 是用于在 Azure AI 搜索中设置 CMK 的必需输入。
获取Azure 密钥保管库的资源 ID：

az keyvault show --name <key-vault-name> --query id --output tsv
将密钥保管库 Crypto Service Encryption User角色分配给租户 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应用程序并将其连接到客户的密钥保管库后，请在搜索服务（租户 A）中创建测试对象来验证设置。此示例创建一个索引来确认搜索服务可以使用客户端密码访问客户管理的密钥。

有关如何使用客户管理的密钥创建搜索服务和新的索引对象的指导，请参阅配置Azure AI 搜索加密数据的客户管理的密钥。
可以使用 Azure 门户添加索引并提供此 JSON，或使用 REST 客户端发送 Create Index 请求。创建索引对象后，需要填写以下内容：
- keyVaultUri：客户的 URI 地址。
- keyVaultKeyName：客户的密钥名称。
- keyVaultKeyVersion：客户提供的密钥版本。
- accessCredentials：applicationId 看起来会类似于“12345678-1234-1234-1234-123456789012”，以及刚刚创建的 applicationSecret。

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

验证是否已成功创建索引：

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

有关如何轮换或管理密钥的详细信息，请参阅配置客户管理的密钥进行数据加密。

Last updated on 2026-06-30