Подключение к Azure Cosmos DB для NoSQL с помощью управления доступом на основе ролей и идентификатора Microsoft Entra

Применяется к: ✅ NoSQL

Управление доступом на основе ролей относится к методу управления доступом к ресурсам в Azure. Этот метод основан на назначении определенным удостоверениям ролей, которые управляют уровнем их доступа к одному или нескольким ресурсам. Управление доступом на основе ролей обеспечивает гибкую систему точного управления доступом, которая гарантирует, что учетные записи имеют только минимально необходимый уровень доступа, чтобы выполнить свои задачи.

Дополнительные сведения см. в разделе "Управление доступом на основе ролей".

Предпосылки

Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Существующая учетная запись Azure Cosmos DB для NoSQL.
Одно или несколько существующих удостоверений в идентификаторе Microsoft Entra.

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".
Если вы предпочитаете запускать справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, подумайте о запуске Azure CLI в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login . Чтобы завершить процесс аутентификации, следуйте шагам, отображаемым в вашем терминале. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".
- Когда вас попросят, установите расширение Azure CLI при первом использовании. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Если вы решили использовать Azure PowerShell локально:
- Установите последнюю версию модуля Az PowerShell.
- Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
Если вы решили использовать Azure Cloud Shell:
- Дополнительные сведения см. в статье Общие сведения об Azure Cloud Shell.

Отключение проверки подлинности на основе ключей

Отключение авторизации на основе ключей предотвращает использование учетной записи без более безопасного метода проверки подлинности Идентификатора Microsoft Entra. Эта процедура — это шаг, который должен выполняться для новых учетных записей в безопасных рабочих нагрузках. Кроме того, выполните эту процедуру в существующих учетных записях, перенесенных в шаблон безопасной рабочей нагрузки.

Сначала отключите аутентификацию на основе ключа для вашей существующей учетной записи, чтобы приложения были обязаны использовать аутентификацию 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

Используйте эти действия, чтобы создать новую учетную запись Azure Cosmos DB для NoSQL с отключенной проверкой подлинности на основе ключей, чтобы приложения использовали только аутентификацию Microsoft Entra.

При настройке новой учетной записи Azure Cosmos DB для NoSQL перейдите в раздел "Безопасность " процесса создания учетной записи.
Затем выберите "Отключить " для параметра проверки подлинности на основе ключей .

Это важно

