通过 Azure Key Vault 为 Azure Cosmos DB 帐户配置客户管理的密钥

适用对象: NoSQL MongoDB Cassandra Gremlin

存储在 Azure Cosmos DB 帐户中的数据将使用 Azure 管理的密钥(服务托管密钥)自动无缝地进行加密。 或者,你可以选择使用你管理的密钥(客户管理的密钥或 CMK)添加另一层加密。

围绕客户数据的加密层示意图。

必须在 Azure Key Vault 中存储客户管理的密钥,并为启用了客户管理的密钥的每个 Azure Cosmos DB 帐户提供密钥。 此密钥用于加密存储在该帐户中的所有数据。

注意

如果要在现有 Azure Cosmos DB 帐户上启用客户管理的密钥,请参阅 使用 Azure Key Vault 为现有 Azure Cosmos DB 帐户配置客户管理的密钥

警告

在使用客户管理密钥的账户中,Cassandra API 表保留以下字段名称:

  • id
  • ttl
  • _ts
  • _etag
  • _rid
  • _self
  • _attachments
  • _epk

如果未启用客户管理的密钥,则仅保留以 __sys_ 开头的字段名称。

先决条件

注册到 Azure Cosmos DB 资源提供程序

如果 Microsoft.DocumentDB 资源提供程序尚未注册,则应首先注册此提供程序。

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

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

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

    Microsoft.DocumentDB 资源提供程序的“注册”选项的屏幕截图。

配置 Azure Key Vault 实例

重要

Azure 密钥保管库实例必须可通过公共网络访问进行访问,或者允许受信任的 Azure 服务绕过其防火墙。 只能通过专用终结点访问的实例不能用于托管客户管理的密钥。

强烈建议创建的 Azure Key Vault 资源 启用了数据复制 ,以确保在意外的区域中断期间持续可用性。

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

  1. 如果创建新的 Azure Key Vault 实例,请在创建过程中启用以下属性:

Azure 密钥保管库选项(包括软删除和清除保护)的屏幕截图。

  1. 如果使用的是现有 Azure Key Vault 实例,则可以通过查看 Azure 门户中的“属性”部分来验证是否已启用这些属性。 如果未启用上述任何属性,请参阅以下文章之一中的 “启用软删除 ”和 “启用清除保护 ”部分:

选择首选安全模型

启用清除保护和软删除后,在访问策略选项卡上,可以选择要使用的首选权限模型。 默认设置访问策略,但也支持 Azure 基于角色的访问控制。

必须提供必要的权限才能允许 Cosmos DB 使用加密密钥。 根据 Azure 密钥保管库使用的是访问策略还是基于角色的访问控制,此步骤也有所不同。

注意

请务必注意,一次只能有一个安全模型处于活动状态,因此,如果 Azure Key Vault 设置为使用访问策略,则无需配置基于角色的访问控制;同样地,如果配置了基于角色的访问控制,则不需要设置访问策略。

添加访问策略

在此变体中,使用 Azure Cosmos DB 主体创建具有相应权限的访问策略。

  1. 在 Azure 门户中,转到你打算用来托管加密密钥的 Azure Key Vault 实例。 在左侧菜单中选择“访问策略”:

资源导航菜单中“访问策略”选项的屏幕截图。

  1. 选择“+ 添加访问策略”

  2. 在“密钥权限”下拉菜单中,选择“获取”、“解包密钥”和“包装密钥”权限:

访问策略权限(包括 GET、解包密钥和包装密钥)的屏幕截图。

  1. 在“选择主体”下,选择“未选择任何项”。

  2. 搜索 Azure Cosmos DB 主体并选择它。

    提示

    这样便可在 Azure Key Vault 访问策略中注册 Azure Cosmos DB 第一方标识。 如果“Azure Cosmos DB”主体不在列表中,则可能需要重新注册“Microsoft.DocumentDB”资源提供程序。

  3. 选择底部的“选择”。

    “添加访问策略”页上的“选择主体”选项的屏幕截图。

  4. 选择“添加”以添加新的访问策略

  5. 在密钥保管库实例上选择“保存”,以保存所有更改。

