Compartilhar via

Use o controle de acesso baseado em função do plano de dados com o Azure Cosmos DB for NoSQL

  • Artigo

APLICA-SE A: NoSQL

Diagrama da localização atual (

Dica

Acesse nossa nova Galeria de Amostras para obter as mais recentes amostras para compilar novos aplicativos

Esse artigo descreve as etapas para conceder acesso de identidade para gerenciar dados em uma conta do Azure Cosmos DB for NoSQL.

Importante

As etapas nesse artigo abrangem apenas o acesso ao plano de dados para executar operações em itens individuais e executar consultas. Para aprender a gerenciar funções, definições e atribuições para o plano de controle, veja conceder acesso baseado em função ao plano de controle.

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.

Preparar definição de função

Primeiro, você deve preparar uma definição de função com uma lista de dataActions para conceder acesso para ler, consultar e gerenciar dados no Azure Cosmos DB for 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

Para obter mais informações, confira conceder um acesso baseado em função do plano de dados.

Liste todas as definições de função associadas à sua conta do Azure Cosmos DB for NoSQL usando az cosmosdb sql role definition list. Revise a saída e localize a definição de função chamada Contribuidor de dados integrado do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade id. Registre esse valor, pois ele será necessário para uso na etapa de atribuição mais adiante nesse guia.

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

[
  ...,
  {
    "assignableScopes": [
      "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
    ],
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "permissions": [
      {
        "dataActions": [
          "Microsoft.DocumentDB/databaseAccounts/readMetadata",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
        ],
        "notDataActions": []
      }
    ],
    "resourceGroup": "msdocs-identity-example",
    "roleName": "Cosmos DB Built-in Data Contributor",
    "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
    "typePropertiesType": "BuiltInRole"
  }
  ...
]

Observação

Por exemplo, neste exemplo, o valor de id 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. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo.

Use Get-AzCosmosDBSqlRoleDefinition para listar todas as definições de função associadas à sua conta do Azure Cosmos DB for NoSQL. Revise a saída e localize a definição de função chamada Contribuidor de dados integrado do Cosmos DB. A saída contém o identificador exclusivo da definição de função na propriedade Id. Registre esse valor, pois ele será necessário para uso na etapa de atribuição mais adiante nesse guia.

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

Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002
RoleName                   : Cosmos DB Built-in Data Contributor
Type                       : BuiltInRole
AssignableScopes           : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccountsmsdocs-identity-example-nosql}
Permissions.DataActions    : {Microsoft.DocumentDB/databaseAccounts/readMetadata, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*}
Permissions.NotDataActions :

Observação

Por exemplo, neste exemplo, o valor de Id 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. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo. No entanto, o identificador (00000000-0000-0000-0000-000000000002) é exclusivo em todas as definições de função na sua conta.

Atribuir função à identidade

Agora, atribua a função recém-definida a uma identidade para que seus aplicativos possam acessar dados no Azure Cosmos DB for NoSQL.

Importante

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

Para obter mais informações, confira conceder um acesso baseado em função do plano de dados.

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

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

  2. Observe a saída do comando anterior. Registre o valor da propriedade id para essa conta, pois ela será necessária para uso 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

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

  3. 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 argumento --role-definition-id e o identificador exclusivo para sua identidade para o argumento --principal-id. Por fim, use o identificador da sua conta para o argumento --scope.

    az cosmosdb sql role assignment create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --role-definition-id "<id-of-new-role-definition>" \
    --principal-id "<id-of-existing-identity>" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"

  4. Use az cosmosdb sql role assignment list para listar todas as atribuições de função para sua conta do Azure Cosmos DB for NoSQL. Revise a saída para garantir que sua atribuição de função foi criada.

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

  1. 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

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

resource assignment 'Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments@2024-05-15' = {
  name: guid(roleDefinitionId, identityId, account.id)
  parent: account
  properties: {
    principalId: identityId
    roleDefinitionId: roleDefinitionId
    scope: account.id
  }
}

output assignmentId string = assignment.id

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

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

param accountName = '<name-of-existing-nosql-account>'
param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

  3. Implante o modelo Bicep usando o 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

  4. Repita essas etapas para conceder acesso à conta de qualquer outra identidade que você queira 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 para permitir que os aplicativos acessem usando uma identidade gerenciada.

  1. 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

  2. Observe a saída do comando anterior. Registre o valor da propriedade Id para essa conta, pois ela será necessária para uso 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

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

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

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleDefinitionId = "<id-of-new-role-definition>"
    PrincipalId = "<id-of-existing-identity>"
    Scope = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql"
}    
New-AzCosmosDBSqlRoleAssignment @parameters

  4. Liste todas as atribuições de função para sua conta do Azure Cosmos DB for NoSQL usando Get-AzCosmosDBSqlRoleAssignment. Revise a saída para garantir que sua atribuição de função foi criada.

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

Validar acesso ao plano de dados no código

Por fim, valide se você concedeu acesso corretamente usando o código do aplicativo e o SDK do Azure na sua linguagem de programação preferida.

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

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Importante

Esse exemplo de código usa as bibliotecas Microsoft.Azure.Cosmos e Azure.Identity do NuGet.