Compartir a través de

将基于角色的数据平面访问控制与 Azure Cosmos DB for NoSQL 配合使用

适用范围: NoSQL

此图显示部署指南序列中的当前位置(“基于角色的访问控制”)。

部署指南序列图,包括以下位置,顺序为:概述、概念、准备、基于角色的访问控制、网络和参考。 当前突出显示了“基于角色的访问控制”位置。

提示

有关生成新应用的最新示例,请访问我们的新示例库

本文逐步介绍了授予标识访问权限以管理 Azure Cosmos DB for NoSQL 帐户中的数据的步骤。

重要

本文中的步骤仅介绍对单个项执行操作和运行查询的数据平面访问。 若要了解如何管理控制平面的数据库和容器,请参阅授予控制平面基于角色的访问权限

先决条件

  • 具有活动订阅的 Azure 帐户。 创建帐户
  • 一个现有的适用于 NoSQL 的 Azure Cosmos DB 帐户。
  • Microsoft Entra ID 中的一个或多个现有标识。

可以使用本地 Azure CLI。

  • 如果需要,请安装 Azure CLI 来运行 CLI 参考命令。

  • 本地 Azure CLI,请了解如何安装 Azure CLI。 如果在 Windows 或 macOS 上运行,请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息,请参阅如何在 Docker 容器中运行 Azure CLI

    • 通过使用 az login 命令登录到 Azure CLI。 若要完成身份验证过程,请遵循终端中显示的步骤。 有关其他登录选项,请参阅使用 Azure CLI 登录

    • 出现提示时,请在首次使用时安装 Azure CLI 扩展。 有关扩展详细信息,请参阅使用 Azure CLI 的扩展

    • 运行 az version 以查找安装的版本和依赖库。 若要升级到最新版本,请运行 az upgrade

准备角色定义

首先,必须准备一个角色定义,其中包含授予对 Azure Cosmos DB for NoSQL 中读取、查询和管理数据的访问权限的列表 dataActions

重要

获取现有数据平面角色定义需要以下控制平面权限:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

有关详细信息,请参阅授予控制平面基于角色的访问权限

使用 az cosmosdb sql role definition list 列出与 Azure Cosmos DB for NoSQL 帐户关联的所有角色定义。 查看输出并找到名为 Cosmos DB 内置数据参与者的角色定义。 输出包含属性中 id 角色定义的唯一标识符。 记下此值,因为本指南后面的工作分配步骤需要使用此值。

az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
[
  ...,
  {
    "assignableScopes": [
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    ],
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "msdocs-identity-example",
    "roleName": "Cosmos DB Built-in Data Contributor",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
    "typePropertiesType": "BuiltInRole"
  }
  ...
]

注意

在此示例中,id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002。 此示例使用虚构数据,而你的标识符与此示例不同。

使用 Get-AzCosmosDBSqlRoleDefinition 列出与 Azure Cosmos DB for NoSQL 帐户关联的所有角色定义。 查看输出并找到名为 Cosmos DB 内置数据参与者的角色定义。 输出包含属性中 Id 角色定义的唯一标识符。 记下此值,因为本指南后面的工作分配步骤需要使用此值。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters
Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName                   : Cosmos DB Built-in Data Contributor
Type                       : BuiltInRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions : 

注意

在此示例中,Id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002。 此示例使用虚构数据,而你的标识符与此示例不同。 但是,标识符 (00000000-0000-0000-0000-000000000002) 在帐户中的所有角色定义中都是唯一的。

将角色分配给标识

现在,将新定义的角色分配给标识,以便应用程序可以访问 Azure Cosmos DB for NoSQL 中的数据。

重要

创建新的数据平面角色分配需要以下控制平面权限:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/read
  • Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write

