Compartilhar via

Use o controle de acesso baseado em função com o Azure Cosmos DB for Table (versão prévia)

  • Artigo
  • Aplica-se a:
    ✅ Table

Diagrama da localização atual (

Este artigo percorre as etapas para conceder a uma identidade acesso para gerenciar dados em uma conta do Azure Cosmos DB for Table. As etapas nesse artigo abrangem apenas o acesso ao plano de dados para executar operações em itens individuais e executar consultas.

Pré-requisitos

  • Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
  • Uma conta existente do Azure Cosmos DB for Table.
  • 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 leitura, consulta e gerenciar dados no Azure Cosmos DB for Table.

Primeiro, obtenha o identificador de recurso da conta existente do Azure Cosmos DB for Table usando az cosmsodb show e armazene-o em uma variável. Em seguida, liste todas as definições de função associadas à sua conta do Azure Cosmos DB for Table usando az rest. Por fim, revise a saída e localize a definição de função nomeada Colaborador de Dados Interno 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.

resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "GET" \
    --url $resourceId/tableRoleDefinitions?api-version=2023-04-15

[
  ...,
  {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/tableRoleDefinitions/00000000-0000-0000-0000-000000000002",
    "name": "00000000-0000-0000-0000-000000000002",
    "properties": {
      "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/tables/*",
            "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
          ],
          "notDataActions": []
        }
      ],
      "roleName": "Cosmos DB Built-in Data Contributor",
      "type": "BuiltInRole"
    },
    "type": "Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions"
  }
  ...
]

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/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo. Essa saída de exemplo está truncada.

Use Get-AzCosmosDBAccount para obter o identificador de recurso da conta existente do Azure Cosmos DB for Table e armazene-o em uma variável. Em seguida, use Invoke-AzRestMethod para listar todas as definições de função associadas à sua conta do Azure Cosmos DB for Table. Revise a saída e localize a definição de função chamada Colaborador interno de dados 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>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id

$parameters = @{
  Path = "$resourceId/tableRoleDefinitions?api-version=2023-04-15"
  Method = "GET"
}
Invoke-AzRestMethod @parameters

StatusCode : 200
Content    : {
               "value": [
                ...,
                {
                  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/tableRoleDefinitions/00000000-0000-0000-0000-000000000002",
                  "name": "00000000-0000-0000-0000-000000000002",
                  "properties": {
                    "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/tables/*",
                          "Microsoft.DocumentDB/databaseAccounts/tables/containers/entities/*"
                        ],
                        "notDataActions": []
                      }
                    ],
                    "roleName": "Cosmos DB Built-in Data Contributor",
                    "type": "BuiltInRole"
                  },
                  "type": "Microsoft.DocumentDB/databaseAccounts/tableRoleDefinitions"
                }
                ...
               ]
             }
...

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/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. Esse exemplo usa dados fictícios e seu identificador seria diferente deste exemplo. Essa saída de exemplo está truncada.

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

Importante

Essa tarefa de atribuição requer que você tenha o identificador exclusivo de qualquer identidade que deseja conceder permissões de controle de acesso baseado em função. Se você não tiver um identificador exclusivo para uma identidade, siga as instruções nos guias criar identidade gerenciada ou obter identidade assinada.

  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-resource-group>" \
    --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. Crie um arquivo JSON chamado role-assignment.json. No arquivo JSON, adicione o identificador exclusivo para sua identidade e o identificador exclusivo para o recurso de conta.

    {
  "properties": {
    "roleDefinitionId": "<account-resource-id>/tableRoleDefinitions/d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4",
    "scope": "<account-resource-id>",
    "principalId": "<id-of-existing-identity>"
  }
}

    Observação

    Neste exemplo, o GUID único especificado foi d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4. Você pode usar o GUID exclusivo que usou anteriormente para sua própria definição de função.

  4. Agora crie ou atualize uma atribuição de função usando az cosmosdb show e az rest juntos para emitir uma solicitação HTTP PUT. Como parte dessa solicitação, especifique um GUID exclusivo para sua atribuição de função.

    resourceId=$( \
    az cosmosdb show \
        --resource-group "<name-of-existing-resource-group>" \
        --name "<name-of-existing-table-account>" \
        --query "id" \
        --output tsv \
)

az rest \
    --method "PUT" \
    --url $resourceId/tableRoleAssignments/e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5?api-version=2023-04-15 \
    --body @role-assignment.json

    Observação

    Neste exemplo, o GUID único especificado foi e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Você pode especificar qualquer GUID exclusivo para sua própria atribuição de função.

  1. Crie outro arquivo Bicep para atribuir uma função a uma identidade. Nomeie este arquivo data-plane-role-assignment.bicep.

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

@description('Name of the Azure Cosmos DB for Table 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@2023-04-15' existing = {
  name: accountName
}

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

output id string = assignment.id

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

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

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

  3. Implante este 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

  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 o identificador exclusivo para 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. Agora crie ou atualize uma atribuição de função usando Get-AzCosmosDBAccount e Invoke-AzRestMethod juntos para emitir uma solicitação HTTP PUT. Como parte dessa solicitação, especifique um GUID exclusivo para sua atribuição de função. Por fim, crie uma carga de atribuição de recurso especificando o identificador exclusivo para sua identidade.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    Name = "<name-of-existing-table-account>"
}
$resourceId = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Id -First 1
).Id    

$payload = @{
  properties = @{
    roleDefinitionId = "$resourceId/tableRoleDefinitions/00000000-0000-0000-0000-000000000002"
    scope = "$resourceId"
    principalId = "<id-of-existing-identity>"
  }
}

$parameters = @{
  Path = "$resourceId/tableRoleAssignments/e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5?api-version=2023-04-15"
  Method = "PUT"
  Payload = $payload | ConvertTo-Json -Depth 2
}
Invoke-AzRestMethod @parameters

    Observação

    Neste exemplo, o GUID único especificado foi e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Você pode especificar qualquer GUID exclusivo para sua própria atribuição de função.

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.Identity;
using Azure.Data.Tables;

string endpoint = "<account-endpoint>";

DefaultAzureCredential credential = new();

TableServiceClient client = new(
    endpoint: new Uri(endpoint),
    tokenCredential: credential
);

TableClient table = client.GetTableClient(
    tableName: "<name-of-table>"
);

Importante

Esse exemplo de código usa as bibliotecas Azure.Data.Tables e Azure.Identity do NuGet.

Aviso

Se você estiver usando uma identidade gerenciada atribuída pelo usuário, será necessário especificar o identificador exclusivo da identidade gerenciada como parte da criação do objeto de credenciais.