你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 Azure Cosmos DB for MongoDB vCore 群集配置静止数据加密的客户托管密钥（CMK）

2025-10-13
适用于: ✅ MongoDB (vCore)

本文介绍如何在 Azure Cosmos DB for MongoDB vCore 中为静态数据加密配置客户管理的密钥 (CMK)。本指南中的步骤配置新的 Azure Cosmos DB for MongoDB vCore 群集、副本群集或还原的群集。 CMK 设置使用存储在 Azure Key Vault 中的客户管理的密钥，并使用用户分配的托管标识。

先决条件

Azure 订阅服务
- 如果没有 Azure 订阅，请在开始之前创建一个免费帐户。

Azure Cloud Shell 中最新版本的 Azure CLI。
- 如果想要在本地运行 CLI 引用命令，请使用 az login 该命令登录到 Azure CLI。

准备用户分配的托管标识和 Azure Key Vault

若要在 Azure Cosmos DB for MonogDB vCore 群集上配置客户管理的密钥加密，需要用户分配的托管标识、Azure Key Vault 实例和正确配置的权限。

重要

用于配置 CMK 的用户分配的托管标识和 Azure Key Vault 实例应位于托管 Azure Cosmos DB for MongoDB 群集的 Azure 区域中，都属于同一 Microsoft 租户。

使用 Azure 门户：

在群集区域中创建一个用户分配的托管标识（如果尚未创建）。
在群集区域中创建一个 Azure Key Vault（如果尚未创建密钥存储）。请确保满足要求。此外，请在配置密钥存储之前以及创建密钥并将所需的权限分配给用户分配的托管标识之前，按照建议进行操作。
在密钥存储中创建一个密钥。
根据要求中所述，向 Azure Key Vault 实例授予用户分配的托管标识权限。

在预配新的 Azure Cosmos DB for MongoDB vCore 群集期间，用于群集数据加密的服务托管密钥或客户管理的密钥在“加密”选项卡中进行配置。选择“客户管理的密钥”进行“数据加密”。
在“用户分配的托管标识”部分，选择“更改标识”。
在用户分配的托管标识列表中，选择希望群集用来访问 Azure Key Vault 中存储的数据加密密钥的那个托管标识。
选择 并添加。
在“密钥选择方法”中，选择“选择密钥”。
在“密钥”部分，选择“更改密钥”。
在“选择密钥”窗格中，选择“密钥保管库”中的 Azure Key Vault 和“密钥”中的加密密钥，然后选择“选择”以确认所做的选择。

重要

所选的 Azure Key Vault 实例应位于要托管 Azure Cosmos DB for MongoDB 群集的同一 Azure 区域中。
在“加密”选项卡上确认选定的用户分配的托管标识和加密密钥，然后选择“查看 + 创建”以创建群集。

可以使用用户分配的加密密钥启用数据加密，同时通过 az rest 命令预配新群集。

创建包含以下内容的 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 应包含密钥名称，但不应包含特定的密钥版本。

运行以下 Azure CLI 命令以进行 REST API 调用，来创建 Azure Cosmos DB for MongoDB vCore 群集。将变量部分中的占位符和 --body 命令行中 az rest 参数的文件名替换为实际值。

# Define your variables
$randomIdentifier = (New-Guid).ToString().Substring(0,8)
$subscriptionId="00000000-0000-0000-0000-000000000000"
$resourceGroup="AzureCosmosDB"
$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
REST API

在群集边栏的 “设置”下，选择“ 数据加密”。
在“用户分配的托管标识”部分，选择“更改标识”。
在用户分配的托管标识列表中，选择希望群集用来访问 Azure Key Vault 中存储的数据加密密钥的那个托管标识。
选择 并添加。
在“密钥选择方法”中，选择“选择密钥”。
在密钥中，选择 “更改密钥”。
在“选择密钥”窗格中，选择“密钥保管库”中的 Azure Key Vault 和“密钥”中的加密密钥，然后选择“选择”以确认所做的选择。

重要

所选的 Azure Key Vault 实例应位于托管 Azure Cosmos DB for MongoDB 群集的同一 Azure 区域中。
在 “数据加密 ”页上确认所选用户分配的托管标识和加密密钥，然后选择“ 保存 ”以确认选择并创建副本群集。

