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

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

  • 项目

适用于： NoSQL MongoDB Cassandra Gremlin 表

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

注意

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

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

  1. 登录到 Azure 门户，转到 Azure 订阅，并在 “设置” 选项卡下选择 “资源提供程序” ：

    资源导航菜单中“资源提供程序”选项的屏幕截图。

  2. 搜索“Microsoft DocumentDB”资源提供程序。 确认该资源提供程序是否标记为已注册。 如果不是，请选择该资源提供程序，然后选择“注册”：

    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

后续步骤