Compartir a través de

Uso del control de acceso basado en rol del plano de datos con Azure Cosmos DB para NoSQL

  • Artículo

SE APLICA A: NoSQL

Diagrama de la ubicación actual (

Sugerencia

Visite nuestra nueva Galería de ejemplos para obtener los ejemplos más recientes para compilar nuevas aplicaciones

En este artículo se describen los pasos para conceder acceso a una identidad para administrar datos en una cuenta de Azure Cosmos DB para NoSQL.

Importante

Los pasos de este artículo solo cubren el acceso al plano de datos para realizar operaciones en elementos individuales y ejecutar consultas. Para obtener información sobre cómo administrar bases de datos y contenedores para el plano de control, consulte Concesión de acceso basado en roles del plano de control.

Requisitos previos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
  • Una cuenta existente de Azure Cosmos DB for NoSQL.
  • 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 datos de lectura, consulta y administración en Azure Cosmos DB para NoSQL.

Importante

La obtención de una definición de rol del plano de datos existente requiere estos permisos de plano de control:

  • Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/read

Para obtener más información, consulte conceder acceso basado en rol del plano de control.

Enumere todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB para NoSQL mediante az cosmosdb sql role definition list. 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.

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:

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/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

Use Get-AzCosmosDBSqlRoleDefinition para enumerar todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB para NoSQL. 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>"
    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:

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/sqlRoleDefinitions/00000000-0000-0000-0000-000000000002. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Sin embargo, el identificador (00000000-0000-0000-0000-000000000002) es único en todas las definiciones de roles de la cuenta.

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

Importante

Crear una nueva asignación de rol de plano de datos requiere estos permisos de plano de control:

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

Para obtener más información, consulte conceder acceso basado en rol del plano de control.

  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-nosql-account>" \
    --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. Asigne el nuevo rol mediante az cosmosdb sql role assignment create. Use los identificadores de definición de roles registrados anteriormente en el argumento --role-definition-id y el identificador único de la identidad en el argumento --principal-id. Por último, use el identificador de la cuenta para el 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 enumerar todas las asignaciones de roles de la cuenta de Azure Cosmos DB para NoSQL. Revise la salida para asegurarse de que se creó la asignación de roles.

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

  1. Cree un nuevo archivo de Bicep para definir la asignación de roles. Asigne al archivo el nombre 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. 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 para NoSQL 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-nosql-account>'
param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

  3. Implemente la 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 los metadatos 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. Use New-AzCosmosDBSqlRoleAssignment para asignar el nuevo rol. Use los identificadores de definición de roles registrados anteriormente en el parámetro RoleDefinitionId y el identificador único de la identidad en el parámetro PrincipalId. Por último, use el identificador de la cuenta para el 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. Enumere todas las asignaciones de roles para la cuenta de Azure Cosmos DB para NoSQL mediante Get-AzCosmosDBSqlRoleAssignment. Revise la salida para asegurarse de que se creó la asignación de roles.

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

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.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Importante

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