跨不同租戶設定客戶管理的金鑰

Note

Azure AI 搜尋服務可透過 Azure 入口網站、REST API 及 Azure SDK 取得。它同時也是 Foundry IQ 的基礎，這是一個管理式知識層，能將企業內容轉化為可重複使用、權限感知的知識庫，供 Microsoft Foundry 入口網站中的代理使用。

Important

標記（預覽）的功能、能力或屬性不受服務等級協議涵蓋，也不建議用於生產工作負載，且在正式上架前可能會有所變動或受限。 Azure AI 搜尋服務預覽條款適用於所有預覽功能，無論是獨立功能還是正式推出功能的一部分。

本文描述一種跨租戶情境，服務提供者在自己的租戶中承載Azure AI 搜尋服務，並利用多租戶Microsoft Entra應用程式啟用客戶管理金鑰（CMK）加密。

在此配置中，客戶會在自己的租戶中使用 Azure Key Vault 來管理加密金鑰。服務提供者無法取得此金鑰。

先決條件

租戶 A：租戶及建立 Azure AI 搜尋服務服務與相關物件（索引、同義詞列表、索引器、資料來源、向量器、技能集）所需的權限。支援客戶管理金鑰（CMK）需要基本定價等級或更高等級。
設定搜尋服務為基於角色的存取（建議提升安全性，但非必要）。
租用戶 B：具有 Azure Key Vault 和該租用戶必要權限的個別客戶租用戶：
- 金鑰保存庫貢獻者：如果你需要建立新的key vault，此角色是必不可少的。
- 在 Microsoft Entra ID：若要安裝服務提供者設定的跨租戶 CMK 多租戶應用程式，您必須擁有在 Microsoft Entra ID 中建立應用程式註冊的權限。這通常需要應用程式開發者角色或更高階的管理職務，例如應用程式管理員或全域管理員。
- 金鑰保存庫加密官員：此角色需為key vault新增金鑰。
- 金鑰保存庫加密服務加密使用者：此角色必須指派給為已安裝多租戶應用程式所建立的服務主體，以便授予服務主體對key vault中客戶管理金鑰的存取權。您必須取得使用者存取管理員權限才能做到這點。您可以在以下 Enterprise applications\<installed multitenant application>\Manage\Properties\Object ID欄位查看服務主體 GUID（亦稱為物件 ID）。
Azure Key Vault也必須設定為角色存取。
Azure CLI 用於發送請求。

選擇認證方法

您可以透過以下方法之一，將多租戶 Microsoft Entra 應用程式配置為在跨租戶情境中使用客戶管理的金鑰：

聯邦身份支援（預覽，建議）：設定 Microsoft Entra 聯邦身份憑證（FIC）並使用使用者指派的管理身份（UAMI）。此方法使用受管理身份憑證，並以存取憑證交換，消除長期秘密的需求，並與工作負載身份聯盟原則相符。此方法需要預覽 federatedIdentityClientId 特性，該特性在 API 版本 2026-05-01-preview中引入。
用戶端秘密：使用屬性 accessCredentials 設定用戶端秘密。這種做法安全性較低，且需要額外管理人員輪流保護秘密。

Note

Azure Key Vault 和 Azure Key Vault Managed HSM 使用相同的 API 和管理介面來處理客戶管理的金鑰。 Azure Key Vault 中任何支援的操作也都被 Azure Key Vault 管理 HSM 支援。

在租用戶 A 中建立多租用戶 Microsoft Entra 應用程式

使用 Azure CLI 來傳送要求。包含 Azure AI 搜尋服務的服務提供者租戶將被稱為租戶 A。

取得租戶識別碼： 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
儲存此步驟的應用程式識別碼輸出。

使用聯邦身份支援（預覽）

若要使用聯合身分識別來支援跨租用戶 CMK 案例：

