為Azure DocumentDB叢集配置客戶管理密鑰（CMK）用於靜止時的資料加密

在本文中，您將學習如何在 Azure DocumentDB 中設定 客戶管理金鑰（CMK） 以進行資料加密。 本指南中的步驟包括配置新的 Azure DocumentDB 叢集、複本叢集或還原叢集。 CMK 設定使用儲存在 Azure Key Vault 中的客戶自控金鑰，以及使用者指派的受控識別。

先決條件

• Azure 訂用帳戶

  • 如果您沒有 Azure 訂用帳戶，請建立 免費帳戶

• 使用 Azure Cloud Shell 中的 Bash 環境。 如需詳細資訊，請參閱開始使用 Azure Cloud Shell。

  

• 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 若您在 Windows 或 macOS 上執行，請考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱 如何在 Docker 容器中執行 Azure CLI。

  • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱 使用 Azure CLI 向 Azure 進行驗證。

  • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能的詳細資訊，請參閱 使用和管理 Azure CLI 的擴充功能。

  • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

準備使用者指派的受控識別與 Azure Key Vault

要在 MonogDB 叢集的 Azure DocumentDB 上設定客戶管理的金鑰加密，你需要一個由使用者指派的管理身份、一個 Azure Key Vault 實例，以及正確設定的權限。

這很重要

使用者指派的管理身份和用來設定 CMK 的 Azure Key Vault 實例應該位於 Azure DocumentDB 叢集所託管的同一 Azure 區域，且都屬於同一個 Microsoft 租戶。

使用 Azure 入口網站：

1. 如果尚未建立，請在叢集所在區域建立一個使用者指派的受控識別。

2. 如果尚未建立金鑰存放區，請在叢集所在區域建立一個 Azure Key Vault。 請確定您符合需求 (部分機器翻譯)。 此外，在設定金鑰存放區之前，以及在建立金鑰並將所需權限指派給使用者指派的受控識別之前，也請遵循建議。

3. 在金鑰存放區中建立一個金鑰。

4. 依照需求中所述，授予使用者指派的受控識別對 Azure Key Vault 執行個體的權限。

在叢集佈建期間，使用客戶自控金鑰設定資料加密

Portal

1. 在新建 Azure DocumentDB 叢集時，會在 加密 標籤籤中設定服務管理或客戶管理的叢集資料加密金鑰。選擇由 客戶管理的金鑰 進行 資料加密。

   

2. 在 [使用者指派的受控識別] 區段中，選取 [變更身分識別]。

   

3. 在使用者指派的受控識別清單中，選取您希望叢集使用哪一個受控識別來存取 Azure Key Vault 中所儲存的資料加密金鑰。

   

4. 選取 ，然後新增。

   

5. 在 [金鑰選取方法] 中，選擇[選取金鑰]。

6. 在 [金鑰] 區段中，選取 [變更金鑰]。

   

7. 在 [選取金鑰] 窗格中，於 [金鑰保存庫] 選取 Azure Key Vault，於 [金鑰] 選取加密金鑰，然後選取 [選取] 確認您的選擇。

   

   這很重要

   選擇的 Azure Key Vault 實例應該位於 Azure DocumentDB 叢集將要託管的同一 Azure 區域。

8. 在 [加密] 索引標籤確認選取的使用者指派的受控識別與加密金鑰，然後選取 [檢閱 + 建立] 建立叢集。

   

REST API

您可以在佈建新叢集時，透過 az rest 命令啟用使用者指派加密金鑰的資料加密。

1. 建立一個 JSON 檔案，內容如下。 將以 $ 符號開頭的預留位置替換為實際值，並儲存檔案。

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "administrator": {
             "userName": "$adminName",
             "password": "$complexPassword"
           },
           "serverVersion": "8.0",
           "storage": {
             "sizeGb": 32
           },
           "compute": {
             "tier": "M40"
           },
           "sharding": {
             "shardCount": 1
           },
           "highAvailability": {
             "targetMode": "ZoneRedundantPreferred"
           },
         "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   備註

   keyEncryptionKeyUrl 應包含金鑰名稱，但不應包含特定金鑰版本。

2. 執行以下 Azure CLI 命令，呼叫 REST API 以建立 Azure DocumentDB 叢集。 將變數區段及 az rest 命令列中 --body 參數的檔案名稱中的預留位置替換為實際值。

   # Define your variables
   $randomIdentifier = (New-Guid).ToString().Substring(0,8)
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="DocumentDB"
   $mongoClustersName="msdocscr$randomIdentifier"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

更新已啟用 CMK 之叢集上的資料加密設定

若現有叢集部署了使用客戶自控金鑰的資料加密，您可以變更幾個設定。 您可以變更儲存加密金鑰的金鑰保存庫，以及用作客戶自控金鑰的加密金鑰。 您也可以變更服務用來存取金鑰存放區中加密金鑰的使用者指派受控識別。

