在 Azure AI 搜尋服務中設定客戶管理的數據加密金鑰

發行項
04/03/2024

Azure AI 搜尋會自動使用服務管理的金鑰加密待用數據。如果需要更多保護，您可以使用您在 Azure 金鑰保存庫中建立和管理的金鑰，以另一個加密層來補充預設加密。

本文將逐步引導您完成設定客戶自控密鑰（CMK）或「自備密鑰」（BYOK）加密的步驟。以下是一些要記住的要點：

CMK 加密是在個別物件上頒布的。如果您需要整個搜尋服務的 CMK，請設定強制執行原則。
CMK 加密取決於 Azure 金鑰保存庫。您可以建立自己的加密金鑰，並將其儲存在金鑰保存庫中，或使用 Azure 金鑰保存庫 API 來產生加密金鑰。 Azure 金鑰保存庫必須與 Azure AI 搜尋位於相同的訂用帳戶和租使用者中。 Azure AI 搜尋會透過系統或使用者管理的身分識別連線來擷取您的受控密鑰。此行為需要這兩個服務共用相同的租使用者。
建立物件時，CMK 加密會變成可運作。您無法加密已經存在的物件。每當物件儲存到磁碟時，就會發生 CMK 加密，無論是長期儲存的數據，還是短期記憶體的暫存數據。使用 CMK 時，磁碟永遠不會看到未加密的數據。

注意

如果索引已加密 CMK，則只有在搜尋服務可以存取密鑰時，才能存取索引。如果撤銷存取權，索引將無法使用，而且在刪除索引或還原密鑰的存取權之前，無法調整服務。

CMK 加密的物件

可加密的物件包括索引、同義字清單、索引器、數據源和技能集。加密的計算成本很高，無法解密，因此只會加密敏感性內容。

加密會透過下列內容執行：

索引和同義字清單內的所有內容，包括描述。
針對索引器、數據源和技能集，只會加密儲存連接字串、描述、密鑰和使用者輸入的欄位。例如，技能集具有 Azure AI 服務密鑰，而某些技能接受使用者輸入，例如自定義實體。在這兩種情況下，密鑰和使用者對技能的輸入都會加密。

完整雙重加密

當您引進 CMK 加密時，您會加密內容兩次。針對上一節所述的物件和欄位，內容會先使用您的 CMK 加密，第二個是使用 Microsoft 管理的金鑰加密。內容會在數據磁碟上對長期記憶體進行雙重加密，以及用於短期儲存的暫存磁碟上。

啟用 CMK 加密會增加索引大小，並降低查詢效能。根據迄今為止的觀察，您可以預期查詢時間會增加 30-60%，不過實際效能會根據索引定義和查詢類型而有所不同。因為效能會降低，建議您只在真正需要此功能的索引上啟用此功能。

雖然所有區域現在都提供雙重加密，但支援已分兩個階段推出：

第一次推出是在 2020 年 8 月 1 日，包括下面所列的五個區域。搜尋服務在下列區域中建立的數據磁碟支援 CMK，但不支援暫存磁碟：
- 美國西部 2
- 美國東部
- 美國中南部
- US Gov 維吉尼亞州
- US Gov 亞利桑那州
2021 年 5 月 13 日的第二個推出新增了暫存磁碟的加密，並將 CMK 加密延伸至所有支持的區域。

如果您是從第一次推出期間建立的服務使用 CMK，而且也想要透過暫存磁碟進行 CMK 加密，則必須在您選擇的區域中建立新的搜尋服務，並重新部署內容。

必要條件

在此案例中會使用下列工具和服務。

計費層上的 Azure AI 搜尋（任何區域中的基本或更新版本）。
Azure 金鑰保存庫，您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來建立密鑰保存庫。在與 Azure AI 搜尋相同的訂用帳戶中建立資源。金鑰保存庫必須已啟用虛刪除與清除保護。
Microsoft Entra ID。如果您沒有租使用者，請設定新的租使用者。

