Note
Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。
作為獨立軟體供應商(ISV)打造多租戶 SaaS 應用程式,您可以透過控制客戶的加密金鑰,讓客戶對資料保護充滿信心。 您在 Microsoft Entra 租戶中託管 Foundry IQ(Azure AI 搜尋服務),而客戶則在自己的租戶中管理 Azure Key Vault 的金鑰。 它們可以撤銷金鑰存取權,以阻擋對加密資料的存取。 使用多租戶的 Microsoft Entra 應用程式,跨這些租戶啟用客戶管理金鑰(CMK)加密,且不授予您的使用者帳戶金鑰的直接存取權。
先決條件
租戶 A:租戶及建立 Foundry IQ 服務與相關物件(索引、同義詞清單、索引器、資料來源、向量工具、技能集)所需的權限。 支援客戶管理金鑰(CMK)需要基本定價等級或更高等級。
將 Foundry IQ 服務設定為 基於角色的存取 (建議為增強安全性,但非必需)。
租用戶 B: 具有 Azure Key Vault 和該租用戶上必要權限的獨立客戶租用戶:
- 金鑰保存庫 貢獻者:若您需要建立新的 金鑰保存庫,則需要此角色。
- 應用程式管理員 或 雲端應用程式管理員:使用任一角色為租戶 B 的多租戶應用程式建立服務主體。
- 金鑰保存庫 Crypto Officer:此角色是將新金鑰新增至 金鑰保存庫 的必要條件。
-
金鑰保存庫 Crypto Service Encryption 使用者:此角色必須指派給為已安裝多租戶應用程式建立的服務主體,才能授予該服務主體對 key vault 中客戶管理金鑰的存取權。 使用 金鑰保存庫 Data Access Administrator 來指派此角色。 有關角色指派需求,請參閱「使用 Azure RBAC 授予應用程式存取金鑰保存庫」。 您可以在以下
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-10-01開始提供。用戶端密碼:使用
accessCredentials屬性設定用戶端密碼。 這種做法安全性較低,且需要額外管理人員輪流保護秘密。
關於 Azure Key Vault 受管式 HSM 設定,請參閱「為 Foundry IQ 加密資料設定客戶管理金鑰」。
在租用戶 A 中建立多租用戶 Microsoft Entra 應用程式
使用 Azure CLI 來傳送要求。 包含 Foundry IQ 的服務提供者的租戶將被稱為 租戶 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)中配置 Foundry IQ 服務。 如需操作指引,請參閱「在 Azure 入口網站建立 Foundry IQ 服務」或在 Azure CLI 中使用 az 搜尋服務建立指令。
服務提供者使用租戶 A 中建立的多租戶 Microsoft Entra 應用程式註冊。記錄其應用程式(用戶端)ID。
服務提供者會設定一個使用者指派的受控識別,並將其指派給 Foundry IQ 服務。 如需如何操作的指引,請參閱 「建立使用者指派的管理識別碼」。
服務提供者會在應用程式上將使用者指派的受控識別設定為聯邦身分識別認證。 如需瞭解如何執行此操作,請參閱 「設定應用程式以信任受控識別」。
一旦服務提供者分享多租戶應用程式 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 中建立 Foundry IQ 物件,並使用儲存在 租戶 B 的客戶管理金鑰加密這些物件。如需有關如何在新的搜尋物件上設定客戶管理金鑰的指引,請參閱 「為 Foundry IQ 加密資料設定客戶管理金鑰」。
驗證聯合身分識別跨租用戶 CMK 組態
在您設定多租戶 Microsoft Entra 應用程式並將其連接到客戶的 金鑰保存庫 後,請在您的 Foundry IQ 服務(租戶 A)中建立測試物件來驗證安裝。 此範例建立索引,以確認 Foundry IQ 服務是否能使用聯合身份驗證存取客戶管理的金鑰。
請參閱 「為 Foundry IQ 加密資料設定客戶管理金鑰 」,了解如何建立 Foundry IQ 服務及使用客戶管理金鑰建立新的索引物件。
在建立索引之前,請在其
encryptionKey設定中填寫以下數值:-
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-10-01
如果請求成功,請檢查 encryptionKey 是否包含預期的金鑰與身分設定。 此檢查確認已儲存的設定,而非文件索引與查詢是否有效。
如果索引建立失敗且發生金鑰存取錯誤,請確認:
- 使用者指派的管理身份設定正確
- 聯邦身份憑證是在應用程式中設定的
- 金鑰保存庫 存取政策或 RBAC 角色指派是正確的
如果無法使用聯邦身份,請使用客戶端秘密。
如果同盟身分識別不是可行的選項,您可以將用戶端密碼新增至多租戶應用程式,以支援跨租戶 CMK 情境:
若要將客戶端密鑰新增至租用戶 A 中的多租用戶應用程式,請執行下列命令:
az ad app credential reset --id <multitenant-app-id> --append --end-date <end-date>此
--append參數保留現有的憑證。儲存此步驟的密碼輸出。 密碼輸出是 設定 Foundry IQ 中 CMK 的必填輸入。
對於
--end-date,請以 ISO 8601 格式指定租戶政策允許的未來日期。 儲存密碼後,不要再次執行憑證重設指令。
在租戶 B 中建立多租戶應用程式的服務主體
我們將包含 Azure 金鑰保存庫的租用戶稱為 租用戶 B。在租用戶 B 中,為租用戶 A 中的多租用戶應用程式建立服務主體。
登入租戶 B:
az login --tenant <tenant-B-id>使用在第一個步驟中輸出的多租戶應用程式 ID 來建立服務主體。
az ad sp create --id <multitenant-app-id>服務主體代表租戶 B 中的應用程式。當您指派 Key Vault 角色時,即表示您授權該服務主體使用租戶 B 中的金鑰。
檢閱下列命令中的 “appOwnerOrganizationId” ,以確認租用戶 A 與 B 之間的連結:
az ad sp show --id <multitenant-app-id>此命令會以 JSON 顯示服務主體詳細資料。 在輸出中尋找 “appOwnerOrganizationId” 欄位,以確認它符合租用戶 A 的識別碼。
從此步驟儲存服務主體的物件識別碼 (來自
"id"欄位)。 物件 ID 是設定 Foundry IQ 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 應用程式並將其連接到客戶的 金鑰保存庫 後,請在您的 Foundry IQ 服務(租戶 A)中建立測試物件來驗證安裝。 此範例建立索引以確認 Foundry IQ 服務能使用用戶端密鑰存取客戶管理的金鑰。
請參閱 「為 Foundry IQ 加密資料設定客戶管理金鑰 」,了解如何建立 Foundry IQ 服務及使用客戶管理金鑰建立新的索引物件。
使用 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-10-01
回應未回傳 applicationSecret。
如需如何輪替或管理金鑰的詳細資訊,請參閱 設定客戶管理的金鑰以進行資料加密。