在 Azure AI 搜尋服務中設定客戶自控金鑰以進行資料加密

發行項
06/29/2024

Azure AI 搜尋服務會使用服務管理的金鑰，來自動將待用資料加密。如果需要更多保護，您可以使用在 Azure Key Vault 中所建立及管理的金鑰，以其他的加密層來增補預設的加密。

本文章將逐步引導您設定「客戶自控金鑰」(CMK) 或「攜帶您自己的金鑰」(BYOK) 加密的步驟。請記住以下幾點：

CMK 加密是在個別的物件上制定的。如果您在整個搜尋服務中需要 CMK，請設定強制原則。
CMK 加密取決於 Azure Key Vault。您可以建立自己的加密金鑰，然後將其儲存在金鑰保存庫中，或是使用 Azure Key Vault API 來產生加密金鑰。 Azure Key Vault 必須與 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 Key Vault (您可以使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 來建立金鑰保存庫)。在與 Azure AI 搜尋服務相同的訂用帳戶中建立資源。金鑰保存庫必須已啟用虛刪除與清除保護。
Microsoft Entra ID。如果您沒有租用戶，請設定新的租用戶。

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

提示

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

金鑰保存庫秘訣

如果您不熟悉 Azure Key Vault，請檢閱本快速入門以了解基本工作：使用 PowerShell 從 Azure Key Vault 設定及擷取秘密。以下是使用 Key Vault 的一些秘訣：

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

1 - 啟用清除保護

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

為了防止因意外刪除 Key Vault 金鑰而導致資料遺失，必須在金鑰保存庫上啟用虛刪除和清除保護。依預設會啟用虛刪除，所以只有在您故意停用時才會遇到問題。清除保護依預設不會啟用，但在 Azure AI 搜尋服務中，客戶自控金鑰加密需要它。

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

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

執行 Connect-AzAccount 以設定您的 Azure 認證。
執行下列命令以連線到您的金鑰保存庫，並將 <vault_name> 取代為有效的名稱：
```
$resource = Get-AzResource -ResourceId (Get-AzKeyVault -VaultName "<vault_name>").ResourceId
```
Azure Key Vault 會透過啟用虛刪除來建立。如果它在您的保存庫上已停用，請執行下列命令：
```
$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 - 在 Key Vault 中建立金鑰

如果在 Azure Key Vault 中您已有想要使用的金鑰時，請跳過金鑰產生作業，但收集金鑰識別碼。建立加密物件時，您將需要此資訊。

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

3 - 建立安全性主體

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

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

受控識別可讓您的搜尋服務向 Azure Key Vault 進行驗證，而不需將認證 (ApplicationID 或 ApplicationSecret) 儲存在程式碼中。這種類型的受控識別生命週期會繫結到搜尋服務的生命週期，這只能有一個受控識別。如需受控識別如何運作的詳細資訊，請參閱什麼是 Azure 資源的受控識別。

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

讓您無法採用此方法的情況包括：

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

重要

根據補充使用條款，使用者受控識別支援處於公開預覽狀態。

管理 REST API 的 2021-04-01-Preview 版本引進了此功能。

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

身分識別屬性會採用類型和一或多個完整使用者指派的身分識別：
- type 是用於資源的身分識別類型。「SystemAssigned、UserAssigned」類型同時包含系統建立的識別和一組使用者指派的識別。 'None' 類型將從服務中刪除所有身分識別。
- userAssignedIdentities 包含使用者受控識別的詳細資料。
  - 受控識別格式：
    - /subscriptions/subscription ID/resourcegroups/資源群組名稱/providers/Microsoft.ManagedIdentity/userAssignedIdentities/受控識別名稱
如何將使用者受控識別指派給搜尋服務的範例：
```
PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/[search service name]?api-version=2024-06-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" 區段以使用身分識別屬性。將此要求傳送至搜尋服務時，請務必使用預覽版 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 - 授與權限

在此步驟中，您將在 Key Vault 中建立存取原則。此原則會為您向 Microsoft Entra ID 登錄的應用程式提供權限，以便能使用您的客戶自控金鑰。

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

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

重要

Azure AI 搜尋服務中的加密內容已設定為使用含特定版本的特定 Azure Key Vault 金鑰。如果您變更金鑰或版本，則必須更新索引或同義字對應才能使用它 (在您刪除舊的之前)。如果不這樣做，將導致索引或同義字對應無法使用。如果金鑰遺失了，您將無法對內容進行解密。

5 - 對內容進行加密

當您建立物件時，會新增加密金鑰。若要對索引、同義字對應、索引子、資料來源或技能集新增客戶自控金鑰，請使用 Search 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 Key Vault 頁面來輕鬆擷取。

6 - 設定原則

Azure 原則有助於強制執行組織標準及大規模評估合規性。 Azure AI 搜尋服務具有選擇性的內建原則 (適用於服務範圍 CMK 強制執行)。

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

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

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

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

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

REST 範例

本節顯示了數個物件的 JSON，以便您可以在物件定義中查看哪裡可以找到 "encryptionKey"。

索引加密

透過 REST API 建立新索引的詳細資料可以在 Create Index (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"
    }
  }
}

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

資料來源加密

使用 Create Data Source (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"
    }
  }
}

您現在可以傳送資料來源建立要求，然後正常開始使用它。

技能集加密

使用 Create Skillset 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"}
    }
}

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

索引子加密

使用 Create Indexer 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 Vault 金鑰或新的金鑰版本時，使用金鑰的任何搜尋索引或同義字對應必須加以更新才能使用新的 key\version (在刪除舊的 key\version 之前)。如果不這樣做，將導致索引或同義字對應無法使用，因為一旦金鑰存取遺失之後，它將無法對內容進行解密。雖然之後還原金鑰保存庫存取權限會還原內容存取。

處理加密的內容

使用客戶自控金鑰加密時，由於額外的加密/解密工作，您會察覺到編製索引和查詢的延遲問題。 Azure AI 搜尋服務不會記錄加密活動，但您可以透過金鑰保存庫記錄來監視金鑰存取。建議您啟用記錄作為金鑰保存庫組態的一部分。

金鑰輪換預期會隨著時間而發生。每當您輪換金鑰時，請務必遵循下列順序：

確定索引或同義字對應所使用的金鑰。
在金鑰保存庫中建立新的金鑰，但讓原始金鑰保持可用的狀態。
對索引或同義字對應更新 encryptionKey 屬性，以使用新的值。只有最初使用此屬性所建立的物件可以進行更新以使用不同的值。
停用或刪除金鑰保存庫中之前的金鑰。監視金鑰存取，以確認是否正在使用新的金鑰。

基於效能的理由，搜尋服務最多會快取金鑰數小時。如果您停用或刪除金鑰而不提供新的金鑰，查詢還是會暫時繼續運作，直到快取時間到期為止。不過，一旦搜尋服務無法再對內容進行解密，您就會收到下列訊息："Access forbidden. The query key used might have been revoked - please retry."

下一步

如果您不熟悉 Azure 安全性架構，請檢閱 Azure 安全性文件，特別是下面這篇文章：

資料靜態加密

共用方式為