您應該有可建立加密物件的搜尋用戶端。在此程式代碼中，您會參考金鑰保存庫金鑰和應用程式註冊資訊。此程式代碼可以是運作中的應用程式，或原型程式代碼，例如 C# 程式代碼範例 DotNetHowToEncryptionUsingCMK。

提示

您可以使用 REST 用戶端或 Azure PowerShell 來建立包含加密金鑰參數的索引和同義字對應。您也可以使用 Azure SDK。不支援將索引鍵或同義字對應新增至入口網站。

金鑰保存庫秘訣

如果您不熟悉 Azure 金鑰保存庫，請檢閱本快速入門以瞭解基本工作：使用 PowerShell 從 Azure 金鑰保存庫設定和擷取秘密。以下是使用金鑰保存庫的一些秘訣：

視需要使用多個金鑰保存庫。受控金鑰可以位於不同的金鑰保存庫中。搜尋服務可以有多個加密的物件，每個物件都以不同的客戶管理的加密密鑰進行加密，並儲存在不同的密鑰保存庫中。
啟用金鑰保存庫記錄，以便監視金鑰使用方式。
請記得在金鑰保存庫密鑰和 Active Directory 應用程式秘密和註冊的例行輪替期間遵循嚴格的程式。刪除舊的秘密和金鑰之前，請一律更新所有加密的內容，以使用新的秘密和密鑰。如果您錯過此步驟，就無法解密您的內容。

1 - 啟用清除保護

在第一個步驟中，請確定密鑰保存庫上已啟用虛刪除和清除保護。由於使用客戶管理的金鑰進行加密的本質，如果您的 Azure 金鑰保存庫金鑰已刪除，則沒有人可以擷取您的數據。

若要防止意外金鑰保存庫密鑰刪除所造成的資料遺失，必須在密鑰保存庫上啟用虛刪除和清除保護。默認會啟用虛刪除，因此只有在您故意停用時，您才會遇到問題。默認不會啟用清除保護，但 Azure AI 搜尋服務中客戶管理的密鑰加密是必要的。

您可以使用入口網站、PowerShell 或 Azure CLI 命令來設定這兩個屬性。

登入 Azure 入口網站並開啟您的金鑰保存庫概觀頁面。
在 [基本資訊] 底下的 [概觀] 頁面上，啟用虛刪除和清除保護。

執行 Connect-AzAccount 以設定您的 Azure 認證。

執行下列命令以連線到金鑰保存庫，並將取代 <vault_name> 為有效的名稱：

$resource = Get-AzResource -ResourceId (Get-AzKeyVault -VaultName "<vault_name>").ResourceId

Azure 金鑰保存庫會啟用虛刪除功能來建立。如果您的儲存庫已停用，請執行下列命令：
```
$resource.Properties | Add-Member -MemberType NoteProperty -Name "enableSoftDelete" -Value 'true'
```

啟用清除保護：

$resource.Properties | Add-Member -MemberType NoteProperty -Name "enablePurgeProtection" -Value 'true'

儲存您的更新：

Set-AzResource -resourceid $resource.ResourceId -Properties $resource.Properties

2 - 在金鑰保存庫中建立金鑰

如果您已在您想要使用的 Azure 金鑰保存庫中有金鑰，請略過密鑰產生，但收集金鑰標識碼。建立加密物件時，您需要此資訊。

登入 Azure 入口網站並開啟您的金鑰保存庫概觀頁面。
選取 左側的 [金鑰 ]，然後選取 [+ 產生/匯入]。
在 [建立金鑰] 窗格中，從 [選項] 清單中，選擇您要用來建立密鑰的方法。您可以產生新的金鑰、上傳現有的金鑰，或使用 還原備份 來選取金鑰的備份。
輸入金鑰的 [ 名稱 ]，並選擇性地選取其他金鑰屬性。
選取 [建立] 以開始部署。
選取金鑰，選取目前的版本，然後記下金鑰標識碼。它是由金鑰值 URI、金鑰名稱和金鑰版本所組成。您需要識別碼，才能在 Azure AI 搜尋服務中定義加密的索引。

