Compartilhar via

Conectar-se ao Azure Cosmos DB for NoSQL usando o controle de acesso baseado em função e o Microsoft Entra ID

  • Aplica-se a: ✅ NoSQL

O controle de acesso baseado em função refere-se a um método para gerenciar o acesso aos recursos no Azure. Esse método baseia-se em identidades específicas atribuídas a funções que gerenciam o nível de acesso que elas têm a um ou mais recursos. O controle de acesso baseado em função fornece um sistema flexível de gerenciamento de acesso refinado que garante que as identidades tenham apenas o menor nível privilegiado de acesso necessário para executar sua tarefa.

Para obter mais informações, consulte o controle de acesso baseado em função.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

  • Uma conta existente do Azure Cosmos DB for NoSQL.

  • Uma ou mais identidades existentes no Microsoft Entra ID.

Desabilitar a autenticação baseada em chave

Desabilitar a autorização baseada em chave impede que sua conta seja usada sem o método de autenticação de ID do Microsoft Entra mais seguro. Este procedimento é uma etapa que deve ser executada em novas contas em cargas de trabalho seguras. Como alternativa, execute esse procedimento em contas existentes sendo migradas para um padrão de carga de trabalho seguro.

Primeiro, desabilite a autenticação baseada em chave em sua conta existente para que os aplicativos precisem usar a autenticação do Microsoft Entra ID. Use az resource update para modificar properties.disableLocalAuth da conta existente.

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

Primeiro, crie uma nova conta com a autenticação baseada em chave desabilitada para exigir que os aplicativos usem a autenticação do Microsoft Entra.

  1. Crie um novo arquivo Bicep para implantar sua nova conta com a autenticação baseada em chave desabilitada. Nomeie o arquivo 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
  }
}

  2. Use az deployment group create para implantar o arquivo Bicep com a nova conta.

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

Primeiro, desative a autenticação baseada em chave em sua conta existente para que os aplicativos sejam obrigados a usar a autenticação do Microsoft Entra. Use Get-AzResource e Set-AzResource para, respectivamente, ler e atualizar a conta existente.

$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

Use estas etapas para criar uma nova conta do Azure Cosmos DB para NoSQL com autenticação baseada em chaves desabilitada para que os aplicativos precisem usar apenas a autenticação do Microsoft Entra.

  1. Ao configurar uma nova conta do Azure Cosmos DB para NoSQL, navegue até a seção Segurança do processo de criação da conta.

  2. Em seguida, selecione Desabilitar para a opção de autenticação baseada em chave .

    Captura de tela da opção para desabilitar a autenticação baseada em chave ao criar uma nova conta no portal do Azure.

Importante