Portal

1. 在叢集側邊欄的 [設定] 底下，選取 [資料加密]。

2. 在 [使用者指派的受控識別] 區段中，選取 [變更身分識別]。

   

3. 在使用者指派的受控識別清單中，選取您希望叢集使用哪一個受控識別來存取 Azure Key Vault 中所儲存的資料加密金鑰。

   

4. 選取 ，然後新增。

5. 在 [金鑰選取方法] 中，選擇[選取金鑰]。

6. 在 [金鑰] 中，選擇 [變更金鑰]。

   

7. 在 [選取金鑰] 窗格中，於 [金鑰保存庫] 選取 Azure Key Vault，於 [金鑰] 選取加密金鑰，然後選取 [選取] 確認您的選擇。

   

   這很重要

   選取的 Azure Key Vault 實例應該位於與 Azure DocumentDB 叢集所托管的同一 Azure 區域。

8. 在 [資料加密] 頁面確認選取的使用者指派受控識別與加密金鑰，然後選取 [儲存] 以確認您的選擇並建立複本叢集。

   

REST API

您可以透過 REST API 呼叫，在現有叢集上變更資料加密的使用者指派受控識別與加密金鑰。

1. 建立一個 JSON 檔案，內容如下。 將以 $ 符號開頭的預留位置替換為實際值，並儲存檔案。

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
           "encryption": {
             "customerManagedKeyEncryption": {
               "keyEncryptionKeyIdentity": {
                 "identityType": "UserAssignedIdentity",
                 "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
               },
               "keyEncryptionKeyUrl": "$encryptionKeyUrl"
             }
           }
         }
   }
   

   備註

   keyEncryptionKeyUrl 應包含金鑰名稱，但不應包含特定金鑰版本。

2. 執行以下 Azure CLI 命令，呼叫 REST API 以建立 Azure DocumentDB 叢集。 將變數區段及 az rest 命令列中 --body 參數的檔案名稱中的預留位置替換為實際值。

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

無論您是只想變更用來存取金鑰的使用者指派受控識別，還是只想變更用於資料加密的金鑰，或是想要同時變更兩者，都必須提供 JSON 檔案中列出的所有參數。

如果指定的金鑰或使用者指派受控識別不存在，您將會收到錯誤訊息。

若作為參數傳遞的身份存在且有效，會自動加入與 Azure DocumentDB 叢集相關的使用者指派管理身份清單。 即使命令稍後失敗併發生其他錯誤，也是如此。

變更現有叢集的資料加密模式

只有在建立叢集時，才能決定使用服務管理金鑰或客戶自控金鑰 (CMK) 進行資料加密。 一旦您做出決定並建立叢集之後，就無法在這兩個選項之間切換。 若要建立帶有不同加密選項的 Azure DocumentDB 叢集副本，您可以選擇 建立複本叢集 ，或在複本叢集或還原叢集時 執行叢集還原 並選擇新的加密模式。

在建立複本叢集時啟用或停用客戶自控金鑰 (CMK) 資料加密

請依照下列步驟建立具有 CMK 或 SMK 資料加密的複本叢集，以啟用或停用複本叢集上的 CMK。

Portal

1. 在叢集提要字段的 [設定]下，選取 [全域散發]。

2. 選取 [新增讀取複本]。

   

3. 在 [讀取複本] 名稱欄位提供複本叢集名稱。

4. 選取 [讀取複本區域] 中的區域。 複本叢集裝載於選取的 Azure 區域中。

   備註

   複本叢集總是會建立在與其主要 (讀取-寫入) 叢集相同的 Azure 訂閱和資源群組中。

   

5. 在 [資料加密] 區段，選取 [客戶自控金鑰] 以啟用 CMK，或選取 [服務管理金鑰] 以停用複本叢集上的 CMK。

   

6. 在 [使用者指派的受控識別] 區段中，選取 [變更身分識別]。

   

7. 在使用者指派的受控識別清單中，選取您希望叢集使用哪一個受控識別來存取 Azure Key Vault 中所儲存的資料加密金鑰。

   

8. 選取 ，然後新增。

9. 在 [金鑰選取方法] 中，選擇[選取金鑰]。

10. 在 [金鑰] 中，選擇 [變更金鑰]。

    

11. 在 [選取金鑰] 窗格中，於 [金鑰保存庫] 選取 Azure Key Vault，於 [金鑰] 選取加密金鑰，然後選取 [選取] 確認您的選擇。

    

12. 在 [全域發佈] 頁面確認選取的使用者指派受控識別與加密金鑰，然後選取 [儲存] 以確認您的選擇並建立複本叢集。

    

REST API

若要在相同區域中建立啟用了 CMK 的複本叢集，請遵循以下步驟。