添加基于角色的访问控制角色

  1. 在 Azure 门户中,转到你打算用来托管加密密钥的 Azure Key Vault 实例。 从左侧菜单中选择“访问控制 (IAM)”,然后选择“授予对此资源的访问权限”。

    资源导航菜单中“访问控制”选项的屏幕截图。

    “访问控制”页上“授予对此资源的访问权限”选项的屏幕截图。

  2. 搜索“密钥保管库管理员”角色并将其分配给自己。 此分配是通过首先从列表中搜索角色名称来完成的,然后单击 “成员” 选项卡。在选项卡上,选择单选按钮中的 “用户、组或服务主体” 选项,然后查找您的 Azure 帐户。 选择帐户后,可以分配角色。

    “访问控制”页上的角色分配的屏幕截图。

  3. 然后,必须将必要的权限分配给 Cosmos DB 的主体。 因此,与上一个角色分配一样,请转到分配页,但这次查找“密钥保管库加密服务加密用户”角色,并在成员选项卡上查找 Cosmos DB 的主体。 如需找到主体,可以搜索并选择“Azure Cosmos DB”主体。

    正在分配给权限的 Azure Cosmos DB 主体的屏幕截图。

  4. 选择 “查看 + 分配”,即可将角色分配给 Cosmos DB。

验证角色是否已正确设置

接下来,使用访问控制页确认已正确配置所有角色。

  1. 分配角色后,在“访问控制 IAM”页上选择“ 查看对此资源的访问权限 ”,以验证是否已正确设置所有内容。

    “访问控制”页上“查看资源访问权限”选项的屏幕截图。

  2. 在页面上,将范围设置为 此资源 ,并验证你是否具有 Key Vault 管理员角色,Cosmos DB 主体具有 Key Vault 加密用户角色。

在 Azure Key Vault 中生成密钥

在此处,使用 Azure 密钥保管库创建新密钥并检索唯一标识符。

  1. 在 Azure 门户中,转到你打算用来托管加密密钥的 Azure Key Vault 实例。 然后,从左侧菜单中选择“密钥”

    资源导航菜单中“密钥”选项的屏幕截图。

  2. 选择“生成/导入”,为新密钥提供名称,并选择一个 RSA 密钥大小。 建议至少使用 3072,以获得最佳安全性。 然后选择“创建”

    用于创建新密钥的对话框的屏幕截图。

    提示

    或者,可以使用 Azure CLI 使用以下方法生成密钥:

    az keyvault key create \
        --vault-name <name-of-key-vault> \
        --name <name-of-key>
    

    有关使用 Azure CLI 管理密钥保管库的详细信息,请参阅使用 Azure CLI 管理 Azure 密钥保管库

  3. 创建密钥后,选择新创建的密钥,然后选择其当前版本。

  4. 复制密钥的密钥标识符(最后一个正斜杠之后的部分除外):

    密钥标识符字段和复制操作的屏幕截图。

创建新的 Azure Cosmos DB 帐户

使用 Azure 门户或 Azure CLI 创建新的 Azure Cosmos DB 帐户。

当你从 Azure 门户创建新的 Azure Cosmos DB 帐户时,请选择“加密”步骤中“客户管理的密钥”。 在“密钥 URI”字段中,粘贴从上一步复制的 Azure Key Vault 密钥的 URI/密钥标识符:

“加密”页的屏幕截图,其中配置了自定义管理的密钥 URI。

重要

根据网络配置,可能需要允许从其他 Azure 服务访问 Azure Cosmos DB。

使用 Azure Key Vault 访问策略中的托管标识

此访问策略确保你的 Azure Cosmos DB 帐户可以访问你的加密密钥。 访问策略通过授予对特定 Microsoft Entra 标识的访问权限来实现。 支持两种类型的标识:

  • Azure Cosmos DB 的第一方标识,可用于授予对 Azure Cosmos DB 服务的访问权限。
  • Azure Cosmos DB 帐户的托管标识,可用于专门授予对帐户的访问权限。

不可用

将客户管理的密钥与连续备份配合使用

可以使用 Azure CLI 或 ARM 模板创建连续备份帐户。

目前,仅支持使用用户分配的托管标识来创建连续备份帐户。

创建帐户后,可以将标识更新为系统分配的托管标识。

或者,用户还可以先使用定期备份模式创建系统标识,然后将帐户迁移到连续备份模式。 有关详细步骤,请参阅 将 Azure Cosmos DB 帐户从定期备份模式迁移到连续备份模式

不可用

还原通过托管标识配置的连续帐户

还原请求中需要用户分配的标识,因为源帐户托管标识(用户分配的标识和系统分配的标识)无法自动传递到目标数据库帐户。