Modificar uma conta do Azure Cosmos DB requer uma função do Azure com pelo menos a Microsoft.DocumentDb/databaseAccounts/*/write permissão. Para obter mais informações, consulte as permissões para o Azure Cosmos DB.

Validar se a autenticação baseada em chave está desabilitada

Para validar se o acesso baseado em chave está desabilitado, tente usar o SDK do Azure para se conectar ao Azure Cosmos DB para NoSQL usando uma ROPC (credencial de senha de proprietário de recurso). Essa tentativa deve falhar. Se necessário, exemplos de código para linguagens de programação comuns são fornecidos aqui.

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

Conceder acesso baseado em função ao plano de controle

O acesso ao plano de controle refere-se à capacidade de gerenciar recursos para um serviço do Azure sem gerenciar dados. Por exemplo, o acesso ao plano de controle do Azure Cosmos DB pode incluir a capacidade de:

  • Ler todos os metadados de conta e de recurso
  • Ler e regenerar chaves de conta e cadeias de conexão
  • Executar backup e restaurar da conta
  • Iniciar e acompanhar trabalhos de transferência de dados
  • Gerenciar bancos de dados e contêineres
  • Modificar propriedades da conta

Importante

No Azure Cosmos DB, você precisa de acesso ao plano de controle para gerenciar as definições e atribuições de controle de acesso baseado em função do plano de dados nativo. Como o mecanismo de controle de acesso baseado em função do plano de dados do Azure Cosmos DB é nativo, você precisa controlar o acesso ao plano para criar definições e atribuições e armazená-las como recursos em uma conta do Azure Cosmos DB.

Primeiro, você deve preparar uma definição de função com uma lista de actions e conceder acesso para gerenciar recursos da conta no Azure Cosmos DB. Neste guia, você prepara uma função integrada e personalizada. Em seguida, atribua as funções recém-definidas a uma identidade para que seus aplicativos possam acessar recursos no Azure Cosmos DB.

  1. Liste todas as definições de função associadas à sua conta do Azure Cosmos DB usando az role definition list.

    az role definition list \
    --name "Cosmos DB Operator"

  2. Examine a saída e localize a definição de função chamada Operador Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    [
  {
    "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",
  }
]

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. No entanto, o identificador (230815da-be43-4aae-9cb4-875f7bd000aa) é globalmente exclusivo em todas as definições de função no Azure.

  3. Use az group show para obter os metadados do grupo de recursos atual.

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

  4. Observe a saída do comando anterior. Registre o valor da id propriedade para esse grupo de recursos, pois é necessário usar na próxima etapa.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "___location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. Essa cadeia de caracteres é um exemplo truncado da saída.

  5. Crie um novo arquivo JSON chamado role-definition.json. No arquivo, crie essa definição de recurso especificando os valores listados aqui. Para a lista AssignableScopes, adicione a propriedade id do grupo de recursos registrado na etapa anterior.

    {
  "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"
  ]
}

    Observação

    Este exemplo usa o /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valor registrado da etapa anterior. O identificador de recurso real pode ser diferente.

  6. Criar uma nova definição de função usando az role definition create. Use o arquivo role-definition.json como entrada para o --role-definition argumento.

    az role definition create \
    --role-definition role-definition.json

  7. Examine a saída do comando de criação de definição. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    {
  "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"
}

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. Este exemplo é um subconjunto do JSON típico gerado pela implantação para maior clareza.

  8. Use az group show para obter os metadados do grupo de recursos atual novamente.

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

  9. Observe a saída do comando anterior. Registre o valor da id propriedade para esse grupo de recursos, pois é necessário usar na próxima etapa.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "___location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. Essa cadeia de caracteres é um exemplo truncado da saída.

  10. Atribuir a nova função usando az role assignment create. Use o identificador do grupo de recursos para o --scope argumento, o identificador da função para o -role argumento e o identificador exclusivo para sua identidade para o --assignee argumento.

    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"

    Observação

    Neste comando de exemplo, o scope foi definido como o exemplo fictício /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example da etapa anterior. O identificador do grupo de recursos seria distinto deste exemplo. O role também foi configurado para o fictício /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. Novamente, o identificador de função seria distinto.

  11. Verifique a saída do comando. A saída inclui um identificador exclusivo para a atribuição na propriedade 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"
}

    Observação

    Neste exemplo, a id propriedade é /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, que é outro exemplo fictício.

  12. Repita estas etapas para conceder acesso à conta de qualquer outra identidade que você gostaria de usar.

    Dica

    Você pode repetir essas etapas para quantas identidades desejar. Normalmente, essas etapas são pelo menos repetidas para permitir que os desenvolvedores acessem uma conta usando sua identidade humana e permitir que os aplicativos acessem os dados usando uma identidade gerenciada.

  1. Liste todas as definições de função associadas à sua conta do Azure Cosmos DB usando az role definition list.

    az role definition list \
    --name "Cosmos DB Operator"

  2. Examine a saída e localize a definição de função chamada Operador Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    [
  {
    "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",
  }
]

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. No entanto, o identificador (230815da-be43-4aae-9cb4-875f7bd000aa) é globalmente exclusivo em todas as definições de função no Azure.

  3. Crie um novo arquivo Bicep para definir sua definição de função. Nomeie o arquivo como control-plane-role-definition.bicep. Adicione-os actions à definição:

    Description
    Microsoft.DocumentDb/* Habilita todas as ações possíveis. 
    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

  4. Implantar o modelo Bicep usando az deployment group create. Especifique o nome do modelo Bicep e do grupo de recursos do Azure.

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

  5. Examine a saída da implantação. A saída contém o identificador exclusivo da definição de função na propriedade properties.outputs.definitionId.value. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    {
  "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"
      }
    }
  }
}

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. Este exemplo é um subconjunto do JSON típico gerado pela implantação para maior clareza.

  6. Crie um novo arquivo Bicep para definir sua atribuição de função. Nomeie o arquivo 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
  }
}

  7. Crie um novo arquivo de parâmetros Bicep chamado control-plane-role-assignment.bicepparam. Neste arquivo de parâmetros; atribua os identificadores de definição de função registrados anteriormente ao roleDefinitionId parâmetro e o identificador exclusivo de sua identidade ao identityId parâmetro.

    using './control-plane-role-assignment.bicep'

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

  8. Implante este modelo Bicep usando 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

  9. Repita estas etapas para conceder acesso à conta de qualquer outra identidade que você gostaria de usar.

    Dica

    Você pode repetir essas etapas para quantas identidades desejar. Normalmente, essas etapas são pelo menos repetidas para permitir que os desenvolvedores acessem uma conta usando sua identidade humana e permitir que os aplicativos acessem os dados usando uma identidade gerenciada.

  1. Entre no portal do Azure (https://portal.azure.com).

  2. Insira o grupo de recursos na barra de pesquisa global.

    Captura de tela da barra de pesquisa global no portal do Azure.

  3. Em Serviços, selecione Grupos de recursos.

    Captura de tela da opção

  4. No painel Grupos de recursos , selecione o grupo de recursos existente.

    Captura de tela de um grupo de recursos existente na lista de grupos de recursos da assinatura.

    Observação

    Esta captura de tela de exemplo inclui o msdocs-identity-example grupo de recursos. O nome do grupo de recursos real pode ser diferente.

  5. No painel do grupo de recursos, selecione Controle de acesso (IAM) no menu de serviço.

    Captura de tela da opção

  6. No painel controle de acesso (IAM), selecione Funções.

    Captura de tela da opção 'Funções' no painel 'Controle de Acesso (IAM)'.

  7. Na seção Funções, use a frase de pesquisa Cosmos DB e localize a definição de função Cosmos DB Operator. Em seguida, selecione a opção Exibir associada a essa definição.

    Captura de tela de uma lista de definições de função no escopo atribuível atual filtrado para incluir apenas definições com 'Cosmos DB' no título.

  8. Na janela de definição da função Cosmos DB Operator, observe as ações atribuídas como parte dessa definição de função.

    Captura de tela da janela de diálogo 'Operador do Cosmos DB' com detalhes sobre a definição de função predefinida.

  9. Feche a caixa de diálogo da definição de função do Operador do Cosmos DB.

  10. De volta ao painel controle de acesso (IAM), selecione Adicionar. Em seguida, selecione Adicionar função personalizada.

    Captura de tela da opção

  11. No painel Básico, configure as seguintes opções e selecione Avançar:

    Value
    Nome da função personalizada Azure Cosmos DB Control Plane Owner
    Descrição Can perform all control plane actions for an Azure Cosmos DB account.
    Permissões de linha de base Começar do zero

    Captura de tela do painel 'Noções básicas' para adicionar uma função personalizada.

  12. No painel Permissões , selecione Adicionar permissões. Em seguida, pesquise DocumentDB na caixa de diálogo de permissões. Por fim, selecione a opção Microsoft.DocumentDB .

    Captura de tela do painel 'Permissões' para adicionar uma função personalizada.

    Captura de tela da caixa de diálogo 'Adicionar permissões' filtrada para permissões relacionadas ao 'DocumentDB' para adicionar uma função personalizada.

  13. Na caixa de diálogo de permissões, selecione todas as Ações para Microsoft.DocumentDB. Em seguida, selecione Adicionar para retornar ao painel *Permissões .

    Captura de tela de todas as permissões selecionadas para 'DocumentDB' em uma caixa de diálogo para uma função personalizada.

  14. De volta ao painel Permissões , observe a lista de permissões. Em seguida, selecione Examinar + criar.

    Captura de tela do painel 'Permissões' com várias permissões adicionadas à lista para uma função personalizada.

  15. No painel Examinar + criar , examine as opções especificadas para a nova definição de função. Por fim, selecione Criar.

    Captura de tela do painel 'Examinar + criar' para adicionar uma função personalizada.

  16. Aguarde até que o portal termine de criar a definição de função.

  17. No painel controle de acesso (IAM), selecione Adicionar e, em seguida, Adicionar atribuição de função.

    Captura de tela da opção

  18. No painel Função , pesquise Azure Cosmos DB e selecione a função Proprietário do Plano de Controle do Azure Cosmos DB criada anteriormente neste guia. Em seguida, selecione Avançar.

    Captura de tela do painel 'Função' para adicionar uma atribuição de função.

    Dica

    Opcionalmente, você pode filtrar a lista de funções para incluir apenas funções personalizadas.

  19. No painel Membros , selecione a opção Selecionar membros . Na caixa de diálogo membros, selecione a identidade que você deseja conceder a esse nível de acesso para sua conta do Azure Cosmos DB e use a opção Selecionar para confirmar sua escolha.

    Captura de tela do painel 'Membros' para adicionar uma atribuição de função.

    Captura de tela da caixa de diálogo de seleção de identidade para adicionar uma atribuição de função.

    Observação

    Esta captura de tela ilustra um usuário de exemplo chamado "Kai Carter" com uma entidade de segurança de kai@adventure-works.com.

  20. De volta ao painel Membros , examine os membros selecionados e selecione Examinar + atribuir.

    Captura de tela do painel 'Membros' com uma identidade selecionada para uma atribuição de função.

  21. No painel Examinar + atribuir , examine as opções especificadas para a nova atribuição de função. Por fim, selecione Examinar + atribuir.

    Captura de tela do painel 'Examinar + criar' para uma atribuição de função.

  22. Aguarde até que o portal termine de criar a atribuição de função.

  1. Use Get-AzRoleDefinition para listar todas as definições de função associadas à sua conta do Azure Cosmos DB.

    $parameters = @{
    Name = "Cosmos DB Operator"
}
Get-AzRoleDefinition @parameters

  2. Examine a saída e localize a definição de função chamada Colaborador de Dados Internos do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade Id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    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 : {/}

    Observação

    Neste exemplo, o Id valor seria 230815da-be43-4aae-9cb4-875f7bd000aa. O identificador é globalmente exclusivo em todas as definições de função no Azure.

  3. Use Get-AzResourceGroup para obter os metadados do grupo de recursos atual.

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

  4. Observe a saída do comando anterior. Registre o valor da ResourceId propriedade para esse grupo de recursos, pois é necessário usar na próxima etapa.

    ResourceGroupName : msdocs-identity-example
Location          : westus
ProvisioningState : Succeeded
ResourceId        : /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example

    Observação

    Neste exemplo, o ResourceId valor seria /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. Essa cadeia de caracteres é um exemplo truncado da saída típica.

  5. Primeiro, importe o Az.Resources módulo. Em seguida, crie um novo Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition objeto. No objeto, crie essa definição de recurso especificando os valores listados aqui. Para a lista AssignableScopes, adicione a propriedade ResourceId do grupo de recursos registrado na etapa anterior. Por fim, use o objeto de definição de função como entrada para o parâmetro -Role de 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

    Observação

    Este exemplo usa o /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valor registrado da etapa anterior. O identificador de recurso real pode ser diferente.

  6. Examine a saída do comando de criação de definição. A saída contém o identificador exclusivo da definição de função na propriedade Name. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    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}

    Observação

    Neste exemplo, o Name valor seria Azure Cosmos DB Control Plane Owner. Este exemplo é um subconjunto da saída típica da implantação a fim de melhorar a clareza.

  7. Atribuir a nova função usando New-AzRoleAssignment. Use o nome da função para o RoleDefinitionName parâmetro e o identificador exclusivo para sua identidade para o ObjectId parâmetro.

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

  8. Verifique a saída do comando. A saída inclui um identificador exclusivo para a atribuição na propriedade 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

    Observação

    Neste exemplo, a RoleAssignmentId propriedade é /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, que é outro exemplo fictício. Este exemplo é um subconjunto da saída típica da implantação a fim de melhorar a clareza.

  9. Repita estas etapas para conceder acesso à conta de qualquer outra identidade que você gostaria de usar.

    Dica

    Você pode repetir essas etapas para quantas identidades desejar. Normalmente, essas etapas são pelo menos repetidas para permitir que os desenvolvedores acessem uma conta usando sua identidade humana e permitir que os aplicativos acessem os dados usando uma identidade gerenciada.

Importante

Atribuir uma definição de função exige que você já tenha o identificador exclusivo de qualquer identidade à qual deseje conceder permissões de controle de acesso baseado em função.

Validar o acesso baseado em função do painel de controle no código

Valide se você concedeu acesso corretamente usando o código do aplicativo e o SDK de Gerenciamento do 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);
    }
}

Conceder acesso por função ao plano de dados

O acesso ao plano de dados refere-se à capacidade de ler e gravar dados em um serviço do Azure sem a capacidade de gerenciar recursos na conta. Por exemplo, o acesso ao plano de dados do Azure Cosmos DB pode incluir a capacidade de:

  • Ler alguns metadados de conta e de recurso
  • Criar, ler, atualizar, corrigir e excluir itens
  • Executar consultas NoSQL
  • Ler o feed de alterações de um contêiner
  • Executar procedimentos armazenados
  • Gerenciar conflitos no feed de conflitos

Primeiro, você deve preparar uma definição de função com uma lista dataActions para conceder acesso à leitura, consulta e gerenciamento de dados no Azure Cosmos DB para NoSQL. Neste guia, você prepara um papel integrado e personalizado. Em seguida, atribua as funções recém-definidas a uma identidade para que seus aplicativos possam acessar dados no Azure Cosmos DB para NoSQL.

Importante

A obtenção de uma definição de função de plano de dados existente requer essas permissões do plano de controle:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

A criação de uma nova definição de função do plano de dados requer essas permissões do painel de controle:

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

A criação de uma nova atribuição de função de plano de dados requer essas permissões do painel de controle:

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

Aviso

O controle nativo de acesso baseado em função do Azure Cosmos DB para NoSQL não dá suporte à propriedade notDataActions. Qualquer ação que não seja especificada como permitida dataAction é excluída automaticamente.

  1. Liste todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL usando 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>"

  2. Examine a saída e localize a definição de função chamada Colaborador de Dados Internos do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    [
  ...,
  {
    "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"
  }
  ...
]

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  3. Crie um novo arquivo JSON chamado role-definition.json. Neste arquivo, crie uma definição de recurso especificando as ações de dados listadas aqui:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Pode ler metadados no nível da conta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Pode executar quaisquer operações de dados no nível do contêiner
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Pode executar qualquer operação em itens com contêineres 
    {
  "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/*"
      ]
    }
  ]
}

  4. Em seguida, use az cosmosdb sql role definition create para criar a definição de função. Use o role-definition.json como argumento para a entrada --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"

  5. Agora, liste todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL usando 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>"

  6. Examine a saída do comando anterior. Localize a definição de função que você acabou de criar denominada Proprietário do Plano de Dados do Azure Cosmos DB para NOSQL. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    {
  "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"
}

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  7. Use az cosmosdb show para obter o identificador exclusivo para sua conta atual.

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

  8. Observe a saída do comando anterior. Registre o valor da id propriedade para essa conta, pois ela é necessária para usar na próxima etapa.

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

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  9. Atribuir a nova função usando az cosmosdb sql role assignment create. Use os identificadores de definição de função registrados anteriormente para o --role-definition-id argumento e o identificador exclusivo de sua identidade para o --principal-id argumento. Por fim, use o identificador da sua conta para o --scope argumento.

    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"

    Dica

    Se você estiver tentando conceder controle de acesso baseado em função do plano de dados à sua própria identidade, poderá usar este comando para obter a identidade:

    az ad signed-in-user show

    Para obter mais informações, consulte az ad signed-in-user.

    Dica

    Na implementação nativa do controle de acesso baseado em função do Azure Cosmos DB, o escopo refere-se à granularidade de recursos em uma conta para a qual você deseja que a permissão seja aplicada. No nível mais alto, você pode definir o escopo de uma atribuição de controle de acesso baseada em função do plano de dados para toda a conta usando o maior escopo. Esse escopo inclui todos os bancos de dados e contêineres dentro da conta:

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

    Ou você pode definir o escopo da atribuição de função do plano de dados para um banco de dados específico:

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

    Por fim, você pode definir o escopo da atribuição para um único contêiner, o escopo mais granular:

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

    Em muitos casos, você pode usar o escopo relativo em vez do escopo totalmente qualificado. Por exemplo, você pode usar esse escopo relativo para conceder permissões de controle de acesso baseado em função ao plano de dados para um banco de dados e um contêiner específicos por meio de um comando da CLI do Azure.

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

    Você também pode conceder acesso universal a todos os bancos de dados e contêineres usando o escopo relativo:

    /

  10. Use az cosmosdb sql role assignment list para listar todas as atribuições de função para sua conta do Azure Cosmos DB para NoSQL. Revise o resultado para garantir que sua atribuição de função tenha sido criada.

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

  1. Liste todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL usando 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>"

  2. Examine a saída e localize a definição de função chamada Colaborador de Dados Internos do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    [
  ...,
  {
    "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"
  }
  ...
]

    Observação

    Neste exemplo, o id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  3. Crie um novo arquivo Bicep para definir sua definição de função. Nomeie o arquivo data-plane-role-definition.bicep. Adicione-os dataActions à definição:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Pode ler metadados no nível da conta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Pode executar quaisquer operações de dados no nível do contêiner
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Pode executar qualquer operação em itens com contêineres 
    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

    Dica

    Na implementação nativa do controle de acesso baseado em função do Azure Cosmos DB, o escopo refere-se à granularidade de recursos em uma conta para a qual você deseja que a permissão seja aplicada. No nível mais alto, você pode definir o escopo de uma atribuição de controle de acesso baseada em função do plano de dados para toda a conta usando o maior escopo. Esse escopo inclui todos os bancos de dados e contêineres dentro da conta:

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

    Ou você pode definir o escopo da atribuição de função do plano de dados para um banco de dados específico:

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

    Por fim, você pode definir o escopo da atribuição para um único contêiner, o escopo mais granular:

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

    Em muitos casos, você pode usar o escopo relativo em vez do escopo totalmente qualificado. Por exemplo, você pode usar esse escopo relativo para conceder permissões de controle de acesso baseado em função ao plano de dados a um banco de dados e contêiner específicos em um comando na CLI do Azure.

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

    Você também pode conceder acesso universal a todos os bancos de dados e contêineres usando o escopo relativo:

    /

  4. Crie um novo arquivo de parâmetros Bicep chamado data-plane-role-definition.bicepparam. Neste arquivo de parâmetros, atribua o nome da sua conta existente do Azure Cosmos DB para NoSQL ao accountName parâmetro.

    using './data-plane-role-definition.bicep'

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

  5. Implantar o template Bicep usando 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

  6. Crie um novo arquivo Bicep para definir sua atribuição de função. Nomeie o arquivo 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

  7. Crie um novo arquivo de parâmetros Bicep chamado data-plane-role-assignment.bicepparam. Neste arquivo de parâmetros, atribua o nome da sua conta existente do Azure Cosmos DB para NoSQL ao accountName parâmetro, aos identificadores de definição de função registrados anteriormente ao roleDefinitionId parâmetro e ao identificador exclusivo de sua identidade ao identityId parâmetro.

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

    Dica

    Se você estiver tentando permitir o controle de acesso baseado em função do plano de dados à sua identidade, omita o parâmetro identityId. Em seguida, o modelo Bicep usa deployer().objectId para obter a identidade do principal que implantou o modelo. Para obter mais informações, consulte deployer.

  8. Implantar o modelo Bicep usando 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

  9. Repita estas etapas para conceder acesso à conta de qualquer outra identidade que você gostaria de usar.

    Dica

    Você pode repetir essas etapas para quantas identidades desejar. Normalmente, essas etapas são pelo menos repetidas para permitir que os desenvolvedores acessem uma conta usando sua identidade humana. Você também pode repetir essas etapas para permitir que os aplicativos acessem recursos usando uma identidade gerenciada.

  1. Use Get-AzCosmosDBSqlRoleDefinition para listar todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL.

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

  2. Examine a saída e localize a definição de função chamada Colaborador de Dados Internos do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade Id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    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 :

    Observação

    Neste exemplo, o Id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo. No entanto, o identificador (00000000-0000-0000-0000-000000000002) é exclusivo em todas as definições de função em sua conta.

  3. Criar uma nova definição de função usando New-AzCosmosDBSqlRoleDefinition. Para o DataAction parâmetro, especifique as ações de dados listadas aqui:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Pode ler metadados no nível da conta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Pode executar quaisquer operações de dados no nível do contêiner
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Pode executar qualquer operação em itens com contêineres 
    $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

    Dica

    Na implementação nativa do controle de acesso baseado em função do Azure Cosmos DB, o escopo refere-se à granularidade de recursos em uma conta para a qual você deseja que a permissão seja aplicada. No nível mais alto, você pode definir o escopo de uma atribuição de controle de acesso baseada em função do plano de dados para toda a conta usando o maior escopo. Esse escopo inclui todos os bancos de dados e contêineres dentro da conta:

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

    Ou você pode definir o escopo da atribuição de função do plano de dados para um banco de dados específico:

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

    Por fim, você pode definir o escopo da atribuição para um único contêiner, o escopo mais granular:

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

    Em muitos casos, você pode usar o escopo relativo em vez do escopo totalmente qualificado. Por exemplo, você pode usar esse escopo relativo para conceder permissões de controle de acesso baseado em função ao plano de dados a um banco de dados e contêiner específicos em um comando na CLI do Azure.

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

    Você também pode conceder acesso universal a todos os bancos de dados e contêineres usando o escopo relativo:

    /

  4. Use Get-AzCosmosDBSqlRoleDefinition para listar todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL.

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

  5. Examine a saída do comando anterior. Localize a definição de função que você acabou de criar denominada Proprietário do Plano de Dados do Azure Cosmos DB para NOSQL. A saída contém o identificador exclusivo da definição de função na propriedade Id. Registre este valor, pois ele é necessário para a etapa de atribuição que ocorre mais adiante neste guia.

    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 :

    Observação

    Neste exemplo, o Id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  6. Use Get-AzCosmosDBAccount para obter os metadados da sua conta atual.

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

  7. Observe a saída do comando anterior. Registre o valor da Id propriedade para essa conta, pois ela é necessária para usar na próxima etapa.

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

    Observação

    Neste exemplo, o Id valor seria /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. Este exemplo usa dados fictícios e seu identificador seria distinto deste exemplo.

  8. Use New-AzCosmosDBSqlRoleAssignment para atribuir a nova função. Use os identificadores de definição de função registrados anteriormente para o RoleDefinitionId parâmetro e o identificador exclusivo de sua identidade para o PrincipalId parâmetro. Por fim, use o identificador da sua conta para o Scope parâmetro.

    $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

    Dica

    Se você estiver tentando conceder controle de acesso baseado em função do plano de dados à sua própria identidade, poderá usar este comando para obter a identidade:

    Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName

    Para obter mais informações, consulte Get-AzADUser.

  9. Liste todas as atribuições de função para sua conta do Azure Cosmos DB para NoSQL usando Get-AzCosmosDBSqlRoleAssignment. Revise o resultado para garantir que sua atribuição de função tenha sido criada.

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

Aviso

Não há suporte para o gerenciamento do controle de acesso baseado em função do plano de dados no portal do Azure.

Validar o acesso baseado em função do plano de dados no código

Valide se você concedeu acesso corretamente usando o código do aplicativo e o SDK do 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();
}

Conteúdo relacionado