Compartir vía

Uso del control de acceso basado en rol con Azure Cosmos DB for Table (versión preliminar)

  • Artículo
  • Se aplica a:
    ✅ Table

Diagrama de la ubicación actual (

En este artículo se describen los pasos para conceder acceso a una identidad para administrar datos en una cuenta de Azure Cosmos DB for Table. Los pasos de este artículo solo cubren el acceso al plano de datos para realizar operaciones en elementos individuales y ejecutar consultas.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
  • Una cuenta existente de Azure Cosmos DB for Table.
  • Una o varias identidades existentes en Microsoft Entra ID.

Preparación de la definición de roles

En primer lugar, debe preparar una definición de roles con una lista de dataActions para conceder acceso a los datos de lectura, consulta y administración en Azure Cosmos DB for Table.

En primer lugar, obtenga el identificador de recurso de la cuenta de Azure Cosmos DB for Table existente mediante az cosmsodb show y almacénelo en una variable. A continuación, enumere todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB for Table mediante az rest. Por último, revise la salida y busque la definición de rol denominada Colaborador de datos integrado de Cosmos DB. La salida contiene el identificador único de la definición de roles en la propiedad id. Registre este valor ya que es necesario usarlo en el paso de asignación más adelante en esta guía.

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:

Para este ejemplo, el valor de id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Esta salida de ejemplo se trunca.

Use Get-AzCosmosDBAccount para obtener el identificador de recurso de la cuenta Azure Cosmos DB for Table existente y almacenarlo en una variable. A continuación, use Invoke-AzRestMethod para enumerar todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB for Table. Revise la salida y busque la definición de roles denominada Colaborador de datos integrado en Cosmos DB. La salida contiene el identificador único de la definición de roles en la propiedad Id. Registre este valor ya que es necesario usarlo en el paso de asignación más adelante en esta guía.

$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:

Para este ejemplo, el valor de Id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/tableRoleDefinitions/00000000-0000-0000-0000-000000000002. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Esta salida de ejemplo se trunca.

Asignación de un rol a la identidad

Ahora, asigne el rol recién definido a una identidad para que las aplicaciones puedan acceder a los datos de Azure Cosmos DB for Table.

Importante

Esta tarea de asignación requiere que tenga el identificador único de cualquier identidad que quiera conceder permisos de control de acceso basado en rol. Si no tiene un identificador único para una identidad, siga las instrucciones del crear una identidad administrada u obtener guías de identidad de inicio de sesión.

  1. Use az cosmosdb show para obtener el identificador único de la cuenta actual.

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

  2. Observe la salida del comando anterior. Registre el valor de la propiedad id para esta cuenta, ya que es necesario usar en el paso siguiente.

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

    Nota:

    Para este ejemplo, el valor de id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

  3. Cree un nuevo archivo JSON denominado role-assignment.json. En el archivo JSON, agregue el identificador único de la identidad y el identificador único para el recurso de cuenta.

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

    Nota:

    En este ejemplo, el GUID único especificado era d3d3d3d3-eeee-ffff-aaaa-b4b4b4b4b4b4. Puede usar el GUID único que usó anteriormente para su propia definición de rol.

  4. Ahora cree o actualice una asignación de roles mediante az cosmosdb show y az rest juntos para emitir una solicitud HTTP PUT. Como parte de esta solicitud, especifique un GUID único para la asignación de roles.

    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

    Nota:

    En este ejemplo, el GUID único especificado era e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Puede especificar cualquier GUID único para su propia asignación de roles.

  1. Cree otro archivo de Bicep para asignar un rol a una identidad. Asigne un nombre a este archivo 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. Cree un nuevo archivo de parámetros de Bicep denominado data-plane-role-assignment.bicepparam. En este archivo de parámetros, asigne el nombre de la cuenta de Azure Cosmos DB for Table existente al parámetro accountName, los identificadores de definición de roles registrados anteriormente al parámetro roleDefinitionId y el identificador único de la identidad al 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. Implemente esta plantilla de Bicep mediante 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 estos pasos para conceder acceso a la cuenta desde cualquier otra identidad que quiera usar.

    Sugerencia

    Puede repetir estos pasos para tantas identidades como quiera. Normalmente, estos pasos se repiten al menos para permitir que los desarrolladores accedan a una cuenta mediante su identidad humana y para permitir que las aplicaciones accedan mediante una identidad administrada.

  1. Use "Get-AzCosmosDBAccount" para obtener el identificador único de la cuenta actual.

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

  2. Observe la salida del comando anterior. Registre el valor de la propiedad Id para esta cuenta, ya que es necesario usar en el paso siguiente.

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

    Nota:

    Para este ejemplo, el valor de Id sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

  3. Ahora cree o actualice una asignación de roles mediante Get-AzCosmosDBAccount y Invoke-AzRestMethod juntos para emitir una solicitud HTTP PUT. Como parte de esta solicitud, especifique un GUID único para la asignación de roles. Por último, cree una carga de asignación de recursos que especifique el identificador único de la identidad.

    $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

    Nota:

    En este ejemplo, el GUID único especificado era e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5. Puede especificar cualquier GUID único para su propia asignación de roles.

Validación del acceso al plano de datos en el código

Por último, valide que ha concedido acceso correctamente mediante el código de aplicación y el SDK de Azure en el lenguaje de programación preferido.

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

En este ejemplo de código se usan las bibliotecas Azure.Data.Tables y Azure.Identity de NuGet.

Advertencia

Si usa una identidad administrada asignada por el usuario, deberá especificar el identificador único de la identidad administrada como parte de la creación del objeto de credenciales.