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

  • Artigo

APLICA-SE A: NoSQL

Diagrama do local atual ('Controle de acesso baseado em função') na sequência do guia de implantação.

Gorjeta

Visite a nossa nova Galeria de Amostras para obter as amostras mais recentes para criar novas aplicações

Este artigo descreve as etapas para conceder acesso a uma identidade para gerenciar dados em uma conta do Azure Cosmos DB para NoSQL.

Importante

As etapas neste artigo abrangem apenas o acesso ao plano de dados para executar operações em itens individuais e executar consultas. Para saber como gerenciar funções, definições e atribuições para o plano de controle, consulte Conceder acesso baseado em função ao plano de controle.

Pré-requisitos

  • Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
  • Uma conta existente do Azure Cosmos DB para NoSQL.
  • Uma ou mais identidades existentes no Microsoft Entra ID.

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Preparar a 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 para NoSQL.

Importante

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

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

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

Liste todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL usando az cosmosdb sql role definition listo . Revise a saída e localize a definição de função chamada Colaborador de Dados Interno do Cosmos DB. A saída contém o identificador exclusivo da definição de função na id propriedade. Registre esse valor conforme ele é necessário usar na etapa de atribuição mais adiante neste 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"
  }
  ...
]

Nota

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 diferente deste exemplo.

Use Get-AzCosmosDBSqlRoleDefinition para listar todas as definições de função associadas à sua conta do Azure Cosmos DB para NoSQL. Revise a saída e localize a definição de função chamada Colaborador de Dados Interno do Cosmos DB. A saída contém o identificador exclusivo da definição de função na Id propriedade. Registre esse valor conforme ele é necessário usar na etapa de atribuição mais adiante neste 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 :

Nota

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 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 para NoSQL.

Importante

Criar uma nova atribuição de função de plano de dados requer estas permissões de plano de controle:

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

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

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

    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 id valor da propriedade para esta conta como é necessário usar na próxima etapa.

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

    Nota

    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 diferente deste exemplo.

  3. Atribua a nova função usando az cosmosdb sql role assignment createo . Use os identificadores de definição de função gravados anteriormente para o --role-definition-id argumento e o identificador exclusivo para 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"

  4. 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 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. Neste arquivo de parâmetros, atribua o nome de sua conta existente do Azure Cosmos DB para NoSQL ao accountName parâmetro, 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 './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 az deployment group createo .

    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 estas etapas para conceder acesso à conta a partir de quaisquer outras identidades que você gostaria de usar.

    Gorjeta

    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 o acesso de aplicativos 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 Id valor da propriedade para esta conta como é necessário usar na próxima etapa.

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

    Nota

    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 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 RoleDefinitionId parâmetro e o identificador exclusivo para 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

  4. Liste todas as atribuições de função para sua conta do Azure Cosmos DB para NoSQL usando Get-AzCosmosDBSqlRoleAssignmento . 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 o 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 em 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

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