使用英语阅读

通过

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

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

  • 项目
选择 Azure 接口

适用范围： NoSQL

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

提示

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

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

重要

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

先决条件

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

准备角色定义

首先，必须准备一个角色定义，其中包含授予对 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 角色定义的唯一标识符。 记下此值，因为本指南后面的工作分配步骤需要使用此值。

Azure CLI 
az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
JSON 
[
  ...,
  {
    "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 角色定义的唯一标识符。 记下此值，因为本指南后面的工作分配步骤需要使用此值。

Azure PowerShell 
$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 获取当前帐户的唯一标识符。

    Azure CLI 
    az cosmosdb show \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-nosql-account>" \
    --query "{id:id}"

  2. 观察上一命令的输出。 记录此帐户的 id 属性的值，因为下一步需要使用此属性。

    JSON 
    {
  "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 参数。

    Azure CLI 
    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 帐户的所有角色分配。 查看输出以确保已创建角色分配。

    Azure CLI 
    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。

    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 参数。

    Bicep 
    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 模板。

    Azure CLI 
    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 获取当前帐户的元数据。

    Azure PowerShell 
    $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 参数。

    Azure PowerShell 
    $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 帐户的所有角色分配。 查看输出以确保已创建角色分配。

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

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

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

C# 
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.Cosmos 和 Azure.Identity 库。