保护对 Azure Cosmos DB 中数据的访问

项目
05/08/2024

适用范围： NoSQL

本文概述了 Azure Cosmos DB 中的数据访问控制。

Azure Cosmos DB 提供了三种方法来控制对数据的访问。

访问控制类型	特征
主/辅助密钥	允许任何管理或数据操作的共享机密。它包括读写变量和只读变量。
基于角色的访问控制 (RBAC)	使用 Microsoft Entra 标识进行身份验证的细粒度、基于角色的权限模型。
资源令牌	基于本机 Azure Cosmos DB 用户和权限的细化权限模型。

主/辅助密钥

主/辅助密钥提供对数据库帐户的所有管理资源的访问权限。每个帐户包括两个密钥：主密钥和辅助密钥。使用两个密钥的目的是为了能够重新生成或轮换密钥，从而可以持续访问帐户和数据。若要了解有关主密钥/辅助密钥的详细信息，请参阅 Azure Cosmos DB 中的数据库安全性概述。

若要查看帐户密钥，请在左侧菜单中选择“密钥”。然后，选择每个密钥右侧的“视图”图标。选择“复制”按钮以复制所选密钥。之后，可以通过为每个密钥选择相同的图标来隐藏它们，这样做会将图标更新为“隐藏”按钮。

Azure Cosmos DB 的“查看帐户密钥”的屏幕截图。

密钥轮换和重新生成

注意

以下部分介绍为 API for NoSQL 轮换和重新生成密钥的步骤。如果使用不同的 API，请参阅 API for MongoDB、API for Cassandra、API for Gremlin 或 API for Table 部分。

密钥轮换和重新生成的过程非常简单。首先，请确保应用程序始终使用主密钥或辅助密钥来访问你的 Azure Cosmos DB 帐户。然后，按照下一部分中的步骤操作。

如果你的应用程序当前正在使用主密钥
如果你的应用程序当前正在使用辅助密钥

转到 Microsoft Azure 门户中的 Azure Cosmos DB 帐户。
从左侧菜单中选择“密钥”，然后从辅助密钥右侧的省略号中选择“重新生成辅助密钥”。
验证新的辅助密钥是否适用于你的 Azure Cosmos DB 帐户。密钥重新生成可能需要一分钟，也可能长达数小时，具体取决于 Azure Cosmos DB 帐户的大小。
在应用程序中将主密钥替换为辅助密钥。
返回到 Azure 门户，并触发主密钥的重新生成。

有关如何使用主密钥的代码示例

以下代码示例演示如何使用 Azure Cosmos DB 帐户终结点和主密钥来实例化 CosmosClient：

// Read the Azure Cosmos DB endpointUrl and authorization keys from config.
// These values are available from the Azure portal on the Azure Cosmos DB account blade under "Keys".
// Keep these values in a safe and secure location. Together they provide Administrative access to your Azure Cosmos DB account.

private static readonly string endpointUrl = ConfigurationManager.AppSettings["EndPointUrl"];
private static readonly string authorizationKey = ConfigurationManager.AppSettings["AuthorizationKey"];

CosmosClient client = new CosmosClient(endpointUrl, authorizationKey);

基于角色的访问控制

Azure Cosmos DB 公开一个内置的 RBAC 系统，使你可以：

使用 Microsoft Entra 标识对数据请求进行身份验证。
使用细粒度的、基于角色的权限模型来授权数据请求。

Azure Cosmos DB RBAC 是在以下情况下的理想访问控制方法：

你不希望使用共享机密（如主密钥），但希望依赖于基于令牌的身份验证机制。
你希望使用 Microsoft Entra 标识对请求进行身份验证。
你需要细化权限模型来严格限制标识允许执行的数据库操作。
你希望将访问控制策略具体化为可分配给多个标识的“角色”。

若要详细了解 Azure Cosmos DB RBAC，请参阅为 Azure Cosmos DB 帐户配置基于角色的访问控制。

资源令牌

资源令牌提供对数据库中应用程序资源的访问权限。资源令牌：

提供对特定容器、分区键、文档和附件的访问权限。
向用户授予对特定资源的权限时创建。
当权限资源由 POST、GET 或 PUT 调用执行时重新创建。
使用专门针对用户、资源和权限构造的哈希资源令牌。
生存期受到可自定义的有效期的约束。默认的有效期限为一小时。但是，可以显式指定令牌生存期，最长为 24 小时。
可以安全替代主密钥。
使客户端能够根据授予的权限读取、写入和删除 Azure Cosmos DB 帐户中的资源。

如果想要为不能通过主密钥得到信任的客户端提供对 Azure Cosmos DB 帐户中资源的访问权限，可以使用资源令牌（通过创建 Azure Cosmos DB 用户和权限来使用）。

Azure Cosmos DB 资源令牌提供一种安全的替代方案，使客户端能够根据授予的权限读取、写入和删除 Azure Cosmos DB 帐户中的资源，而无需主密钥或只读密钥。

以下是典型的设计模式，通过它可以请求、生成资源令牌并将其提供给客户端：

设置中间层服务，以用于移动应用程序共享用户照片。
中间层服务拥有 Azure Cosmos DB 帐户的主密钥。
照片应用安装在用户移动设备上。
登录时，照片应用使用中间层服务建立用户的标识。这种标识建立机制完全由应用程序决定。
建立标识后，中间层服务会根据标识请求权限。
中间层服务将资源令牌发送回手机应用。
手机应用可以继续使用该资源令牌，以该资源令牌定义的权限，按照该资源令牌允许的间隔直接访问 Azure Cosmos DB 资源。
资源令牌到期后，后续请求收到 401 未经授权的异常。此时，手机应用会重新建立标识，并请求新的资源令牌。