不可用

客户管理的密钥和双重加密

使用客户管理的密钥时,存储在 Azure Cosmos DB 帐户中的数据最终会加密两次:

  • 通过 Microsoft 托管密钥执行的默认加密一次。
  • 通过客户管理的密钥执行额外加密一次。

双重加密仅适用于主 Azure Cosmos DB 事务存储。 某些功能涉及将数据内部复制到不提供双重加密的第二层存储,即使使用客户管理的密钥也是如此。 这些功能包括:

密钥轮换

可以通过两种方式来轮换 Azure Cosmos DB 帐户使用的客户管理的密钥。

  • 创建当前在 Azure Key Vault 中使用的密钥的新版本:

    Azure 门户“版本”页中“新版本”选项的屏幕截图。

  • 通过更新帐户上的密钥 URI,将当前使用的密钥替换为其他密钥。 在 Azure 门户中转到你的 Azure Cosmos DB 帐户,然后在左侧菜单中选择“数据加密”:

    资源导航菜单上“数据加密”选项的屏幕截图。

    然后,将“密钥 URI”替换为要使用的新密钥,并选择“保存”:

    “密钥”页上“保存”选项的屏幕截图。

    下面介绍如何在 PowerShell 中实现相同的结果:

    # Variable for resource group name
    $RESOURCE_GROUP_NAME = "<resource-group-name>"
    
    # Variable for account name
    $ACCOUNT_NAME = "<multiple-regionally-unique-account-name>"
    
    # Variable for new key URI in the key vault
    $NEW_KEY_VAULT_KEY_URI="https://<key-vault-name>.vault.azure.cn/keys/<new-key-name>"
    
    $parameters = @{
        ResourceGroupName = $RESOURCE_GROUP_NAME 
        Name = $ACCOUNT_NAME
        ResourceType = "Microsoft.DocumentDb/databaseAccounts"
    }
    $ACCOUNT = Get-AzResource @parameters
    
    $ACCOUNT.Properties.keyVaultKeyUri = $NEW_KEY_VAULT_KEY_URI
    
    $ACCOUNT | Set-AzResource -Force
    

可以在 Azure Key Vault 审核日志不再显示该密钥或密钥版本 Azure Cosmos DB 中的活动之后禁用以前的密钥或密钥版本。 在密钥轮换 24 小时后,不应在以前的密钥或密钥版本上进行更多活动。

只要上一个密钥未禁用或删除,Azure Key Vault 中的密钥自动启动就受支持。 内部系统在验证帐户未处于吊销状态或转为启用客户管理密钥的过程中,需要一些时间才能赶上新版密钥。

错误处理

如果 Azure Cosmos DB 中客户管理的密钥有任何错误,Azure Cosmos DB 会在响应中返回错误详细信息以及 HTTP 子状态代码。 可以使用 HTTP 子状态代码来调试问题的根本原因。 若要获取支持的 HTTP 子状态代码列表,请参阅 Azure Cosmos DB 的 HTTP 状态代码

常见问题

此处包含有关在 Azure Cosmos DB 中设置客户管理的密钥的常见问题。

启用客户管理的密钥是否需要支付更多费用?

否,启用此功能不收取任何费用。

客户管理的密钥如何影响容量计划?

使用客户管理密钥时,由数据库操作消耗的请求单位 (RU)会增加,以表明执行数据加密和解密所需的额外处理。 额外的 RU 消耗可能导致预配容量的利用率略高。 使用此表作为指导:

操作类型 请求单位增加
点读取(按 ID 获取项) 每个操作 + 5%
任何写入操作 每次操作 + 6% | 每个索引属性大约 + 0.06 RU
查询、读取更改源或冲突源 每个操作 + 15%

哪些数据是通过客户管理的密钥加密的?

Azure Cosmos DB 帐户中存储的所有数据都是通过客户管理的密钥加密的,以下元数据除外:

现有的 Azure Cosmos DB 帐户是否支持客户管理的密钥?

是的。 若要了解详细信息,请参阅 使用 Azure Key Vault 为现有 Azure Cosmos DB 帐户配置客户管理的密钥

能否将客户管理的密钥与 Azure Cosmos DB 分析存储结合使用?

