Usar controle de acesso baseado em função com o Azure Cosmos DB para Tabela (visualização)
Diagrama da sequência do guia de implantação, incluindo esses locais, na ordem: Visão geral, Conceitos, Preparar, Controle de acesso baseado em função e Referência. O local 'Controle de acesso baseado em função' está atualmente realçado.
Este artigo descreve as etapas para conceder acesso a uma identidade para gerenciar dados em uma conta do Azure Cosmos DB for Table. As etapas neste 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 subscrição ativa. Crie uma conta gratuitamente.
- Uma conta existente do Azure Cosmos DB for Table.
- 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 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 resto . Por fim, 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.
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"
}
...
]
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/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. Este exemplo usa dados fictícios e seu identificador seria diferente deste exemplo. Este exemplo de saída está truncado.
Use Get-AzCosmosDBAccount para obter o identificador de recurso da conta existente do Azure Cosmos DB for Table e armazená-lo 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 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>"
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"
}
...
]
}
...
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/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. Este exemplo usa dados fictícios e seu identificador seria diferente deste exemplo. Este exemplo de saída está truncado.
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
Esta tarefa de atribuição requer que você tenha o identificador exclusivo de qualquer identidade que deseja conceder permissões de controle de acesso baseadas em função. Se você não tiver um identificador exclusivo para uma identidade, siga as instruções em criar identidade gerenciada ou obter guias de identidade conectados.
Use
az cosmosdb showpara obter o identificador exclusivo da sua conta corrente.az cosmosdb show \ --resource-group "<name-of-existing-resource-group>" \ --name "<name-of-existing-resource-group>" \ --query "{id:id}"Observe a saída do comando anterior. Registre o
idvalor 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
idvalor 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.Crie um novo 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>" } }Nota
Neste exemplo, o GUID exclusivo especificado foi
d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4. Você pode usar o GUID exclusivo usado anteriormente para sua própria definição de função.Agora, crie ou atualize uma atribuição de função usando
az cosmosdb showeaz restjuntos para emitir uma solicitação HTTPPUT. 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.jsonNota
Neste exemplo, o GUID exclusivo especificado foi
e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Você pode especificar qualquer GUID exclusivo para sua própria atribuição de função.
Crie outro arquivo Bicep para atribuir uma função a uma identidade. Nomeie esse 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.idCrie um novo arquivo de parâmetros do Bicep chamado
data-plane-role-assignment.bicepparam. Neste arquivo de parâmetros; atribua o nome da sua conta existente do Azure Cosmos DB for Table aoaccountNameparâmetro, os identificadores de definição de função gravados anteriormente aoroleDefinitionIdparâmetro e o identificador exclusivo da sua identidade aoidentityIdparâmetro.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>'Implante este 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.bicepRepita 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.
Use 'Get-AzCosmosDBAccount para obter o identificador exclusivo da sua conta corrente.
$parameters = @{ ResourceGroupName = "<name-of-existing-resource-group>" Name = "<name-of-existing-nosql-account>" } Get-AzCosmosDBAccount @parameters | Select -Property IdObserve a saída do comando anterior. Registre o
Idvalor 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-nosqlNota
Neste exemplo, o
Idvalor 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.Agora, crie ou atualize uma atribuição de função usando
Get-AzCosmosDBAccounteInvoke-AzRestMethodjuntos para emitir uma solicitação HTTPPUT. Como parte dessa solicitação, especifique um GUID exclusivo para sua atribuição de função. Por fim, crie uma carga útil de atribuição de recursos 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 @parametersNota
Neste exemplo, o GUID exclusivo especificado foi
e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Você pode especificar qualquer GUID exclusivo para sua própria atribuição de função.
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.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
Este exemplo de código usa as bibliotecas e Azure.Identity do Azure.Data.Tables NuGet.
Aviso
Se você estiver usando uma identidade gerenciada atribuída pelo usuário, precisará especificar o identificador exclusivo da identidade gerenciada como parte da criação do objeto de credenciais.