有关详细信息,请参阅授予控制平面基于角色的访问权限

  1. 使用 az cosmosdb show 获取当前帐户的唯一标识符。

    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-nosql-account>" \
        --query "{id:id}"
    
  2. 观察上一命令的输出。 记录此帐户的 id 属性的值,因为下一步需要使用此属性。

    {
      "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    }
    

    注意

    在此示例中,id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql。 此示例使用虚构数据,而你的标识符与此示例不同。

  3. 使用 az cosmosdb sql role assignment create 分配新角色。 将以前记录的角色定义标识符用于 --role-definition-id 参数,将标识的唯一标识符用于 --principal-id 参数。 最后,将帐户的标识符用于 --scope 参数。

    az cosmosdb sql role assignment create \
        --resource-group "<name-of-existing-resource-group>" \
        --account-name "<name-of-existing-nosql-account>" \
        --role-definition-id "<id-of-new-role-definition>" \
        --principal-id "<id-of-existing-identity>" \
        --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    
  4. 使用 az cosmosdb sql role assignment list 列出 Azure Cosmos DB for NoSQL 帐户的所有角色分配。 查看输出以确保已创建角色分配。

    az cosmosdb sql role assignment list \
        --resource-group "<name-of-existing-resource-group>" \
        --account-name "<name-of-existing-nosql-account>"
    
  1. 创建新的 Bicep 文件以定义角色分配。 将文件命名为 data-plane-role-assignment.bicep

    metadata description = 'Assign RBAC role for data plane access to Azure Cosmos DB for NoSQL.'
    
    @description('Name of the Azure Cosmos DB for NoSQL account.')
    param accountName string
    
    @description('Id of the role definition to assign to the targeted principal in the context of the account.')
    param roleDefinitionId string
    
    @description('Id of the identity/principal to assign this role in the context of the account.')
    param identityId string
    
    resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
      name: accountName
    }
    
    resource assignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = {
      name: guid(roleDefinitionId, identityId, account.id)
      parent: account
      properties: {
        principalId: identityId
        roleDefinitionId: roleDefinitionId
        scope: account.id
      }
    }
    
    output assignmentId string = assignment.id
    
  2. 创建名为 data-plane-role-assignment 的新 Bicep 参数文件。bicepparam。 在此参数文件中,将现有 Azure Cosmos DB for NoSQL 帐户的名称分配给 accountName 参数、以前记录的角色定义标识符分配给 roleDefinitionId 参数,并将标识的唯一标识符分配给 identityId 参数。

    using './data-plane-role-assignment.bicep'
    
    param accountName = '<name-of-existing-nosql-account>'
    param roleDefinitionId = '<id-of-new-role-definition>'
    param identityId = '<id-of-existing-identity>'
    
  3. 使用 az deployment group create 部署 Bicep 模板。

    az deployment group create \
        --resource-group "<name-of-existing-resource-group>" \
        --parameters data-plane-role-assignment.bicepparam \
        --template-file data-plane-role-assignment.bicep
    
  4. 重复这些步骤,从要使用的任何其他标识授予对帐户的访问权限。

    提示

    可以根据需要为任意数量的标识重复这些步骤。 通常,这些步骤至少重复一次,以允许开发人员使用人工标识访问帐户,并允许应用程序使用托管标识进行访问。

  1. 使用 Get-AzCosmosDBAccount 获取当前帐户的元数据。

    $parameters = @{
        ResourceGroupName = "<name-of-existing-resource-group>"
        Name = "<name-of-existing-nosql-account>"
    }    
    Get-AzCosmosDBAccount @parameters | Select -Property Id
    
  2. 观察上一命令的输出。 记录此帐户的 Id 属性的值,因为下一步需要使用此属性。

    Id
    --    
    /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql
    

    注意

    在此示例中,Id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql。 此示例使用虚构数据,而你的标识符与此示例不同。

  3. 使用 New-AzCosmosDBSqlRoleAssignment 分配新角色。 将以前记录的角色定义标识符用于 RoleDefinitionId 参数,将标识的唯一标识符用于 PrincipalId 参数。 最后,将帐户的标识符用于 Scope 参数。

    $parameters = @{
        ResourceGroupName = "<name-of-existing-resource-group>"
        AccountName = "<name-of-existing-nosql-account>"
        RoleDefinitionId = "<id-of-new-role-definition>"
        PrincipalId = "<id-of-existing-identity>"
        Scope = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    }    
    New-AzCosmosDBSqlRoleAssignment @parameters
    
  4. 使用 Get-AzCosmosDBSqlRoleAssignment 列出 Azure Cosmos DB for NoSQL 帐户的所有角色分配。 查看输出以确保已创建角色分配。

    $parameters = @{
        ResourceGroupName = "<name-of-existing-resource-group>"
        AccountName = "<name-of-existing-nosql-account>"
    }
    Get-AzCosmosDBSqlRoleAssignment @parameters
    

在代码中验证数据平面访问

最后,使用首选编程语言使用应用程序代码和 Azure SDK 验证是否已正确授予访问权限。

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

重要

此代码示例使用 NuGet 中的 Microsoft.Azure.CosmosAzure.Identity 库。