通过

Azure Cosmos DB 中的资源令牌

  • 项目

适用对象： NoSQL MongoDB Cassandra Gremlin 表

资源令牌是可以提供对容器、分区键或项的特定访问权限的凭据。 可以微调它们，以按用户授予特定权限，并直接使用适用于 Azure Cosmos DB 的 REST API。 资源令牌提供使用为读取/写入或只读访问配置的主密钥或辅助密钥进行身份验证的替代方法。

重要

Microsoft 建议使用最安全的可用身份验证流。 本过程中介绍的身份验证流程需要非常高的信任度，并携带其他流中不存在的风险。 请仅在无法使用其他更安全的流（例如托管标识）时才使用此流。

对于 Azure Cosmos DB，Microsoft Entra 身份验证是可用的最安全的身份验证机制。 查看 API 的相应安全指南：

本机 Azure Cosmos DB 客户端库直接处理资源令牌生成和管理。 但是，如果使用 REST，则必须自行构造请求/身份验证标头。 有关为 REST 创建身份验证标头的详细信息，请参阅 对 REST 中的 Azure Cosmos DB 资源的访问控制。

先决条件

  • 现有的 Azure Cosmos DB 帐户
  • .NET 8 SDK （或更高版本）

创建用户和权限

首先，必须使用 Azure Cosmos DB for NoSQL SDK 创建用户。 然后，可以为用户创建权限。

注意

许多 API（如 Cassandra 和 Gremlin）不会通过其本机 SDK 公开接口来创建资源令牌。 若要使用资源令牌，必须使用 NoSQL SDK 与帐户终结点进行交互，而不考虑选择的 API。

  1. 从现有帐户获取 NoSQL 终结点和帐户的读写密钥之一。

  2. 将包的 Microsoft.Azure.Cosmos 3.x 版本添加到 .NET 项目。

    dotnet add package Microsoft.Azure.Cosmos --version 3.*

  3. 为 Microsoft.Azure.Cosmos 命名空间添加一个 using 块。

    using Microsoft.Azure.Cosmos;

  4. 创建新的客户端，指定帐户 NoSQL 终结点和读写密钥。

    CosmosClient client = new(
    accountEndpoint: "<account-nosql-endpoint>",
    authKeyOrResourceToken: "<account-read-write-key>"
);

    注意

    必须为通常采用以下格式的帐户使用 NoSQL 终结点： https://<account-name>.documents.azure.com:443/

  5. 获取数据库和容器对象。

    Database database = client.GetDatabase("<database-name>");
Container container = database.GetContainer("<container-name>");

  6. 在数据库中创建一个新用户，指定用户的名称。

    User user = await database.CreateUserAsync("demo-user");

  7. 为指定权限模式（Read 或 All）、唯一标识符、作用域容器和可选分区键范围的用户创建新权限。

    PermissionProperties permissionProperties = new(
    id: "read-permission",
    permissionMode: PermissionMode.All,
    container: container,
    resourcePartitionKey: new PartitionKey("partition-key-value")
);
Permission permission = await user.CreatePermissionAsync(permissionProperties);

获取资源令牌

现在，再次使用 NoSQL SDK 从帐户获取资源令牌。

PermissionResponse response = await permission.ReadAsync();
string resourceToken = response.Resource.Token;

使用资源令牌

最后，可以使用 API 的本机 SDK 来使用资源令牌。

using Microsoft.Azure.Cosmos;

CosmosClient client = new(
    accountEndpoint: "<account-nosql-endpoint>",
    authKeyOrResourceToken: "<resource-token>"
);

Container container = client.GetContainer("<database-name>", "<container-name>");

var iterator = container.GetItemQueryIterator<dynamic>("SELECT * FROM c");

while (iterator.HasMoreResults)
{
    foreach (var item in await iterator.ReadNextAsync())
    {
        Console.WriteLine(item);
    }
}