1. 建立一個 JSON 檔案，內容如下。 將以 $ 符號開頭的預留位置替換為實際值，並儲存檔案。

   {
           "identity": {
               "type": "UserAssigned",
               "userAssignedIdentities": {
                 "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
               }
             },
         "location": "$targetRegionName",
             "properties": {
             	"createMode": "GeoReplica",
                   "replicaParameters": {
                     "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$sourceClusterName",
                     "sourceLocation": "sourceRegionName"
                   },
                   "encryption": {
                     "customerManagedKeyEncryption": {
                       "keyEncryptionKeyIdentity": {
                         "identityType": "UserAssignedIdentity",
                         "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                       },
                       "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                     }
                   }
             }
       }
   

   備註

   keyEncryptionKeyUrl 應包含金鑰名稱，但不應包含特定金鑰版本。

2. 執行以下 Azure CLI 命令，呼叫 REST API 以建立 Azure DocumentDB 叢集。 將變數區段及 az rest 命令列中 --body 參數的檔案名稱中的預留位置替換為實際值。

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

在叢集還原期間啟用或停用客戶自控金鑰 (CMK) 資料加密

還原流程會在與原始叢集相同的 Azure 區域、訂閱和資源群組中建立具有相同設定的新叢集。 依照下列步驟建立啟用 CMK 或 SMK 的還原叢集。

Portal

1. 選擇一個現有的 Azure DocumentDB 叢集。

2. 在叢集提要欄位的 [設定] 下，選取 [還原時間點]。

3. 在日期和時間欄位中選取日期並提供時間 (以 UTC 時區為準)。

   

4. 在 [還原目標叢集名稱] 欄位中輸入叢集名稱。

   

5. 在 [管理員使用者名稱] 欄位中為還原的叢集輸入叢集管理員名稱。

6. 在 [密碼] 及[確認密碼] 欄位中輸入管理員角色的密碼。

   

7. 在 [資料加密] 區段，選取 [客戶自控金鑰] 以啟用 CMK。 如果您需要在還原的叢集上停用 CMK，請選取 [服務管理金鑰]。

   

8. 在 [使用者指派的受控識別] 區段中，選取 [變更身分識別]。

   

9. 在使用者指派的受控識別清單中，選取您希望叢集使用哪一個受控識別來存取 Azure Key Vault 中所儲存的資料加密金鑰。

   

10. 選取 ，然後新增。

11. 在 [金鑰選取方法] 中，選擇[選取金鑰]。

12. 在 [金鑰] 中，選擇 [變更金鑰]。

    

13. 在 [選取金鑰] 窗格中，於 [金鑰保存庫] 選取 Azure Key Vault，於 [金鑰] 選取加密金鑰，然後選取 [選取] 確認您的選擇。

    

14. 選取 [提交] 以啟動叢集還原。

REST API

若要還原啟用了 CMK 的叢集，請遵循以下步驟。

1. 建立一個 JSON 檔案，內容如下。 將以 $ 符號開頭的預留位置替換為實際值，並儲存檔案。

   {
       "identity": {
           "type": "UserAssigned",
           "userAssignedIdentities": {
             "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName": {}
           }
         },
     "location": "$regionName",
         "properties": {
               "administrator": {
                 "userName": "$adminName"
               },
         	"createMode": "PointInTimeRestore",
               "restoreParameters": {
                 "pointInTimeUTC": "yyyy-mm-ddThh:mm:ssZ",
                 "sourceResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/$restoredClusterName"
               },
               "encryption": {
                 "customerManagedKeyEncryption": {
                   "keyEncryptionKeyIdentity": {
                     "identityType": "UserAssignedIdentity",
                     "userAssignedIdentityResourceId": "/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$userAssignedIdentityName"
                   },
                   "keyEncryptionKeyUrl": "$encryptionKeyUrl"
                 }
               }
         }
   }
   

   備註

   keyEncryptionKeyUrl 應包含金鑰名稱，但不應包含特定金鑰版本。

2. 執行以下 Azure CLI 命令，呼叫 REST API 以建立 Azure DocumentDB 叢集。 將變數區段及 az rest 命令列中 --body 參數的檔案名稱中的預留位置替換為實際值。

   # Define your variables
   $subscriptionId="00000000-0000-0000-0000-000000000000"
   $resourceGroup="resourceGroupName"
   $mongoClustersName="clusterName"
   
   # Execute the az rest command to make REST API call
   az rest --method "PUT" --url https://management.azure.com/subscriptions/$subscriptionId/resourceGroups/$resourceGroup/providers/Microsoft.DocumentDB/mongoClusters/${mongoClustersName}?api-version=2025-09-01 --body  @jsonFileFromThePreviousStep.json
   

在建立還原叢集後，檢閱還原後工作清單。

相關內容

• 了解Azure DocumentDB中資料加密的靜態狀態
• 疑難排解 CMK 設定
• 查看 CMK 限制
• Migrate data to Azure DocumentDB