资源令牌生成和管理由本机 Azure Cosmos DB 客户端库处理。但是，如果使用 REST，则必须构造请求/身份验证标头。有关为 REST 创建身份验证标头的详细信息，请参阅 Azure Cosmos DB 资源的访问控制或我们的 .NET SDK 或 Node.js SDK 的源代码。

有关用于生成或代理资源令牌的中间层服务的示例，请参阅 ResourceTokenBroker 应用。

Users

Azure Cosmos DB 用户与 Azure Cosmos DB 数据库相关联。每个数据库可以包含零个或多个 Azure Cosmos DB 用户。以下代码示例展示了如何使用 Azure Cosmos DB .NET SDK v3 创建 Azure Cosmos DB 用户。

// Create a user.
Database database = client.GetDatabase("SalesDatabase");
User user = await database.CreateUserAsync("User 1");

注意

每个 Azure Cosmos DB 用户都有一个 ReadAsync() 方法，可用于检索与用户关联的权限列表。

Permissions

权限资源与用户相关联并分配给特定资源。每个用户可以包含零个或多个权限。用户在尝试访问某个特定容器或访问特定分区键中的数据时需要一个安全令牌，权限资源提供对该安全令牌的访问权限。权限资源提供两种可用的访问级别：

全部：用户对资源拥有完全权限。
读取：用户只能读取资源的内容，但不能对资源执行写入、更新或删除操作。

注意

若要运行存储过程，用户必须对要在其中运行存储过程的容器拥有“全部”权限。

如果对数据平面请求启用诊断日志，则会记录与该权限相对应的以下两个属性：

resourceTokenPermissionId：此属性指示指定的资源令牌权限 ID。
resourceTokenPermissionMode：此属性指示创建资源令牌时设置的权限模式。权限模式可以具有“全部”或“读取”等值。

有关创建权限的代码示例

以下代码示例演示如何创建权限资源、读取权限资源的资源令牌，并将权限与刚刚创建的用户关联。

// Create a permission on a container and specific partition key value
Container container = client.GetContainer("SalesDatabase", "OrdersContainer");
await user.CreatePermissionAsync(
    new PermissionProperties(
        id: "permissionUser1Orders", 
        permissionMode: PermissionMode.All, 
        container: container,
        resourcePartitionKey: new PartitionKey("012345")));

有关读取用户权限的代码示例

以下代码片段演示如何检索与创建的用户关联的权限，并实例化用户的新 CosmosClient，范围限定为单个分区键。

// Read a permission, create user client session.
Permission permission = await user.GetPermission("permissionUser1Orders").ReadAsync();

CosmosClient client = new CosmosClient(accountEndpoint: "MyEndpoint", authKeyOrResourceToken: permission.Resource.Token);

RBAC 和资源令牌之间的差异

使用者	RBAC	资源令牌
身份验证	使用 Microsoft Entra ID。	基于本机 Azure Cosmos DB 用户。将资源令牌与 Microsoft Entra ID 集成需要额外桥接 Microsoft Entra 标识和 Azure Cosmos DB 用户。
授权	基于角色：角色定义映射允许的操作，并且可以分配给多个标识。	基于权限：对于每个 Azure Cosmos DB 用户，需要分配数据访问权限。
令牌范围	Microsoft Entra 令牌包含请求者的标识。此标识将与所有分配的角色定义匹配以执行授权。	资源令牌带有向特定 Azure Cosmos DB 资源上的特定 Azure Cosmos DB 用户授权的权限。不同资源的授权请求可能需要不同的令牌。
令牌刷新	Azure Cosmos DB SDK 在过期时会自动刷新 Microsoft Entra 令牌。	不支持资源令牌刷新。资源令牌过期时，需要发出一个新令牌。

添加用户和分配角色

若要将 Azure Cosmos DB 帐户读者访问权限添加到用户帐户，请让订阅所有者在 Azure 门户执行以下步骤。

打开 Microsoft Azure 门户并选择 Azure Cosmos DB 帐户。
选择“访问控制 (IAM)”。
选择“添加”>“添加角色分配”，打开“添加角色分配”页面。
分配以下角色。有关详细步骤，请参阅使用 Azure 门户分配 Azure 角色。

设置值

角色 Cosmos DB 帐户读者。

将访问权限分配到用户、组或服务主体。

成员目录中要向其授予访问权限的用户、组或应用程序。

设置	值
角色	Cosmos DB 帐户读者。
将访问权限分配到	用户、组或服务主体。
成员	目录中要向其授予访问权限的用户、组或应用程序。

实体现在便可以读取 Azure Cosmos DB 资源。

删除或导出用户数据

借助 Azure Cosmos DB 数据库服务，可搜索、选择、修改和删除数据库或容器中的任何数据。你有责任使用提供的 API 并定义查找和擦除任何个人数据所需的逻辑（如果需要）。

每个多模型 API（SQL、MongoDB、Gremlin、Cassandra 或表）都包含不同的语言 SDK，这些 SDK 提供了各种用于搜索和基于自定义谓词删除数据的方法。还可启用生存时间 (TTL) 功能在指定时间段后自动删除数据，不会产生任何其他费用。

注意

有关查看或删除个人数据的信息，请参阅 GDPR 的 Azure 数据使用者请求。有关 GDPR 的详细信息，请参阅 Microsoft 信任中心的 GDPR 部分和服务信任门户的 GDPR 部分。

后续步骤

若要详细了解 Azure Cosmos DB 数据库安全性，请参阅 Azure Cosmos DB 数据库安全性。
若要了解如何构造 Azure Cosmos DB 授权令牌，请参阅 Azure Cosmos DB 资源的访问控制。
有关具有用户和权限的用户管理示例，请参阅 .NET SDK v3 用户管理示例。

通过