使用基于角色的访问控制和Microsoft Entra ID连接到Azure Cosmos DB for NoSQL

Aplica-se a: ✅ NoSQL

基于角色的访问控制是指管理对Azure中资源的访问的方法。此方法基于将特定标识分配角色，管理其对一个或多个资源的访问级别。基于角色的访问控制提供了一个灵活的精细访问管理系统，可确保身份仅具有完成任务所需的最低权限。

有关详细信息，请参阅基于角色的访问控制。

先决条件

具有活动订阅的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/c0 命令登录到Azure CLI。若要完成身份验证过程，请遵循终端中显示的步骤。有关其他登录选项，请参阅Azure CLI登录。
- 出现提示时，请在首次使用时安装 Azure CLI 扩展。有关扩展的详细信息，请参阅使用 Azure CLI 的扩展。
- 运行 az 版本查找已安装的版本和依赖库。若要升级到最新版本，请运行 az upgrade。

如果选择在本地使用Azure PowerShell：
- 安装最新版本的 Az PowerShell 模块。
- 使用 Connect-AzAccount -Environment AzureChinaCloud cmdlet 连接到Azure帐户。

禁用基于密钥的身份验证

禁用基于密钥的授权可防止在未经更安全的 Microsoft Entra ID 身份验证方法的情况下使用您的帐户。此过程是应在安全工作负荷中的新帐户上执行的步骤。或者，对迁移到安全工作负荷模式的现有帐户执行此过程。

首先，对现有帐户禁用基于密钥的身份验证，以便应用程序需要使用Microsoft Entra ID身份验证。使用 az resource update 修改现有帐户的 properties.disableLocalAuth。

az resource update \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --set properties.disableLocalAuth=true

首先，创建禁用基于密钥的身份验证的新帐户，以便应用程序需要使用Microsoft Entra身份验证。

创建新的Bicep文件，以禁用基于密钥的身份验证方式来部署您的新帐户。将文件命名为 deploy-new-account.bicep。

metadata description = 'Deploys a new Azure Cosmos DB account with key-based auth disabled.'

@description('Name of the Azure Cosmos DB account.')
param name string = 'csms-${uniqueString(resourceGroup().id)}'

@description('Primary location for the Azure Cosmos DB account.')
param location string = resourceGroup().location

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: name
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
    disableLocalAuth: true
  }
}

使用 az deployment group create 通过新帐户部署Bicep文件。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file deploy-new-account.bicep

首先，对现有帐户禁用基于密钥的身份验证，以便应用程序需要使用Microsoft Entra身份验证。分别使用 Get-AzResource 和 Set-AzResource 来读取和更新现有账号。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ResourceName = "<name-of-existing-account>"
    ResourceType = "Microsoft.DocumentDB/databaseAccounts"
}
$resource = Get-AzResource @parameters

$resource.Properties.DisableLocalAuth = $true

$resource | Set-AzResource -Force

使用以下步骤为禁用基于密钥的身份验证的 NoSQL 帐户创建新的Azure Cosmos DB，以便应用程序只需要使用Microsoft Entra身份验证。

为NoSQL帐户设置新的Azure Cosmos DB时，导航到帐户创建过程的 Security 部分。
然后，为基于密钥的身份验证选项选择“禁用”。

重要