3 - 建立安全性主體

您有數個選項可用來在執行時間存取加密金鑰。最簡單的方法是使用搜尋服務的受控識別和許可權來擷取密鑰。您可以使用系統或使用者受控識別。這麼做可讓您省略應用程式註冊和應用程式秘密的步驟，並簡化加密密鑰定義。

或者，您可以建立及註冊 Microsoft Entra 應用程式。搜尋服務會在要求上提供應用程式標識碼。

受控識別可讓您的搜尋服務向 Azure 金鑰保存庫進行驗證，而不需將認證（ApplicationID 或 ApplicationSecret）儲存在程式代碼中。這種類型的受控識別生命週期會系結至您的搜尋服務的生命週期，此生命週期只能有一個受控識別。如需受控識別運作方式的詳細資訊，請參閱什麼是 Azure 資源的受控識別。

讓您的搜尋服務成為受信任的服務。

防止您採用此方法的條件包括：

您無法直接將搜尋服務訪問許可權授與密鑰保存庫（例如，如果搜尋服務位於與 Azure 金鑰保存庫不同的 Microsoft Entra ID 租使用者中）。
需要單一搜尋服務才能裝載多個加密索引或同義字對應，每個索引鍵都會使用不同的密鑰保存庫，其中每個密鑰保存庫都必須使用不同的身分識別進行驗證。因為搜尋服務只能有一個受控識別，所以多個身分識別的需求會排除您案例的簡化方法。

重要

使用者管理的身分識別支援在補充使用規定下處於公開預覽狀態。

2021-04-01-Preview 管理 REST API 提供此功能。

登入 Azure 入口網站。
選取 [+ 建立新資源]。
在 [搜尋服務和市集] 搜尋列中，搜尋 [用戶指派的受控識別]，然後選取 [建立]。
為身分識別提供描述性名稱。
接下來，將使用者受控識別指派給搜尋服務。這可以使用 2021-04-01-preview 管理 API 來完成。

身分識別屬性接受類型和一或多個完整使用者指派的身分識別：
- type 是用於資源的身分識別類型。類型 'SystemAssigned， UserAssigned' 包含系統所建立的身分識別和一組使用者指派的身分識別。類型『None』會從服務中移除所有身分識別。
- userAssignedIdentities 包含使用者受控識別的詳細數據。
  - 使用者受控識別格式：
    - /subscriptions/subscription ID/resourcegroups/資源組名/providers/Microsoft.ManagedIdentity/userAssignedIdentities/managed identity name
如何將使用者受控識別指派給搜尋服務的範例：
```
PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/[search service name]?api-version=2021-04-01-preview
Content-Type: application/json

{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]": {}
    }
  }
} 
```

更新區 "encryptionKey" 段以使用身分識別屬性。將此要求傳送至您的搜尋服務時，請務必使用 2021-04-01-preview REST API 版本。

{
  "encryptionKey": {
    "keyVaultUri": "https://[key vault name].vault.azure.net",
    "keyVaultKeyName": "[key vault key name]",
    "keyVaultKeyVersion": "[key vault key version]",
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity" : "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]"
    }
  }
}

4 - 授與許可權

在此步驟中，您會在金鑰保存庫中建立存取原則。此原則會提供您向 Microsoft Entra ID 註冊的應用程式，以使用客戶管理的密鑰。

任何指定時間都可以撤銷訪問許可權。撤銷之後，任何使用該金鑰保存庫的搜尋服務索引或同義字對應都會變成無法使用。稍後還原金鑰保存庫訪問許可權會還原索引和同義字對應存取。如需詳細資訊，請參閱保護密鑰保存庫的存取。