可以,Azure Synapse Link 仅支持使用 Azure Cosmos DB 帐户的托管标识配置客户管理的密钥。 在帐户上启用 Azure Synapse Link 之前,必须在 Azure Key Vault 访问策略中使用 Azure Cosmos DB 帐户的托管标识。 有关如何启用托管标识并在访问策略中使用它的操作指南,请参阅使用托管标识从 Azure Cosmos DB 访问 Azure Key Vault

是否有计划支持比帐户级别密钥更精细的粒度?

目前没有,但正在考虑容器级别的密钥。

如何判断是否在 Azure Cosmos DB 帐户上启用了客户管理的密钥?

在 Azure 门户中,转到 Azure Cosmos DB 帐户,并在左侧菜单中查看 数据加密 条目。 如果存在此项,则帐户上启用了客户管理的密钥:

资源导航菜单中“数据加密”选项的屏幕截图。

还可通过编程方式提取 Azure Cosmos DB 帐户的详细信息,并查找 keyVaultKeyUri 属性是否存在。

客户管理的密钥如何影响定期备份?

Azure Cosmos DB 将定期自动备份存储在帐户中的数据。 此操作可备份加密的数据。

若要成功还原定期备份,必须满足以下条件:

  • 需要备份时使用的加密密钥,并且 Azure Key Vault 中必须提供该密钥。 此条件要求不进行任何吊销,并且备份时使用的密钥版本仍处于启用状态。
  • 如果在访问策略中使用了系统分配的托管标识,请在恢复数据之前暂时授予对 Azure Cosmos DB 第一方标识的访问权限。 存在此要求是因为系统分配的托管标识是特定于某个帐户,并且不能在目标帐户中重复使用。 将数据完全还原到目标帐户后,可以设置所需的标识配置,并从 Key Vault 访问策略中删除第一方标识。

客户管理的密钥如何影响连续备份?

Azure Cosmos DB 提供了在帐户上配置连续备份的选项。 通过连续备份,你可以将数据还原到过去 30 天内的任何时间点。 若要在启用了客户管理的密钥的帐户上使用连续备份,必须在 Key Vault 访问策略中使用系统分配的或用户分配的托管标识。 使用连续备份的帐户当前不支持 Azure Cosmos DB 的第一方身份。

启用客户管理密钥的帐户更新用户分配身份的前提步骤。

  • 将用户分配的标识添加到 Cosmos DB 帐户,并在密钥保管库访问策略中授予权限。
  • 通过 Azure CLI 或 Azure 资源管理器(ARM)将用户分配的标识设置为默认标识。
az cosmosdb update --resource-group MyResourceGroup --name MyAccountName --default-identity UserAssignedIdentity=/subscriptions/MySubscriptionId/resourcegroups/MyResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MyUserAssignedIdentity

成功执行时间点还原需要满足以下条件:

  • 对客户管理的密钥的访问权限必须可用于账户的默认身份。 如果密钥已轮换,则必须 完全完成轮换过程,或者帐户必须同时访问旧密钥版本和新密钥版本。

  • 必须确保在源帐户上最初使用的用户分配的托管标识仍在 Key Vault 访问策略中声明。

重要

如果在删除帐户之前吊销加密密钥,则帐户的备份可能会错过在吊销前一小时写入的数据。

如何吊销加密密钥?

密钥吊销是通过禁用密钥的最新版本来完成的:

禁用的自定义密钥版本的屏幕截图。

或者,若要从 Azure Key Vault 实例撤消所有密钥,可以删除授予 Azure Cosmos DB 主体的访问策略:

访问策略的“删除”选项的屏幕截图。

吊销客户管理的密钥后可执行哪些操作?

帐户删除是在撤销加密密钥时唯一可能的操作。

将新的托管标识分配给还原的数据库帐户,以继续访问或恢复对数据库帐户的访问权限

每当将用户分配的标识分配给帐户时,用户分配的标识将绑定到指定的 Cosmos DB 帐户,ARM 会将请求转发到托管服务标识以建立此连接。 目前,在 CMK + 用户分配的标识的还原(针对连续和定期备份还原)过程中,我们会将用户标识信息从源数据库帐户转移到目标数据库帐户,

标识元数据与源数据库帐户绑定,还原工作流不会将标识重新范围到目标数据库帐户。 这会导致还原的数据库帐户处于错误状态,并在删除源帐户且标识续订时间过期后变得不可访问。

分配新托管标识的步骤:

  1. 创建新的用户分配的托管标识
  2. 授予 Key Vault 密钥对此标识的访问权限
  3. 将此新标识分配给还原的数据库帐户

后续步骤