修改 Azure Cosmos DB 帐户需要 Azure 角色至少具备 Microsoft.DocumentDb/databaseAccounts/*/write 权限。有关详细信息，请参阅 Azure Cosmos DB 的权限。

验证是否已禁用基于密钥的身份验证

若要验证是否已禁用基于密钥的访问，请尝试使用Azure SDK通过资源所有者密码凭据（ROPC）连接到NoSQL Azure Cosmos DB。此尝试应失败。如有必要，此处提供了常见编程语言的代码示例。

using Microsoft.Azure.Cosmos;

string connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;";

CosmosClient client = new(connectionString);

const { CosmosClient } = require('@azure/cosmos');

const connectionString = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client = new CosmosClient(connectionString);

import { CosmosClient } from '@azure/cosmos'

let connectionString: string = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client: CosmosClient = new CosmosClient(connectionString);

from azure.cosmos import CosmosClient

connection_string = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

client = CosmosClient(connection_string)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

func main() {
    client, _ := azcosmos.NewClientFromConnectionString(connectionString, nil)
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

public class NoSQL{
    public static void main(String[] args){
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<nosql-endpoint>")
            .key("<key>")
            .buildClient();
    }
}

use azure_data_cosmos::CosmosClient;

fn main() {
    let client = CosmosClient::new_with_access_key(
        "<account-endpoint>",
        "<account-key>",
        None,
    ).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

授予控制平面基于角色的访问控制

控制平面访问是指无需管理数据即可管理Azure服务的资源。例如，Azure Cosmos DB 控制平面访问可能包括：

读取所有帐户和资源元数据
读取和重新生成帐户密钥和连接字符串
执行帐户备份和还原
启动和跟踪数据传输作业
管理数据库和容器
修改帐户属性

重要

在 Azure Cosmos DB 中，您需要控制平面权限来管理原生的数据平面基于角色的访问控制定义和分配。由于 Azure Cosmos DB 数据平面的角色访问控制机制是原生的，因此需要控制平面的访问权限来进行定义和分配的创建，并将其存储为 Azure Cosmos DB 帐户中的资源。

首先，必须使用 actions 列表准备角色定义，以授予Azure Cosmos DB中管理帐户资源的访问权限。在本指南中，您将设置内置和自定义角色。然后，将新定义的角色[s]分配给身份，以便应用程序可以访问 Azure Cosmos DB 中的资源。

使用 az role definition list 列出与Azure Cosmos DB帐户关联的所有角色定义。
```
az role definition list \
    --name "Cosmos DB Operator"
```

查看输出并找到名为 Cosmos DB 运算符的角色定义。输出包含属性中 id 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

注释

在此示例中，id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa。此示例使用虚构数据，标识符与此示例不同。但是，标识符（230815da-be43-4aae-9cb4-875f7bd000aa）在Azure中的所有角色定义中全局唯一。

使用 az group show 获取当前资源组的元数据。

az group show \
    --name "<name-of-existing-resource-group>"

观察上一命令的输出。记录此资源组的属性 id 值，因为下一步需要使用此属性。
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "chinanorth3",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
注释

在此示例中，该值 id 为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. 此示例使用虚构数据，标识符与此示例不同。此字符串是输出的截断示例。
创建名为 role-definition.json的新 JSON 文件。在文件中，创建此资源定义，指定此处列出的值。在AssignableScopes列表中，添加上一步中记录的资源组的id属性。
```
{
  "Name": "Azure Cosmos DB Control Plane Owner",
  "IsCustom": true,
  "Description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "Actions": [
    "Microsoft.DocumentDb/*"
  ],
  "AssignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ]
}
```
注释

此示例使用 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example 上一步中记录的值。实际资源标识符可能有所不同。
使用 az role definition create 创建新的角色定义。使用 role-definition.json 文件作为 --role-definition 参数的输入。
```
az role definition create \
    --role-definition role-definition.json
```

查看定义创建命令的输出。输出包含属性中 id 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

{
  "assignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ],
  "description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDb/*"
      ]
    }
  ],
  "roleName": "Azure Cosmos DB Control Plane Owner",
  "roleType": "CustomRole"
}

注释

在此示例中，id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。此示例使用虚构数据，标识符与此示例不同。此示例是部署输出的典型 JSON 的一个子集，以便于清晰展示。

使用 az group show 再次获取当前资源组的元数据。

az group show \
    --name "<name-of-existing-resource-group>"

观察上一命令的输出。记录此资源组的属性 id 值，因为下一步需要使用此属性。
```
{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
注释

在此示例中，该值 id 为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. 此示例使用虚构数据，标识符与此示例不同。此字符串是输出的截断示例。
使用 az role assignment create 分配新角色。使用资源组的标识符作为--scope参数，角色的标识符作为-role参数，您的标识的唯一标识符作为--assignee参数。
```
az role assignment create \
    --assignee "<your-principal-identifier>" \
    --role "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
```
注释

在这个示例命令中，scope 被设置为上一个步骤中示例的虚构示例 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example。资源组的标识符与此示例不同。 role也设置为虚构的/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。同样，角色标识符将不同。

观察命令的输出。输出中包含分配的唯一标识符在 id 属性中。

{
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "ffffffff-5555-6666-7777-aaaaaaaaaaaa",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "msdocs-identity-example",
  "roleDefinitionId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "scope": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "type": "Microsoft.Authorization/roleAssignments"
}

注释

在此示例中，id 属性为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1，这是另一个虚构的示例。

重复这些步骤，以便从您希望使用的任何其他身份向账户授予访问权限。

小窍门

可以根据需要为任意数量身份重复这些步骤。通常，这些步骤至少重复一次，以允许开发人员使用其个人身份访问帐户，并允许应用程序使用托管身份访问数据。

使用 az role definition list 列出与Azure Cosmos DB帐户关联的所有角色定义。
```
az role definition list \
    --name "Cosmos DB Operator"
```

[
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

注释

创建新的Bicep文件以定义角色定义。将文件 control-plane-role-definition.bicep 命名。将以下项 actions 添加到定义：

	Description
*`Microsoft.DocumentDb/`**	启用所有可能的作。

metadata description = 'Create RBAC definition for control plane access to Azure Cosmos DB.'

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB Control Plane Owner'

@description('Description of the role definition.')
param roleDefinitionDescription string = 'Can perform all control plane actions for an Azure Cosmos DB account.'

resource definition 'Microsoft.Authorization/roleDefinitions@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionName)
  scope: resourceGroup()
  properties: {
    roleName: roleDefinitionName
    description: roleDefinitionDescription
    type: 'CustomRole'
    permissions: [
      {
        actions: [
          'Microsoft.DocumentDb/*'
        ]
      }
    ]
    assignableScopes: [
      resourceGroup().id
    ]
  }
}

output definitionId string = definition.id

使用 az deployment group create 部署Bicep模板。指定Bicep模板的名称和Azure资源组。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file control-plane-role-definition.bicep

查看部署的输出。输出包含属性中 properties.outputs.definitionId.value 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。
```
{
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
      }
    }
  }
}
```
注释

在此示例中，id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1。此示例使用虚构数据，标识符与此示例不同。此示例是部署输出的典型 JSON 的一个子集，以便于清晰展示。

创建新的 Bicep 文件以定义角色分配。将文件命名为 control-plane-role-assignment.bicep。

metadata description = 'Assign RBAC role for control plane access to Azure Cosmos DB.'

@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 assignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionId, identityId)
  scope: resourceGroup()
  properties: {
    roleDefinitionId: roleDefinitionId
    principalId: identityId
  }
}

创建名为 control-plane-role-assignment.bicepparam 的新 Bicep 参数文件。在此参数文件中。将以前记录的角色定义标识符分配给参数 roleDefinitionId，将您身份的唯一标识符分配给参数 identityId。
```
using './control-plane-role-assignment.bicep'

param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'
```

使用 az deployment group create 部署此Bicep模板。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters control-plane-role-assignment.bicepparam \
    --template-file control-plane-role-assignment.bicep

重复这些步骤，以便从您希望使用的任何其他身份向账户授予访问权限。

小窍门

可以根据需要为任意数量身份重复这些步骤。通常，这些步骤至少重复一次，以允许开发人员使用其个人身份访问帐户，并允许应用程序使用托管身份访问数据。

登录到Azure门户（https://portal.azure.cn）。
在global search栏中输入 Resource group。
在 “服务”中，选择 “资源组”。
在“ 资源组 ”窗格中，选择现有的资源组。

注释

此示例屏幕截图包括 msdocs-identity-example 资源组。实际的资源组名称可能不同。
在资源组的窗格中，在服务菜单中选择Access control （IAM）。
在 Access control （IAM） 窗格中，选择 Roles。
在 “角色 ”部分中，使用搜索短语 Cosmos DB 并找到 Cosmos DB 操作员 角色定义。然后，选择与该定义关联的 “视图 ”选项。
在 Cosmos DB 操作员 角色定义对话框中，查看分配给此角色定义的一部分的操作。
关闭 Cosmos DB 操作员 角色定义对话框。
返回访问控制（IAM）窗格中，选择添加。然后选择 “添加自定义角色”。

在 “基本信息 ”窗格中，配置以下选项，然后选择“ 下一步” ：

	价值
自定义角色名称	`Azure Cosmos DB Control Plane Owner`
说明	`Can perform all control plane actions for an Azure Cosmos DB account.`
基线权限	从头开始

用于添加自定义角色的“基本信息”窗格的截图。

在“ 权限 ”窗格中，选择“ 添加权限”。然后，在权限对话框中搜索 DocumentDB 。最后，选择 Microsoft。DocumentDB 选项。

添加自定义角色的“权限”窗格截图。

屏幕截图显示“添加权限”对话框，其中筛选仅显示与“DocumentDB”相关的权限，用于添加自定义角色。
在权限对话框中，选择所有Microsoft.DocumentDB。然后选择 “添加 ”以返回到“权限 ”窗格。

在自定义角色的对话框中选择“DocumentDB”的所有权限的截屏。
返回“ 权限 ”窗格，观察权限列表。然后选择 “查看 + 创建”。

“权限”窗格的屏幕截图，其中为自定义角色添加了多个权限。
在 “审阅 + 创建 ”窗格中，查看新角色定义的指定选项。最后，选择“ 创建”。
等待门户完成角色定义创建。
在 Access control （IAM） 窗格中，选择 Add，然后选择 Add 角色分配。
在 Role 窗格中，搜索 Azure Cosmos DB，然后选择本指南前面创建的Azure Cosmos DB控制平面所有者角色。然后选择下一步。

小窍门

可以选择筛选角色列表，以仅包含自定义角色。
在“ 成员 ”窗格中，选择“ 选择成员 ”选项。在成员对话框中，选择要为 Azure Cosmos DB 帐户授予此级别访问权限的标识，然后使用 Select 选项确认选择。

注释

此屏幕截图演示了一个名为 “Kai Carter” 和主体 kai@adventure-works.com的示例用户。
返回“ 成员 ”窗格，查看所选成员[s]，然后选择“ 审阅 + 分配”。
在 “审阅 + 分配 ”窗格中，查看新角色分配的指定选项。最后，选择“ 审阅 + 分配”。
等待门户完成创建角色分配。

使用 Get-AzRoleDefinition 列出与Azure Cosmos DB帐户关联的所有角色定义。
```
$parameters = @{
    Name = "Cosmos DB Operator"
}
Get-AzRoleDefinition @parameters
```

查看输出并找到名为 Cosmos DB 内置数据参与者的角色定义。输出包含属性中 Id 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

Name             : Cosmos DB Operator
Id               : 230815da-be43-4aae-9cb4-875f7bd000aa
IsCustom         : False
Description      : Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.
Actions          : {Microsoft.DocumentDb/databaseAccounts/*, Microsoft.Insights/alertRules/*, Microsoft.Authorization/*/read, Microsoft.ResourceHealth/availabilityStatuses/read…}
NotActions       : {Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*, Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*, Microsoft.DocumentDB/databaseAccounts/regenerateKey/*, Microsoft.DocumentDB/databaseAccounts/listKeys/*…}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/}

注释

在此示例中，该值 Id 为 230815da-be43-4aae-9cb4-875f7bd000aa. 该标识符在Azure中的所有角色定义中全局唯一。

使用 Get-AzResourceGroup 获取当前资源组的元数据。

$parameters = @{
    Name = "<name-of-existing-resource-group>"
}
Get-AzResourceGroup @parameters

观察上一命令的输出。记录此资源组的属性 ResourceId 值，因为下一步需要使用此属性。
```
ResourceGroupName : msdocs-identity-example
Location          : westus
ProvisioningState : Succeeded
ResourceId        : /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example
```
注释

在此示例中，该值 ResourceId 为 /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example. 此示例使用虚构数据，标识符与此示例不同。此字符串是典型输出的截断示例。

首先，导入 Az.Resources 模块。然后，创建新的 Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition 对象。在对象中，创建此资源定义，指定此处列出的值。在AssignableScopes列表中，添加上一步中记录的资源组的ResourceId属性。最后，使用角色定义对象作为-Role的New-AzRoleDefinition参数输入。

Import-Module Az.Resources

$parameters = @{
    TypeName = "Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition"
    Property = @{
        Name = "Azure Cosmos DB Control Plane Owner"
        Description = "Can perform all control plane actions for an Azure Cosmos DB account."
        IsCustom = $true
        Actions = @(
            "Microsoft.DocumentDb/*"
        )
        AssignableScopes = @(
            "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
        )
    }
}
$role = New-Object @parameters

New-AzRoleDefinition -Role $role

注释

此示例使用 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example 上一步中记录的值。实际资源标识符可能有所不同。

查看定义创建命令的输出。输出包含属性中 Name 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

Name             : Azure Cosmos DB Control Plane Owner
Id               : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5
IsCustom         : True
Description      : Can perform all control plane actions for an Azure Cosmos DB account.
Actions          : {Microsoft.DocumentDb/*}
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example}

注释

在此示例中，Name 值将为 Azure Cosmos DB Control Plane Owner。此示例是为了清晰起见而展示的典型部署输出的一个子集。

使用 New-AzRoleAssignment 分配新角色。对于 RoleDefinitionName 参数使用角色名称，而对于 ObjectId 参数则使用您的标识唯一标识符。

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ObjectId = "<your-principal-identifier>"
    RoleDefinitionName = "Azure Cosmos DB Control Plane Owner"
}
New-AzRoleAssignment @parameters

观察命令的输出。输出中包含分配的唯一标识符在 RoleAssignmentId 属性中。

RoleAssignmentName : ffffffff-5555-6666-7777-aaaaaaaaaaaa
RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example
DisplayName        : Kai Carter
SignInName         : <kai@adventure-works.com>
RoleDefinitionName : Azure Cosmos DB Control Plane Owner
RoleDefinitionId   : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5

注释

在此示例中，RoleAssignmentId 属性为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1，这是另一个虚构的示例。此示例是为了清晰起见而展示的典型部署输出的一个子集。

重复这些步骤，以便从您希望使用的任何其他身份向账户授予访问权限。

小窍门

可以根据需要为任意数量身份重复这些步骤。通常，这些步骤至少重复一次，以允许开发人员使用其个人身份访问帐户，并允许应用程序使用托管身份访问数据。

重要

分配角色定义要求你已拥有你要授予基于角色的访问控制权限的身份的唯一标识符。

在代码中验证控制平面基于角色的访问

验证您是否已使用应用程序代码和 Azure Management SDK 正确授予了访问权限。

using Azure.Identity;
using Azure.ResourceManager;

DefaultAzureCredential credential = new();

ArmClient client = new(credential);

const { CosmosDBManagementClient } = require('@azure/arm-cosmosdb');
const { DefaultAzureCredential } = require('@azure/identity');

const subscriptionId = "<subscription-id>";

const credential = new DefaultAzureCredential();

const client = new CosmosDBManagementClient(credential, subscriptionId);

import { CosmosDBManagementClient } from '@azure/arm-cosmosdb';
import { TokenCredential, DefaultAzureCredential } from '@azure/identity';

let subscriptionId: string = "<subscription-id>";

let credential: TokenCredential = new DefaultAzureCredential();

const client: CosmosDBManagementClient = new CosmosDBManagementClient(credential, subscriptionId);

from azure.mgmt.cosmosdb import CosmosDBManagementClient
from azure.identity import DefaultAzureCredential

subscription_id = "<subscription-id>"

credential = DefaultAzureCredential()

client = CosmosDBManagementClient(credential=credential, subscription=subscription_id)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos"
)

const subscriptionId = "<subscription-id>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    
    client, _ := armcosmos.NewDatabaseClient(subscriptionId, credential, nil)
}

package com.example;

import com.azure.core.management.profile.AzureProfile;
import com.azure.core.management.AzureEnvironment;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.resourcemanager.cosmos.CosmosManager;

public class CosmosDB {
    public static void main(String[] args) {
        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
          .build();

        CosmosManager manager = CosmosManager.authenticate(credential, profile);
    }
}

授予数据平面的基于角色的访问权限

数据平面访问是指能够在Azure服务中读取和写入数据，而无需管理帐户中的资源。例如，Azure Cosmos DB数据平面访问可能包括：

读取一些帐户和资源元数据
创建、读取、更新、修补和删除项目
执行NoSQL查询
从容器的更改源读取
执行存储过程
管理冲突源中的冲突

首先，必须使用 dataActions 列表准备角色定义，以授予对NoSQL Azure Cosmos DB中读取、查询和管理数据的访问权限。在本指南中，你将准备自定义角色。然后，将新定义的角色分配给某个标识，以便您的应用程序可以访问 Azure Cosmos DB NoSQL 数据库中的数据。

Azure Cosmos DB还提供内置数据平面角色（Cosmos DB Built-in Data Reader 和 Cosmos DB Built-in Data Contributor），以简化常见的访问模式。有关详细信息，请参阅内置角色的完整列表。

重要

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

Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

创建新的数据平面角色定义需要以下控制平面权限：

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

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

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

警告

Azure Cosmos DB for NoSQL 的角色本机访问控制不支持 notDataActions 属性。自动排除未被指定为允许的任何操作。

使用 az cosmosdb sql role definition list 列出与NoSQL帐户Azure Cosmos DB关联的所有角色定义。

az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

创建名为 role-definition.json的新 JSON 文件，用于创建自定义角色。在此文件中，创建一个资源定义，指定此处列出的数据操作：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	可以读取帐户级元数据
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	可以执行任何容器级数据作业
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	可以对带有容器的项执行任何操作

{
  "RoleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "Type": "CustomRole",
  "AssignableScopes": [
    "/"
  ],
  "Permissions": [
    {
      "DataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ]
    }
  ]
}

接下来，使用 az cosmosdb sql role definition create 创建角色定义。请使用 role-definition.json 作为 --body 参数的输入。

az cosmosdb sql role definition create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --body "@role-definition.json"

查看上一命令的输出。找到刚刚为 NOSQL 数据平面所有者创建的名为 Azure Cosmos DB 的角色定义。输出包含属性中 id 角色定义的唯一标识符。记录此值，因为本指南后面的分配步骤中需要使用此值 --role-definition-id

{
  "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/bbbbbbbb-1111-2222-3333-cccccccccccc",
  "name": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "permissions": [
    {
      "dataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ],
      "notDataActions": []
    }
  ],
  "resourceGroup": "msdocs-identity-example",
  "roleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
  "typePropertiesType": "CustomRole"
}

注释

在此示例中，该值 --role-definition-id 为 bbbbbbbb-1111-2222-3333-cccccccccccc. 此示例使用虚构数据，标识符与此示例不同。

使用 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 "/"
```
小窍门

如果您尝试向基于角色的数据平面访问控制授予您自己的身份，可以使用此命令获取身份：
```
az ad signed-in-user show
```
有关详细信息，请参阅 az ad signed-in-user。
小窍门

在Azure Cosmos DB基于角色的访问控制的本机实现中，scope是指要应用权限的帐户内资源的粒度。在最高级别，您可以使用最大范围将数据平面的基于角色的访问控制分配给整个帐户。此范围包括帐户中的所有数据库和容器：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/
```
或者，可以将数据平面角色分配的范围限定为特定的数据库：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>
```
最后，可以将分配范围限定为单个容器，这是最精细的范围：
```
/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>
```
在许多情况下，可以使用相对范围而不是完全限定的范围。例如，可以使用此相对范围从 Azure CLI 命令向特定数据库和容器授予基于角色的数据平面访问控制权限：
```
/dbs/<database-name>/colls/<container-name>
```
还可以使用相对范围向所有数据库和容器授予通用访问权限。
```
/
```
使用az cosmosdb sql role assignment list列出您用于NoSQL的Azure Cosmos DB帐户的所有角色分配。查看输出以确保已创建角色分配。
```
az cosmosdb sql role assignment list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
```

使用 az cosmosdb sql role definition list 列出与NoSQL帐户Azure Cosmos DB关联的所有角色定义。

az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"

查看输出并找到名为 Cosmos DB 内置数据参与者的角色定义。输出包含属性中 id 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

[
  ...,
  {
    "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。此示例使用虚构数据，标识符与此示例不同。

创建新的Bicep文件以定义你的角色定义。将文件 命名为 data-plane-role-definition.bicep。将以下项 dataActions 添加到定义：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	可以读取帐户级元数据
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	可以执行任何容器级数据作业
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	可以对带有容器的项执行任何操作

metadata description = 'Create RBAC definition for data plane access to Azure Cosmos DB for NoSQL.'

@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB for NoSQL Data Plane Owner'

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
  name: accountName
}

resource definition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-05-15' = {
  name: guid(account.id, roleDefinitionName)
  parent: account
  properties: {
    roleName: roleDefinitionName
    type: 'CustomRole'
    assignableScopes: [
      account.id
    ]
    permissions: [
      {
        dataActions: [
          'Microsoft.DocumentDB/databaseAccounts/readMetadata'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
        ]
      }
    ]
  }
}

output definitionId string = definition.id

小窍门

在 Azure Cosmos DB 的原生角色访问控制实现中，scope 是指要应用权限的帐户之内资源的粒度。在最高级别，您可以使用最大范围将数据平面的基于角色的访问控制分配给整个帐户。此范围包括帐户中的所有数据库和容器：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

或者，可以将数据平面角色分配的范围限定为特定的数据库：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

最后，可以将分配范围限定为单个容器，这是最精细的范围：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

在许多情况下，可以使用相对范围而不是完全限定的范围。例如，可以使用此相对范围从 Azure CLI 命令向特定数据库和容器授予基于角色的数据平面访问控制权限：

/dbs/<database-name>/colls/<container-name>

还可以使用相对范围向所有数据库和容器授予通用访问权限。

创建一个名为 data-plane-role-definition.bicepparam 的新的 Bicep 参数文件。在此参数文件中，将现有Azure Cosmos DB NoSQL帐户的名称分配给 accountName 参数。
```
using './data-plane-role-definition.bicep'

param accountName = '<name-of-existing-nosql-account>'
```

使用 az deployment group create 部署Bicep模板。

az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-definition.bicepparam \
    --template-file data-plane-role-definition.bicep

创建新的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 = deployer().objectId

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

创建名为 data-plane-role-assignment.bicepparam 的新 Bicep 参数文件。在此参数文件中，将现有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>'
```
小窍门

如果您尝试为自己的标识授予基于数据平面角色的访问控制，您可以省略 identityId 参数。然后，Bicep模板使用 deployer().objectId 获取部署模板的主体的标识。有关详细信息，请参阅 deployer。

使用 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

重复这些步骤，以便从您希望使用的任何其他身份向账户授予访问权限。

小窍门

可以根据需要为任意数量身份重复这些步骤。通常，这些步骤至少重复一次，以允许开发人员使用其个人身份访问帐户。还可以重复这些步骤，来允许应用程序使用托管身份访问资源。

使用 Get-AzCosmosDBSqlRoleDefinition 列出与NoSQL帐户Azure Cosmos DB关联的所有角色定义。

$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）在帐户中的所有角色定义中都是唯一的。

使用 New-AzCosmosDBSqlRoleDefinition 创建新的角色定义。对于DataAction参数，请指定此处列出的数据操作：

	Description
`Microsoft.DocumentDB/databaseAccounts/readMetadata`	可以读取帐户级元数据
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/`**	可以执行任何容器级数据作业
*`Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/`**	可以对带有容器的项执行任何操作

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleName = "Azure Cosmos DB for NoSQL Data Plane Owner"
    Type = "CustomRole"
    AssignableScope = @(
        "/"
    )
    DataAction = @(
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
    )
}
New-AzCosmosDBSqlRoleDefinition @parameters

小窍门

在 Azure Cosmos DB 原生实现的基于角色的访问控制中，scope 指的是帐户内要应用权限的资源粒度。在最高级别，您可以使用最大范围将数据平面的基于角色的访问控制分配给整个帐户。此范围包括帐户中的所有数据库和容器：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

或者，可以将数据平面角色分配的范围限定为特定的数据库：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

最后，可以将分配范围限定为单个容器，这是最精细的范围：

/subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

/dbs/<database-name>/colls/<container-name>

还可以使用相对范围向所有数据库和容器授予通用访问权限。

使用 Get-AzCosmosDBSqlRoleDefinition 列出与NoSQL帐户Azure Cosmos DB关联的所有角色定义。

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

查看上一命令的输出。找到刚刚为 NOSQL 数据平面所有者创建的名为 Azure Cosmos DB 的角色定义。输出包含属性中 Id 角色定义的唯一标识符。记下此值，因为本指南后面的工作分配步骤需要使用此值。

Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc
RoleName                   : Azure Cosmos DB for NoSQL Data Plane Owner
Type                       : CustomRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*}
Permissions.NotDataActions :

注释

在此示例中，Id 值将为 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc。此示例使用虚构数据，标识符与此示例不同。

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

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-nosql-account>"
}    
Get-AzCosmosDBAccount @parameters | Select -Property Id

使用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 = "/"
}
New-AzCosmosDBSqlRoleAssignment @parameters
```
小窍门

如果您尝试向基于角色的数据平面访问控制授予您自己的身份，可以使用此命令获取身份：
```
Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName
```
有关详细信息，请参阅 Get-AzADUser。

使用 Get-AzCosmosDBSqlRoleAssignment 列出NoSQL帐户Azure Cosmos DB的所有角色分配。查看输出以确保已创建角色分配。

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

警告

Azure 门户中不支持管理数据平面的基于角色的访问控制。

在代码中验证数据平面基于角色的访问

使用应用程序代码和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);

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

await container.ReadItemAsync<dynamic>("<item-id>", new PartitionKey("<partition-key>"));

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<account-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential});

const container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

import { Container, CosmosClient, CosmosClientOptions } from '@azure/cosmos'
import { TokenCredential, DefaultAzureCredential } from '@azure/identity'

let endpoint: string = '<account-endpoint>';

let credential: TokenCredential = new DefaultAzureCredential();

let options: CosmosClientOptions = {
  endpoint: endpoint,
  aadCredentials: credential
};

const client: CosmosClient = new CosmosClient(options);

const container: Container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<account-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

container = client.get_database_client("<database-name>").get_container_client("<container-name>")

container.read_item(
    item="<item-id>",
    partition_key="<partition-key>",
)

import (
    "context"
    
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const endpoint = "<account-endpoint>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    client, _ := azcosmos.NewClient(endpoint, credential, nil)
    
    database, _ := client.NewDatabase("<database-name>")
    container, _ := database.NewContainer("<container-name>")
    
    _, err := container.ReadItem(context.TODO(), azcosmos.NewPartitionKeyString("<partition-key>"), "<item-id>", nil)
    if err != nil {
        panic(err)
    }
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.PartitionKey;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL {
    public static void main(String[] args) {   
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
            
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<account-endpoint>")
            .credential(credential)
            .buildClient();

        CosmosContainer container = client.getDatabase("<database-name>").getContainer("<container-name>");

        container.readItem("<item-id>", new PartitionKey("<partition-key>"), Object.class);
    }
}

use azure_data_cosmos::CosmosClient;
use azure_identity::DefaultAzureCredential;

fn main() {
    let credential = DefaultAzureCredential::new().unwrap();
    let client = CosmosClient::new("<account-endpoint>", credential, None).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

保护 Azure Cosmos DB 的 NoSQL 帐户安全
Azure Cosmos DB for NoSQL 概述

Last updated on 2026-04-10

Compartilhar via