仍在 Azure 入口網站中，開啟您的密鑰保存庫 [概觀] 頁面。
選取左側的 [ 存取原則 ]，然後選取 [+ 建立 ] 以啟動 [ 建立存取原則 精靈]。
在 [許可權] 頁面上，針對 [金鑰許可權]、[秘密許可權] 和 [憑證許可權] 選取 [取得]。針對金鑰上的 ** 密碼編譯作業，選取 [解除包裝金鑰 ] 和 [包裝金鑰 ]。
選取 [下一步]。
在 [ 準則] 頁面上，尋找並選取搜尋服務用來存取加密密鑰的安全性主體。這會是搜尋服務的系統管理或使用者受控識別，或已註冊的應用程式。
選取 [ 下一步 ] 和 [建立]。

重要

Azure AI 搜尋中的加密內容已設定為使用特定版本的特定 Azure 金鑰保存庫金鑰。如果您變更索引鍵或版本，必須先更新索引或同義字對應，才能刪除前一個索引鍵或同義字對應。若無法這麼做，將會轉譯索引或同義字對應無法使用。如果金鑰遺失，您將無法解密內容。

5 - 加密內容

當您建立物件時，會新增加密金鑰。若要在索引、同義字對應、索引器、數據源或技能集上新增客戶管理的密鑰，請使用搜尋 REST API 或 Azure SDK 來建立已啟用加密的物件。入口網站不允許在物件建立時使用加密屬性。

呼叫 Create API 以指定 encryptionKey 屬性：

將 encryptionKey 建構插入物件定義中。此屬性是與名稱和描述位於相同層級的第一層屬性。下列 REST 範例會顯示屬性放置。如果您使用相同的保存庫、金鑰和版本，您可以將相同的 “encryptionKey” 建構貼到每個物件定義中。

第一個範例顯示使用受控識別連線的搜尋服務的 “encryptionKey” ：

{
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660"
  }
}

第二個範例包含「accessCredentials」，如果您已在 Microsoft Entra ID 中註冊應用程式，則為必要專案：

