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

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

项目
11/22/2023

适用范围： NoSQL

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

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

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

主/辅助密钥

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

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

Screenshot of the View account key for Azure Cosmos DB.

密钥轮换和重新生成

注意

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

若要监视帐户中的密钥更新和密钥重新生成，请参阅监视 Azure Cosmos DB 帐户中的密钥更新和密钥重新生成。

密钥轮换和重新生成的过程非常简单。首先，请确保应用程序始终使用主密钥或辅助密钥来访问你的 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 帐户配置基于角色的访问控制。

有关为 Azure Cosmos DB for MongoDB 配置 RBAC 的信息和示例代码，请参阅为 Azure Cosmos DB for MongoDB 配置基于角色的访问控制。

资源令牌

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

提供对特定容器、分区键、文档和附件的访问权限。
向用户授予对特定资源的权限时创建。
当权限资源由 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 门户执行以下步骤。

打开 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 用户管理示例。
有关为 Azure Cosmos DB for MongoDB 配置 RBAC 的信息和示例代码，请参阅为 Azure Cosmos DB for MongoDB 配置基于角色的访问控制。