服務提供者會在其租戶（租戶 A）中配置 AI 搜尋服務。有關如何操作的指引，請參閱 Create a Search Service（在 Azure 入口網站）或使用 Azure CLI 中的 az search service create 指令。
服務提供者會建立多租用戶 Microsoft Entra 應用程式註冊項目。有關如何操作的指引，請參閱如何在 Microsoft Entra ID 註冊應用程式，或使用 Azure CLI 指令：az ad app create。完成應用程式註冊後，請記錄應用程式（客戶）ID。
服務提供者會設定一個由使用者指派的管理身份。有關如何操作的指引，請參見使用 Azure portal或使用 Azure CLI 管理使用者指派的受管理身份。
服務提供者會在應用程式上將使用者指派的受管理身份設定為聯邦身份憑證。關於如何操作的指引，請參閱「設定應用程式以信任外部身份提供者」。
一旦服務提供者分享多租戶應用程式 ID，客戶便授權服務提供者的應用程式存取其租戶（租戶 B）中的金鑰保存庫。若要在租戶 B 中安裝該應用程式，必須使用多租用戶應用程式 ID 建立服務主體。要建立服務主體，請建構一個 admin-consent URL，並授予租戶全體同意，或在 Azure CLI 中使用 az ad sp 指令。
如果客戶尚未擁有可使用的金鑰保險庫，請參閱快速入門 - 使用Azure入口建立Azure Key Vault或快速入門 - 使用Azure CLI建立 Azure Key Vault。金鑰保存庫需要將權限模型設為「Azure 角色基礎存取控制（RBAC）」，並由服務提供者的多租戶應用程式透過指派金鑰保存庫加密服務使用者角色來獲得權限。客戶接著可以建立加密金鑰。有關如何操作的指引，請參見授權應用程式使用 Azure RBAC 存取 Azure 金鑰庫。

完成這些步驟後，服務提供者將擁有：

安裝在客戶租用戶中之多租用戶應用程式的應用程式識別碼，已獲得客戶自控金鑰的存取權。
在多租用戶應用程式上設定為聯合認證的受控識別。
客戶金鑰保存庫中的金鑰位置。

有了這三個參數，服務提供者現在可以在租戶 A建立Azure AI 搜尋服務物件，並可用儲存在租戶 B 的客戶管理金鑰加密。關於如何在新搜尋物件上設定客戶管理金鑰的指引，請參見 Configure customer-managed key for Azure AI 搜尋服務 encrypted data。

驗證聯合身分識別跨租用戶 CMK 組態

在設定多租戶 Microsoft Entra 應用程式並將其連接到客戶的金鑰保存庫後，請在你的搜尋服務（租戶 A）中建立測試物件來驗證設定。此範例建立索引以確認搜尋服務是否能利用聯邦身份驗證存取客戶管理的金鑰。

請參閱設定適用於 Azure AI 搜尋服務加密資料的客戶管理金鑰，以了解如何建立搜尋服務，以及建立使用客戶管理金鑰的新索引物件。

建立索引物件後，你需要填寫以下事項：

keyVaultUri：客戶提供的URI地址。
keyVaultKeyName：來自客戶的鍵名稱。
keyVaultKeyVersion：來自客戶的金鑰版本。
userAssignedIdentity：您租用戶中的 <subscription-id> 和 <resource-group>，而 <identity-name> 是使用者指派的受控識別名稱。
federatedIdentityClientId：這個屬性值， <application-client-id>將是多租戶應用程式（客戶端）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>"
    }
  }
}

透過發送 GET 請求來驗證索引： GET https://<search-service>.search.windows.net/indexes/cross-tenant-cmk-test?api-version=2026-08-01-preview

如果請求成功，表示跨租戶 CMK 設定運作正常。

如果索引建立失敗且發生金鑰存取錯誤，請確認：

使用者指派的管理身份設定正確
聯邦身份憑證是在應用程式中設定的
金鑰保存庫存取政策或 RBAC 角色指派是正確的

如果無法使用聯邦身份，請使用客戶端秘密。

如果同盟身分識別不是可行的選項，您可以將用戶端密碼新增至多租戶應用程式，以支援跨租戶 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 金鑰保存庫的租用戶稱為 租用戶 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" 欄位）。物件識別碼是在 Azure AI 搜尋服務中設定 CMK 的必要輸入。
取得 Azure 金鑰保存庫的資源識別碼：

az keyvault show --name <key-vault-name> --query id --output tsv
在租用戶 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 類似於 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

如需如何輪替或管理金鑰的詳細資訊，請參閱設定客戶管理的金鑰以進行資料加密。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-17