{
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

一旦您在搜尋服務上建立加密物件，就可以像它類型的任何其他對象一樣使用它。加密對用戶和開發人員而言是透明的。

注意

這些密鑰保存庫詳細數據都不會被視為秘密，而且流覽至 Azure 入口網站中的相關 Azure 金鑰保存庫頁面，即可輕鬆擷取這些密鑰保存庫詳細數據。

6 - 設定原則

Azure 原則可協助強制執行組織標準，並大規模評估合規性。 Azure AI 搜尋有選擇性的內建原則，適用於全服務 CMK 強制執行。

在本節中，您會設定原則來定義搜尋服務的 CMK 標準。然後，您設定搜尋服務以強制執行此原則。

流覽至網頁瀏覽器中的內建原則。選取 [ 指派]
設定原則範圍。在 [參數] 區段中，取消核取 [僅顯示參數...]，並將 [效果] 設定為 [拒絕]。

在評估要求期間，符合拒絕原則定義的要求會標示為不符合規範。假設服務的標準是 CMK 加密，「拒絕」表示未指定 CMK 加密的要求不符合規範。
完成建立原則。
呼叫 Services - 更新 API，以在服務層級啟用 CMK 原則強制執行。

PATCH https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2022-11-01

{
    "properties": {
        "encryptionWithCmk": {
            "enforcement": "Enabled",
            "encryptionComplianceStatus": "Compliant"
        }
    }
}

REST 範例

本節顯示數個物件的 JSON，讓您可以查看物件定義中找出 “encryptionKey” 的位置。

索引加密

透過 REST API 建立新索引的詳細資料可以在建立索引（REST API）中找到，其中唯一的差異在於指定加密密鑰詳細數據做為索引定義的一部分：

{
 "name": "hotels",
 "fields": [
  {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
  {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
  {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
  {"name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene"},
  {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
  {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
  {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
  {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
  {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
  {"name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true}
 ],
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

您現在可以傳送索引建立要求，然後正常開始使用索引。

同義字對應加密

使用建立同義字對應 Azure AI 搜尋 REST API 建立加密的同義字對應。使用「encryptionKey」屬性來指定要使用的加密密鑰。

{
  "name" : "synonymmap1",
  "format" : "solr",
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

您現在可以傳送同義字對應建立要求，然後正常開始使用。

數據源加密

使用建立數據源（REST API）建立加密的數據源。使用「encryptionKey」屬性來指定要使用的加密密鑰。

{
  "name" : "datasource1",
  "type" : "azureblob",
  "credentials" :
  { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=datasource;AccountKey=accountkey;EndpointSuffix=core.windows.net"
  },
  "container" : { "name" : "containername" },
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

您現在可以傳送數據源建立要求，然後正常開始使用。

技能集加密

使用建立技能集 REST API 建立加密的技能集。使用「encryptionKey」屬性來指定要使用的加密密鑰。

{
    "name": "skillset1",
    "skills":  [ omitted for brevity ],
    "cognitiveServices": { omitted for brevity },
      "knowledgeStore":  { omitted for brevity  },
    "encryptionKey": (optional) { 
        "keyVaultKeyName": "myEncryptionKey",
        "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
        "keyVaultUri": "https://demokeyvault.vault.azure.net",
        "accessCredentials": {
            "applicationId": "00000000-0000-0000-0000-000000000000",
            "applicationSecret": "myApplicationSecret"}
    }
}

您現在可以傳送技能集建立要求，然後正常開始使用。

索引器加密

使用建立索引器 REST API 建立加密的索引器。使用「encryptionKey」屬性來指定要使用的加密密鑰。

{
  "name": "indexer1",
  "dataSourceName": "datasource1",
  "skillsetName": "skillset1",
  "parameters": {
      "configuration": {
          "imageAction": "generateNormalizedImages"
      }
  },
  "encryptionKey": {
    "keyVaultUri": "https://demokeyvault.vault.azure.net",
    "keyVaultKeyName": "myEncryptionKey",
    "keyVaultKeyVersion": "eaab6a663d59439ebb95ce2fe7d5f660",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

您現在可以傳送索引器建立要求，然後正常開始使用。

重要

雖然「encryptionKey」無法新增至現有的搜尋索引或同義字對應，但可能會藉由為三個密鑰保存庫詳細數據中的任何一個提供不同的值來更新它（例如，更新密鑰版本）。變更為新的金鑰保存庫索引鍵或新的金鑰版本時，使用密鑰的任何搜尋索引或同義字對應必須先更新為使用新的索引鍵\版本，才能刪除先前的 key\version。若無法這麼做，索引或同義字對應將無法使用，因為它無法在密鑰存取遺失後解密內容。雖然稍後還原金鑰保存庫訪問許可權將會還原內容存取。

使用加密的內容

使用客戶管理的金鑰加密，您可能會注意到索引編製和查詢的延遲，因為額外的加密/解密工作。 Azure AI 搜尋不會記錄加密活動，但您可以透過金鑰保存庫記錄來監視密鑰存取。建議您啟用記錄作為金鑰保存庫組態的一部分。

金鑰輪替預期會在一段時間內發生。每當輪替金鑰時，請務必遵循此順序：

判斷索引或同義字對應所使用的索引鍵。
在金鑰保存庫中建立新的金鑰，但保留原始金鑰可用。
更新索引或同義字對應上的 encryptionKey 屬性，以使用新的值。只有原本使用這個屬性建立的物件可以更新為使用不同的值。
停用或刪除金鑰保存庫中的上一個金鑰。監視金鑰存取，以確認正在使用新的金鑰。

基於效能考慮，搜尋服務最多會快取金鑰數小時。如果您停用或刪除金鑰而不提供新的金鑰，查詢會繼續暫時運作，直到快取到期為止。不過，一旦搜尋服務無法再解密內容，您就會收到下列訊息：「禁止存取。使用的查詢金鑰可能已被撤銷 - 請重試。

下一步

如果您不熟悉 Azure 安全性架構，請檢閱 Azure 安全性檔，特別是本文：

待用數據加密