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

通过 Azure 托管 HSM 密钥保管库为 Azure Cosmos DB 帐户配置客户管理的密钥

2025-04-21

适用对象： NoSQL MongoDB Cassandra Gremlin 表

请参阅链接：使用 Azure Key Vault 配置客户管理的密钥

注意

客户管理的密钥目前仅适用于新的 Azure Cosmos DB 帐户。应在创建帐户期间配置这些密钥。

为 Azure 订阅注册 Azure Cosmos DB 资源提供程序

登录到 Azure 门户，转到 Azure 订阅，并在 “设置” 选项卡下选择 “资源提供程序” ：
搜索“Microsoft DocumentDB”资源提供程序。验证资源提供程序是否已标记为“已注册”。如果不是，请选择资源提供程序，并选择“注册”：

配置 Azure 托管 HSM 密钥保管库

将客户管理的密钥与 Azure Cosmos DB 结合使用时，需要在计划用于托管加密密钥的 Azure Key Vault 实例上设置两个属性： “软删除” 和 “清除保护” 。

由于默认启用软删除，因此必须仅启用清除保护。创建托管 HSM 时，请使用以下 CLI 命令：

objectId = az ad signed-in-user show --query id -o tsv
az keyvault create --hsm-name $hsmName --resource-group $rgName --___location $___location --enable-purge-protection true --administrators $objectId --retention-days 7

如果使用的是现有 Azure 托管 HSM 密钥保管库实例，可使用以下命令查看“属性”部分，验证是否已启用这些属性：

az keyvault show $hsmName $rgName

如果未启用清除保护，可使用以下命令：

az keyvault update-hsm --enable-purge-protection true --hsm-name $hsmName --resource-group $rgName

若要详细了解可用于托管 HSM 的 CLI 命令，请参阅下面的 Azure Key Vault

创建加密密钥并分配相应角色

激活托管 HSM 后，需要创建将用于 CMK 帐户的密钥。为此，将“托管 HSM 加密用户”角色分配给管理员。若要详细了解 RBAC（基于角色的访问控制）如何与托管 HSM 配合使用，请参阅以下文章：托管 HSM 本地 RBAC 内置角色 - Azure Key Vault | Microsoft Learn 和 Azure 托管 HSM 访问控制 | Microsoft Learn

objectId = az ad signed-in-user show --query id -o tsv
$keyName = "Name of your key"
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto User" --assignee $objectId --scope /keys
az keyvault key create --hsm-name $hsmName --name $keyName --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

创建密钥后，需要将相应角色分配给 Cosmos DB 主体 ID 或 Azure 托管标识，以用于预配帐户。使用“托管 HSM 加密服务加密用户”角色的原因是该角色仅拥有处理 CMK 帐户所需的三个权限，即：获取、包装和解包。这些权限的范围也被限定为仅对 Azure 托管 HSM 上存储的密钥有用。

不使用 Azure 托管标识：

$cosmosPrincipal = az ad sp show --id a232010e-820c-4083-83bb-3ace5fc29d0b --query id -o tsv
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys
$keyURI = "https://{0}.managedhsm.azure.net/keys/{1}" -f $hsmName, $keyName
az cosmosdb create -n $cosmosName -g $rgName --key-uri $keyURI

使用 Azure 托管标识：

$identityResourceID = az identity show -g $rgName -n $identityName --query id -o tsv
$identityPrincipal = az identity show -g $rgName -n $identityName --query principalId -o tsv
$defaultIdentity = "UserAssignedIdentity={0}" -f $identityResourceID
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys
$keyURI = "https://{0}.managedhsm.azure.net/keys/{1}" -f $hsmName, $keyName
az cosmosdb create -n $cosmosName -g $rgName --key-uri $keyURI --assign-identity $identityResourceID --default-identity $defaultIdentity

这会使用 Azure 托管 HSM 密钥保管库中存储的密钥来预配 Cosmos DB CMK 帐户。

切换到系统分配的托管标识。

Cosmos DB 支持将系统分配的托管标识用于 CMK Cosmos DB 帐户。若要详细了解系统分配的托管标识 CMK，请参阅：为 Azure Cosmos DB 帐户配置客户管理的密钥

执行以下命令，从默认标识切换到系统分配的托管标识：

az cosmosdb identity assign -n $cosmosName -g $rgName
$principalMSIId = az cosmosdb identity show -n $cosmosName -g $rgName --query principalId -o tsv
az keyvault role assignment create --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $principalMSIId --scope /keys
az cosmosdb update --resource-group $rgName --name $cosmosName --default-identity "SystemAssignedIdentity"

可选说明：可以删除 Cosmos DB 主体 ID 或 Azure 托管标识的原始角色分配。

az keyvault role assignment delete --hsm-name $hsmName --role "Managed HSM Crypto Service Encryption User" --assignee $cosmosPrincipal --scope /keys

后续步骤

详细了解 Azure Cosmos DB 中的数据加密。

通过