Для изменения учетной записи Azure Cosmos DB требуется роль Azure, которая имеет хотя бы разрешение Microsoft.DocumentDb/databaseAccounts/*/write. Дополнительные сведения см. в разделе "Разрешения для Azure Cosmos DB".

Убедитесь, что проверка подлинности на основе ключей отключена

Чтобы убедиться, что доступ на основе ключей отключен, попытайтесь подключиться к Azure Cosmos DB для NoSQL с помощью учетных данных пароля владельца ресурса (ROPC). Эта попытка должна завершиться ошибкой. При необходимости примеры кода для распространенных языков программирования предоставляются здесь.

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. В этом руководстве вы подготовите встроенную и настраиваемую роль. Затем назначьте недавно определённую роль удостоверению, чтобы приложения могли получать доступ к ресурсам в Azure Cosmos DB.

Перечислите все определения ролей, связанные с учетной записью Azure Cosmos DB, с помощью az role definition list.
```
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": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}
```
Замечание

В этом примере значение id будет /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. В этом примере используются вымышленные данные, и идентификатор будет отличаться от этого примера. Эта строка является усеченным примером выходных данных.
Создайте файл JSON с именем role-definition.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 другой вымышленный пример.

Повторите эти действия, чтобы предоставить доступ к аккаунту с использованием других учетных данных, которыми вы хотите воспользоваться.

Подсказка

Эти действия можно повторять для столько идентичностей, сколько вам нужно. Как правило, эти действия по крайней мере повторяются, чтобы разработчики могли получать доступ к учетной записи с помощью человеческого удостоверения и разрешать приложениям доступ к данным с помощью управляемого удостоверения.

Перечислите все определения ролей, связанные с учетной записью Azure Cosmos DB, с помощью az role definition list.
```
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

Разверните шаблон Bicep с помощью az deployment group create. Укажите имя шаблона 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
  }
}

Создайте файл параметров Bicep с именем control-plane-role-assignment.bicepparam В этом файле параметров, назначьте параметру roleDefinitionId ранее записанные идентификаторы определения ролей, а параметру identityId – уникальный идентификатор вашей учетной записи.
```
using './control-plane-role-assignment.bicep'

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

Разверните этот шаблон Bicep с помощью az deployment group create.

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.com).
Введите группу ресурсов в глобальной строке поиска.
В службах выберите группы ресурсов.
В области групп ресурсов выберите существующую группу ресурсов.

Замечание

В этом примере снимок экрана содержит группу msdocs-identity-example ресурсов. Имя группы ресурсов в вашей системе может отличаться.
На панели группы ресурсов выберите управление доступом (IAM) в служебном меню.
В области управления доступом (IAM) выберите роли.
В разделе "Роли" используйте фразу поиска 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 .
В диалоговом окне разрешений выберите все действия для Microsoft.DocumentDB. Затем нажмите кнопку "Добавить", чтобы вернуться в область "Разрешения".
Вернитесь в область разрешений , просмотрите список разрешений. Затем нажмите кнопку "Проверить и создать".
В области "Просмотр и создание " просмотрите указанные параметры для определения новой роли. Наконец, нажмите кнопку "Создать".
Дождитесь завершения создания определения роли на портале.
В области управления доступом (IAM) выберите "Добавить " и "Добавить назначение ролей".
На панели ролей найдите Azure Cosmos DB и выберите роль владельца уровня управления Azure Cosmos DB , созданную ранее в этом руководстве. Затем выберите Далее.

Подсказка

При необходимости можно отфильтровать список ролей, чтобы включить только пользовательские роли.
В области "Участники" выберите параметр "Выбрать участников". В диалоговом окне "Участники" выберите удостоверение, которое вы хотите предоставить этому уровню доступа для учетной записи Azure Cosmos DB, а затем используйте параметр Select , чтобы подтвердить выбор.

Замечание

На этом снимке экрана показан примерный пользователь Kai Carter с основным элементом [email protected].
Вернитесь в область "Участники", просмотрите выбранных участников и выберите "Проверить + назначить".
В области "Проверка и назначение " просмотрите указанные параметры для нового назначения ролей. Наконец, нажмите кнопку "Проверить и назначить".
Подождите, пока портал завершит создание назначения роли.

Используйте 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         : <[email protected]>
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 другой вымышленный пример. Этот пример представляет собой подмножество типичных выходных данных развертывания для ясности.
Повторите эти действия, чтобы предоставить доступ к аккаунту с использованием других учетных данных, которыми вы хотите воспользоваться.

Подсказка

Эти действия можно повторять для столько идентичностей, сколько вам нужно. Как правило, эти действия по крайней мере повторяются, чтобы разработчики могли получать доступ к учетной записи с помощью человеческого удостоверения и разрешать приложениям доступ к данным с помощью управляемого удостоверения.

Это важно

Назначение определения роли требует, чтобы у вас уже был уникальный идентификатор любого удостоверения, которому необходимо предоставить разрешения на управление доступом на основе ролей.

Проверка доступа на основе ролей уровня управления в коде

Убедитесь, что вы правильно предоставили доступ с помощью кода приложения и пакета SDK для управления Azure.

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 для предоставления доступа к чтению, выполнению запросов и управлению данными в Azure Cosmos DB для NoSQL. В этом руководстве вы создадите настраиваемую роль. Затем назначьте только что определенную роль идентификатору, чтобы приложения могли получать доступ к данным в Azure Cosmos DB для NoSQL.

Это важно

Для получения существующего определения роли плоскости данных требуются следующие разрешения уровня управления:

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 для NoSQL собственное управление доступом на основе ролей не поддерживает свойство notDataActions. Любое действие, которое не указано как разрешенное dataAction , исключается автоматически.

Составьте список всех определений ролей, связанных с учетной записью Azure Cosmos DB для NoSQL, используя az cosmosdb sql role definition list.
```
az cosmosdb sql role definition list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
```

Создайте файл JSON с именем role-definition.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"
```

Просмотрите выходные данные предыдущей команды. Найдите определение роли, которое вы только что создали с именем Azure Cosmos DB для владельца уровня данных NOSQL. Выходные данные содержат уникальный идентификатор определения роли в свойстве 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. В этом примере используются вымышленные данные, и идентификатор будет отличаться от этого примера.

Используйте id, полученный на предыдущем шаге, и определите --scope, удалив всё, что идет после имени учетной записи.

Замечание

В этом примере значение --scope будет /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. В этом примере используются вымышленные данные, и идентификатор будет отличаться от этого примера.
Назначьте новую роль с помощью 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"
```
Подсказка

Если вы пытаетесь предоставить управление доступом к элементам плоскости данных на основе ролей для своего удостоверения, используйте эту команду, чтобы получить удостоверение:
```
az ad signed-in-user show
```
Дополнительные сведения см. в разделе az ad signed-in-user.
Подсказка

В собственной реализации управления доступом на основе ролей Azure Cosmos DB область относится к детализации ресурсов в учетной записи, для которой требуется применить разрешение. На самом высоком уровне можно определить назначение управления доступом, основанного на ролях уровня данных, для всей учетной записи с использованием наибольшей области. Эта область включает все базы данных и контейнеры в учетной записи:
```
/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 для перечисления всех назначений ролей для учетной записи Azure Cosmos DB для NoSQL. Просмотрите выходные данные, чтобы убедиться, что назначение роли было создано.
```
az cosmosdb sql role assignment list \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>"
```

Составьте список всех определений ролей, связанных с учетной записью Azure Cosmos DB для NoSQL, используя az cosmosdb sql role definition list.
```
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 область относится к детализации ресурсов в учетной записи, для которой требуется применить разрешение. На самом высоком уровне можно определить назначение управления доступом, основанного на ролях уровня данных, для всей учетной записи с использованием наибольшей области. Эта область включает все базы данных и контейнеры в учетной записи:

/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>

Вы также можете предоставить универсальный доступ ко всем базам данных и контейнерам, используя относительную область действия.

Создайте файл параметров Bicep с именем data-plane-role-definition.bicepparam. В этом файле параметров назначьте имя существующей учетной записи Azure Cosmos DB для NoSQL параметру accountName .
```
using './data-plane-role-definition.bicep'

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

Разверните шаблон Bicep с помощью az deployment group create.

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

Создайте файл параметров Bicep с именем data-plane-role-assignment.bicepparam В этом файле параметров назначьте параметру accountName имя вашей существующей учетной записи Azure Cosmos DB для NoSQL, параметру 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.

Разверните шаблон Bicep с помощью az deployment group create.

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 для перечисления всех определений ролей, связанных с учетной записью Azure Cosmos DB для NoSQL.
```
$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters
```
Просмотрите выходные данные и найдите определение роли с именем Встроенный участник данных в Cosmos DB. Выходные данные содержат уникальный идентификатор определения роли в свойстве Id . Запишите это значение, так как оно необходимо использовать на шаге назначения далее в этом руководстве.
```
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

Подсказка

/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 для перечисления всех определений ролей, связанных с учетной записью Azure Cosmos DB для NoSQL.
```
$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleDefinition @parameters    
```
Просмотрите выходные данные предыдущей команды. Найдите определение роли, которое вы только что создали с именем Azure Cosmos DB для владельца уровня данных NOSQL. Выходные данные содержат уникальный идентификатор определения роли в свойстве 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

Просмотрите выходные данные предыдущей команды. Запишите значение свойства 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. В этом примере используются вымышленные данные, и идентификатор будет отличаться от этого примера.
Используется 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
```
Подсказка

Если вы пытаетесь предоставить управление доступом к элементам плоскости данных на основе ролей для своего удостоверения, используйте эту команду, чтобы получить удостоверение:
```
Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName
```
Дополнительные сведения см. в разделе Get-AzADUser.
Перечислите все назначения ролей для вашей учетной записи Azure Cosmos DB для NoSQL с использованием Get-AzCosmosDBSqlRoleAssignment. Просмотрите выходные данные, чтобы убедиться, что назначение роли было создано.
```
$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
}
Get-AzCosmosDBSqlRoleAssignment @parameters
```

Предупреждение

Управление доступом на основе ролей уровня данных не поддерживается на портале Azure.

Проверка доступа на основе ролей уровня данных в коде

Убедитесь, что вы правильно предоставили доступ с помощью кода приложения и пакета SDK Azure.

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();
}

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-09-11

Поделиться через

Подключение к Azure Cosmos DB для NoSQL с помощью управления доступом на основе ролей и идентификатора Microsoft Entra

Предпосылки

Отключение проверки подлинности на основе ключей

Убедитесь, что проверка подлинности на основе ключей отключена

Предоставление ролевого доступа к плоскости управления

Проверка доступа на основе ролей уровня управления в коде

Предоставление ролевого доступа к плоскости данных

Проверка доступа на основе ролей уровня данных в коде

Связанный контент

Обратная связь

Дополнительные ресурсы