可以通过 REST API 调用更改用户分配的托管标识和加密密钥，以便对现有群集进行数据加密。

创建包含以下内容的 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 应包含密钥名称，但不应包含特定的密钥版本。

# 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 Cosmos DB for MongoDB vCore 群集关联的用户分配的托管标识的列表中。即使命令稍后失败并出现其他错误，也是如此。

更改现有群集上的数据加密模式

唯一可以决定是否要使用服务托管密钥或客户管理的密钥 (CMK) 进行数据加密的时间是在群集创建时。一旦做出决定并创建群集，便无法在两个选项之间切换。若要使用其他加密选项创建 Azure Cosmos DB for MongoDB vCore 群集的副本，可以创建副本群集或执行群集还原，然后在副本群集或还原群集创建期间选择新的加密模式。

在创建副本群集期间启用或禁用客户管理的密钥（CMK）数据加密

按照以下步骤创建具有 CMK 或 SMK 数据加密的副本群集，以便在副本群集上启用或禁用 CMK。

Portal
REST API

在群集边栏的 “设置”下，选择“ 全局分发”。
选择 “添加新只读副本”。
在 “读副本 名称”字段中提供集群副本名称。
在 只读副本区域中选择一个区域。副本群集托管在所选 Azure 区域中。

注释

副本群集始终在与其主（读写）群集相同的 Azure 订阅和资源组中创建。
在 “数据加密 ”部分中，选择 客户管理的密钥 以启用 CMK 或服务 管理的密钥 以在副本群集上禁用 CMK。
在“用户分配的托管标识”部分，选择“更改标识”。
在用户分配的托管标识列表中，选择希望群集用来访问 Azure Key Vault 中存储的数据加密密钥的那个托管标识。
选择 并添加。
在“密钥选择方法”中，选择“选择密钥”。
在密钥中，选择 “更改密钥”。
在“选择密钥”窗格中，选择“密钥保管库”中的 Azure Key Vault 和“密钥”中的加密密钥，然后选择“选择”以确认所做的选择。
在 “全局分发 ”页上确认选定的用户分配的托管标识和加密密钥，然后选择“ 保存” 以确认选择并创建副本群集。

若要在同一区域中创建已启用 CMK 的副本群集，请执行以下步骤。

创建包含以下内容的 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 应包含密钥名称，但不应包含特定的密钥版本。

# 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
REST API

选择现有的 Azure Cosmos DB for MongoDB vCore 群集。
在群集边栏的 “设置”下，选择 “时间点还原”。
选择一个日期，并在日期和时间字段中提供时间（以 UTC 时区为单位）。
在 “还原目标群集名称 ”字段中输入群集名称。
在 “管理员用户名 ”字段中输入已还原群集的群集管理员名称。
在 “密码 ”和 “确认密码 ”字段中输入管理员角色的密码。
在 “数据加密 ”部分中，选择 客户管理的密钥 以启用 CMK。如果需要在还原的群集上禁用 CMK，请选择 服务管理的密钥。
在“用户分配的托管标识”部分，选择“更改标识”。
在用户分配的托管标识列表中，选择希望群集用来访问 Azure Key Vault 中存储的数据加密密钥的那个托管标识。
选择 并添加。
在“密钥选择方法”中，选择“选择密钥”。
在密钥中，选择 “更改密钥”。
在“选择密钥”窗格中，选择“密钥保管库”中的 Azure Key Vault 和“密钥”中的加密密钥，然后选择“选择”以确认所做的选择。
选择 “提交 ”以启动群集还原。

若要还原已启用 CMK 的群集，请执行以下步骤。

创建包含以下内容的 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 应包含密钥名称，但不应包含特定的密钥版本。

# 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 Cosmos DB for MongoDB vCore 群集配置静止数据加密的客户托管密钥（CMK）

先决条件

准备用户分配的托管标识和 Azure Key Vault

在群集预配期间为数据加密配置客户管理的密钥

在启用了 CMK 的群集上更新数据加密设置

更改现有群集上的数据加密模式

在创建副本群集期间启用或禁用客户管理的密钥（CMK）数据加密

在群集还原期间启用或禁用客户管理的密钥 (CMK) 数据加密

相关内容

反馈

其他资源