Compartir a través de

Conexión a Azure Cosmos DB para NoSQL mediante el control de acceso basado en rol y el identificador de Microsoft Entra

  • Se aplica a: ✅ NoSQL

El control de acceso basado en rol hace referencia a un método para administrar el acceso a los recursos de Azure. Este método se basa en identidades específicas a las que se asignan roles que administran el nivel de acceso que tienen a uno o varios recursos. El control de acceso basado en rol proporciona un sistema flexible de administración de acceso específico que garantiza que las identidades solo tengan el nivel de acceso con privilegios mínimos que necesitan para realizar su tarea.

Para obtener más información, consulte Control de acceso basado en rol.

Prerrequisitos

  • Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.

  • Una cuenta existente de Azure Cosmos DB para NoSQL.

  • Una o varias identidades existentes en Microsoft Entra ID.

Deshabilitación de la autenticación basada en claves

Deshabilitar la autorización basada en claves impide que la cuenta se use sin el método de autenticación de Microsoft Entra ID más seguro. Este procedimiento es un paso que debe realizarse en cuentas nuevas dentro de cargas de trabajo seguras. Como alternativa, realice este procedimiento en las cuentas existentes que se migran a un patrón de carga de trabajo seguro.

En primer lugar, deshabilite la autenticación basada en claves en su cuenta existente para que las aplicaciones estén obligadas a usar la autenticación de Microsoft Entra ID. Usa az resource update para modificar properties.disableLocalAuth de la cuenta existente.

az resource update \
    --resource-group "<name-of-existing-resource-group>" \
    --name "<name-of-existing-account>" \
    --resource-type "Microsoft.DocumentDB/databaseAccounts" \
    --set properties.disableLocalAuth=true

En primer lugar, crea una nueva cuenta con la autenticación basada en claves desactivada para que las aplicaciones deban usar la autenticación de Microsoft Entra.

  1. Cree un nuevo archivo de Bicep para implementar la nueva cuenta con la autenticación basada en claves deshabilitada. Asigne al archivo el nombre deploy-new-account.bicep.

    metadata description = 'Deploys a new Azure Cosmos DB account with key-based auth disabled.'

@description('Name of the Azure Cosmos DB account.')
param name string = 'csms-${uniqueString(resourceGroup().id)}'

@description('Primary location for the Azure Cosmos DB account.')
param location string = resourceGroup().location

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' = {
  name: name
  location: location
  kind: 'GlobalDocumentDB'
  properties: {
    databaseAccountOfferType: 'Standard'
    locations: [
      {
        locationName: location
      }
    ]
    disableLocalAuth: true
  }
}

  2. Use az deployment group create para implementar el archivo de Bicep con la nueva cuenta.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file deploy-new-account.bicep

En primer lugar, deshabilite la autenticación basada en claves en su cuenta existente para que las aplicaciones necesiten usar la autenticación de Microsoft Entra. Use Get-AzResource y Set-AzResource para leer y actualizar respectivamente la cuenta existente.

$parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ResourceName = "<name-of-existing-account>"
    ResourceType = "Microsoft.DocumentDB/databaseAccounts"
}
$resource = Get-AzResource @parameters

$resource.Properties.DisableLocalAuth = $true

$resource | Set-AzResource -Force

Siga estos pasos para crear una nueva cuenta de Azure Cosmos DB para NoSQL con autenticación basada en claves deshabilitada para que las aplicaciones solo usen la autenticación de Microsoft Entra.

  1. Al configurar una nueva cuenta de Azure Cosmos DB para NoSQL, vaya a la sección Seguridad del proceso de creación de la cuenta.

  2. A continuación, seleccione Deshabilitar para la opción autenticación basada en claves .

    Captura de pantalla de la opción para deshabilitar la autenticación basada en claves al crear una nueva cuenta en Azure Portal.

Importante

La modificación de una cuenta de Azure Cosmos DB requiere un rol de Azure con al menos el permiso Microsoft.DocumentDb/databaseAccounts/*/write. Para más información, consulte Permisos para Azure Cosmos DB.

Validar que la autenticación basada en claves está deshabilitada

Para validar que el acceso basado en claves está deshabilitado, intente usar el SDK de Azure para conectarse a Azure Cosmos DB para NoSQL mediante una credencial de contraseña de propietario de recursos (ROPC). Este intento debería fallar. Si es necesario, aquí se proporcionan ejemplos de código para lenguajes de programación comunes.

using Microsoft.Azure.Cosmos;

string connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;";

CosmosClient client = new(connectionString);

const { CosmosClient } = require('@azure/cosmos');

const connectionString = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client = new CosmosClient(connectionString);

import { CosmosClient } from '@azure/cosmos'

let connectionString: string = 'AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;';

const client: CosmosClient = new CosmosClient(connectionString);

from azure.cosmos import CosmosClient

connection_string = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

client = CosmosClient(connection_string)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const connectionString = "AccountEndpoint=<nosql-endpoint>;AccountKey=<key>;"

func main() {
    client, _ := azcosmos.NewClientFromConnectionString(connectionString, nil)
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;

public class NoSQL{
    public static void main(String[] args){
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<nosql-endpoint>")
            .key("<key>")
            .buildClient();
    }
}

use azure_data_cosmos::CosmosClient;

fn main() {
    let client = CosmosClient::new_with_access_key(
        "<account-endpoint>",
        "<account-key>",
        None,
    ).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

Concesión de acceso basado en rol del plano de control

El acceso al plano de control hace referencia a la capacidad de administrar recursos para un servicio de Azure sin administrar datos. Por ejemplo, el acceso al plano de control de Azure Cosmos DB podría incluir la capacidad de:

  • Leer todos los metadatos de la cuenta y del recurso
  • Leer y regenerar las claves de cuenta y las cadenas de conexión
  • Realización de copias de seguridad y restauración de cuentas
  • Inicio y seguimiento de trabajos de transferencia de datos
  • Administración de bases de datos y contenedores
  • Modificación de las propiedades de la cuenta

Importante

En Azure Cosmos DB, necesita acceso al plano de control para administrar las definiciones y asignaciones nativas del control de acceso basado en rol del plano de datos. Dado que el mecanismo de control de acceso basado en rol del plano de datos de Azure Cosmos DB es nativo, necesita acceso al plano de control para crear definiciones y asignaciones y almacenarlos como recursos dentro de una cuenta de Azure Cosmos DB.

En primer lugar, debe preparar una definición de roles con una lista de actions para conceder acceso para administrar recursos de cuenta en Azure Cosmos DB. En esta guía, preparará un rol integrado y personalizado. A continuación, asigne el rol recién definido a una identidad para que las aplicaciones puedan acceder a los recursos de Azure Cosmos DB.

  1. Enumere todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB mediante az role definition list.

    az role definition list \
    --name "Cosmos DB Operator"

  2. Revise la salida y busque la definición de rol denominada Operador de Cosmos DB. La salida contiene el identificador único de la definición de rol en la id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    [
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Sin embargo, el identificador (230815da-be43-4aae-9cb4-875f7bd000aa) es único globalmente en todas las definiciones de roles de Azure.

  3. Use az group show para obtener los metadatos del grupo de recursos actual.

    az group show \
    --name "<name-of-existing-resource-group>"

  4. Observe la salida del comando anterior. Registre el valor de la id propiedad para este grupo de recursos, ya que es necesario usar en el paso siguiente.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Esta cadena es un ejemplo truncado de la salida.

  5. Cree un nuevo archivo JSON denominado role-definition.json. En el archivo, cree esta definición de recurso especificando los valores enumerados aquí. En la lista AssignableScopes, agregue la propiedad id del grupo de recursos registrado en el paso anterior.

    {
  "Name": "Azure Cosmos DB Control Plane Owner",
  "IsCustom": true,
  "Description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "Actions": [
    "Microsoft.DocumentDb/*"
  ],
  "AssignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ]
}

    Nota:

    En este ejemplo se usa el /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valor registrado en el paso anterior. El identificador de recurso real podría ser diferente.

  6. Cree una nueva definición de roles mediante az role definition create. Use el archivo role-definition.json como entrada para el --role-definition argumento .

    az role definition create \
    --role-definition role-definition.json

  7. Revise la salida del comando de creación de definiciones. La salida contiene el identificador único de la definición de rol en la id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    {
  "assignableScopes": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
  ],
  "description": "Can perform all control plane actions for an Azure Cosmos DB account.",
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "permissions": [
    {
      "actions": [
        "Microsoft.DocumentDb/*"
      ]
    }
  ],
  "roleName": "Azure Cosmos DB Control Plane Owner",
  "roleType": "CustomRole"
}

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Este ejemplo es un subconjunto del json típico generado a partir de la implementación para mayor claridad.

  8. Use az group show para volver a obtener los metadatos del grupo de recursos actual.

    az group show \
    --name "<name-of-existing-resource-group>"

  9. Observe la salida del comando anterior. Registre el valor de la id propiedad para este grupo de recursos, ya que es necesario usar en el paso siguiente.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "location": "westus",
  "name": "msdocs-identity-example",
  "type": "Microsoft.Resources/resourceGroups"
}

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Esta cadena es un ejemplo truncado de la salida.

  10. Asigne el nuevo rol mediante az role assignment create. Use el identificador del grupo de recursos para el --scope argumento, el identificador del rol para el -role argumento y el identificador único de su identidad para el --assignee argumento.

    az role assignment create \
    --assignee "<your-principal-identifier>" \
    --role "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" \
    --scope "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"

    Nota:

    En este comando de ejemplo, el scope se estableció en el ejemplo ficticio /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example del ejemplo del paso anterior. El identificador del grupo de recursos sería distinto de este ejemplo. El role también se estableció en el /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 ficticio. De nuevo, el identificador de rol sería distinto.

  11. Observe la salida del comando. La salida incluye un identificador único para la asignación en la propiedad id.

    {
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "name": "ffffffff-5555-6666-7777-aaaaaaaaaaaa",
  "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222",
  "resourceGroup": "msdocs-identity-example",
  "roleDefinitionId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1",
  "scope": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example",
  "type": "Microsoft.Authorization/roleAssignments"
}

    Nota:

    En este ejemplo, la id propiedad es /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, que es otro ejemplo ficticio.

  12. 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 a los datos mediante una identidad administrada.

  1. Enumere todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB mediante az role definition list.

    az role definition list \
    --name "Cosmos DB Operator"

  2. Revise la salida y busque la definición de rol denominada Operador de Cosmos DB. La salida contiene el identificador único de la definición de rol en la id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    [
  {
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa",
    "name": "230815da-be43-4aae-9cb4-875f7bd000aa",
    "permissions": [
      {
        "actions": [
          "Microsoft.DocumentDb/databaseAccounts/*",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/deployments/*",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Support/*",
          "Microsoft.Network/virtualNetworks/subnets/joinViaServiceEndpoint/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*",
          "Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/regenerateKey/*",
          "Microsoft.DocumentDB/databaseAccounts/listKeys/*",
          "Microsoft.DocumentDB/databaseAccounts/listConnectionStrings/*",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/write",
          "Microsoft.DocumentDB/databaseAccounts/sqlRoleAssignments/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbRoleDefinitions/delete",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/write",
          "Microsoft.DocumentDB/databaseAccounts/mongodbUserDefinitions/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Cosmos DB Operator",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
  }
]

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.Authorization/roleDefinitions/230815da-be43-4aae-9cb4-875f7bd000aa. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Sin embargo, el identificador (230815da-be43-4aae-9cb4-875f7bd000aa) es único globalmente en todas las definiciones de roles de Azure.

  3. Cree un nuevo archivo de Bicep para definir tu rol. Asigne al archivo el nombre control-plane-role-definition.bicep. Agregue estos elementos actions a la definición:

    Description
    Microsoft.DocumentDb/* Habilita todas las acciones posibles. 
    metadata description = 'Create RBAC definition for control plane access to Azure Cosmos DB.'

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB Control Plane Owner'

@description('Description of the role definition.')
param roleDefinitionDescription string = 'Can perform all control plane actions for an Azure Cosmos DB account.'

resource definition 'Microsoft.Authorization/roleDefinitions@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionName)
  scope: resourceGroup()
  properties: {
    roleName: roleDefinitionName
    description: roleDefinitionDescription
    type: 'CustomRole'
    permissions: [
      {
        actions: [
          'Microsoft.DocumentDb/*'
        ]
      }
    ]
    assignableScopes: [
      resourceGroup().id
    ]
  }
}

output definitionId string = definition.id

  4. Implemente la plantilla de Bicep usando az deployment group create. Especifique el nombre de la plantilla de Bicep y el grupo de recursos de Azure.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --template-file control-plane-role-definition.bicep

  5. Revise la salida de la implementación. La salida contiene el identificador único de la definición de rol en la properties.outputs.definitionId.value propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    {
  "properties": {
    "outputs": {
      "definitionId": {
        "type": "String",
        "value": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
      }
    }
  }
}

    Nota:

    En este ejemplo, el id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleDefinitions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Este ejemplo es un subconjunto del json típico generado a partir de la implementación para mayor claridad.

  6. Cree un nuevo archivo de Bicep para definir la asignación de roles. Asigne al archivo el nombre control-plane-role-assignment.bicep.

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

@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 assignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(subscription().id, resourceGroup().id, roleDefinitionId, identityId)
  scope: resourceGroup()
  properties: {
    roleDefinitionId: roleDefinitionId
    principalId: identityId
  }
}

  7. Cree un nuevo archivo de parámetros de Bicep denominado control-plane-role-assignment.bicepparam. En este archivo de parámetros, asigne los identificadores de definición de roles registrados anteriormente al parámetro roleDefinitionId y el identificador único de su identidad al parámetro identityId.

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

param roleDefinitionId = '<id-of-new-role-definition>'
param identityId = '<id-of-existing-identity>'

  8. Implemente esta plantilla de Bicep mediante az deployment group create.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters control-plane-role-assignment.bicepparam \
    --template-file control-plane-role-assignment.bicep

  9. 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 a los datos mediante una identidad administrada.

  1. Inicie sesión en Azure Portal (https://portal.azure.com).

  2. Escriba Grupo de recursos en la barra de búsqueda global.

    Captura de pantalla de la barra de búsqueda global en Azure Portal.

  3. En Servicios, seleccione Grupos de recursos.

    Captura de pantalla de la opción

  4. En el panel Grupos de recursos, seleccione el grupo de recursos existente.

    Captura de pantalla de un grupo de recursos existente en la lista de grupos de recursos de la suscripción.

    Nota:

    En esta captura de pantalla de ejemplo se incluye el msdocs-identity-example grupo de recursos. El nombre real del grupo de recursos podría ser diferente.

  5. En el panel del grupo de recursos, seleccione Control de acceso (IAM) en el menú servicio.

    Captura de pantalla de la opción

  6. En el panel Control de acceso (IAM), seleccione Roles.

    Captura de pantalla de la opción

  7. En la sección Roles , use la frase de búsqueda Cosmos DB y busque la definición del rol Operador de Cosmos DB . A continuación, seleccione la opción Ver asociada a esa definición.

    Captura de pantalla de una lista de definiciones de roles en el ámbito asignable actual filtrado para incluir solo definiciones con

  8. En el cuadro de diálogo de definición de roles del Operador de Cosmos DB, observe las acciones asignadas como parte de esta definición de rol.

    Captura de pantalla del cuadro de diálogo

  9. Cierre el cuadro de diálogo de la definición del rol del operador de Cosmos DB.

  10. De nuevo en el panel Control de acceso (IAM), seleccione Agregar. A continuación, seleccione Agregar rol personalizado.

    Captura de pantalla de la opción

  11. En el panel Aspectos básicos , configure las siguientes opciones y, a continuación, seleccione Siguiente:

    Importancia
    Nombre de rol personalizado Azure Cosmos DB Control Plane Owner
    Descripción Can perform all control plane actions for an Azure Cosmos DB account.
    Permisos de línea base Comienzo desde cero

    Captura de pantalla del panel

  12. En el panel Permisos , seleccione Agregar permisos. A continuación, busque DocumentDB en el cuadro de diálogo permisos. Por último, seleccione la opción Microsoft.DocumentDB .

    Captura de pantalla del panel

    Captura de pantalla del cuadro de diálogo

  13. En el cuadro de diálogo Permisos, seleccione todas las acciones para Microsoft.DocumentDB. A continuación, seleccione Agregar para volver al panel *Permisos .

    Captura de pantalla de todos los permisos seleccionados para

  14. De nuevo en el panel Permisos , observe la lista de permisos. A continuación, seleccione Revisar y crear.

    Captura de pantalla del panel

  15. En el panel Revisar y crear , revise las opciones especificadas para la nueva definición de roles. Por último, seleccione Crear.

    Captura de pantalla del panel

  16. Espere a que el portal termine de crear la definición de roles.

  17. En el panel Control de acceso (IAM), seleccione Agregar y, a continuación, Agregar asignación de roles.

    Captura de pantalla de la opción

  18. En el panel Rol , busque Azure Cosmos DB y seleccione el rol Propietario del plano de control de Azure Cosmos DB creado anteriormente en esta guía. Después, seleccione Siguiente.

    Captura de pantalla del panel

    Sugerencia

    Opcionalmente, puede filtrar la lista de roles para incluir solo roles personalizados.

  19. En el panel Miembros , seleccione la opción Seleccionar miembros . En el cuadro de diálogo miembros, seleccione la identidad que desea conceder a este nivel de acceso para la cuenta de Azure Cosmos DB y, a continuación, use la opción Seleccionar para confirmar su elección.

    Captura de pantalla del panel

    Captura de pantalla del cuadro de diálogo de selección de identidad para agregar una asignación de roles.

    Nota:

    En esta captura de pantalla se ilustra un usuario de ejemplo denominado "Kai Carter" con un principal de kai@adventure-works.com.

  20. De nuevo en el panel Miembros , revise los miembros seleccionados y, a continuación, seleccione Revisar y asignar.

    Captura de pantalla del panel

  21. En el panel Revisar y asignar , revise las opciones especificadas para la nueva asignación de roles. Por último, seleccione Revisar y asignar.

    Captura de pantalla del panel

  22. Espere a que el portal termine de crear la asignación de roles.

  1. Use Get-AzRoleDefinition para enumerar todas las definiciones de roles asociadas a su cuenta de Azure Cosmos DB.

    $parameters = @{
    Name = "Cosmos DB Operator"
}
Get-AzRoleDefinition @parameters

  2. 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 rol en la Id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    Name             : Cosmos DB Operator
Id               : 230815da-be43-4aae-9cb4-875f7bd000aa
IsCustom         : False
Description      : Lets you manage Azure Cosmos DB accounts, but not access data in them. Prevents access to account keys and connection strings.
Actions          : {Microsoft.DocumentDb/databaseAccounts/*, Microsoft.Insights/alertRules/*, Microsoft.Authorization/*/read, Microsoft.ResourceHealth/availabilityStatuses/read…}
NotActions       : {Microsoft.DocumentDB/databaseAccounts/dataTransferJobs/*, Microsoft.DocumentDB/databaseAccounts/readonlyKeys/*, Microsoft.DocumentDB/databaseAccounts/regenerateKey/*, Microsoft.DocumentDB/databaseAccounts/listKeys/*…}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/}

    Nota:

    En este ejemplo, el Id valor sería 230815da-be43-4aae-9cb4-875f7bd000aa. El identificador es único globalmente en todas las definiciones de roles de Azure.

  3. Use Get-AzResourceGroup para obtener los metadatos del grupo de recursos actual.

    $parameters = @{
    Name = "<name-of-existing-resource-group>"
}
Get-AzResourceGroup @parameters

  4. Observe la salida del comando anterior. Registre el valor de la ResourceId propiedad para este grupo de recursos, ya que es necesario usar en el paso siguiente.

    ResourceGroupName : msdocs-identity-example
Location          : westus
ProvisioningState : Succeeded
ResourceId        : /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example

    Nota:

    En este ejemplo, el ResourceId valor sería /subscriptions/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1/resourcegroups/msdocs-identity-example. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo. Esta cadena es un ejemplo truncado de la salida típica.

  5. En primer lugar, importe el Az.Resources módulo. A continuación, cree un nuevo Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition objeto. En el objeto , cree esta definición de recurso especificando los valores enumerados aquí. En la lista AssignableScopes, agregue la propiedad ResourceId del grupo de recursos registrado en el paso anterior. Por último, use el objeto de definición de roles como entrada para el parámetro -Role de New-AzRoleDefinition.

    Import-Module Az.Resources

$parameters = @{
    TypeName = "Microsoft.Azure.Commands.Resources.Models.Authorization.PSRoleDefinition"
    Property = @{
        Name = "Azure Cosmos DB Control Plane Owner"
        Description = "Can perform all control plane actions for an Azure Cosmos DB account."
        IsCustom = $true
        Actions = @(
            "Microsoft.DocumentDb/*"
        )
        AssignableScopes = @(
            "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example"
        )
    }
}
$role = New-Object @parameters

New-AzRoleDefinition -Role $role

    Nota:

    En este ejemplo se usa el /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example valor registrado en el paso anterior. El identificador de recurso real podría ser diferente.

  6. Revise la salida del comando de creación de definiciones. La salida contiene el identificador único de la definición de rol en la Name propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    Name             : Azure Cosmos DB Control Plane Owner
Id               : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5
IsCustom         : True
Description      : Can perform all control plane actions for an Azure Cosmos DB account.
Actions          : {Microsoft.DocumentDb/*}
AssignableScopes : {/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example}

    Nota:

    En este ejemplo, el Name valor sería Azure Cosmos DB Control Plane Owner. Este ejemplo es un subconjunto de la salida típica de la implementación para mayor claridad.

  7. Asigne el nuevo rol mediante New-AzRoleAssignment. Usa el nombre del rol para el RoleDefinitionName parámetro y el identificador único de la identidad para el ObjectId parámetro.

    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    ObjectId = "<your-principal-identifier>"
    RoleDefinitionName = "Azure Cosmos DB Control Plane Owner"
}
New-AzRoleAssignment @parameters

  8. Observe la salida del comando. La salida incluye un identificador único para la asignación en la propiedad RoleAssignmentId.

    RoleAssignmentName : ffffffff-5555-6666-7777-aaaaaaaaaaaa
RoleAssignmentId   : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1
Scope              : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example
DisplayName        : Kai Carter
SignInName         : <kai@adventure-works.com>
RoleDefinitionName : Azure Cosmos DB Control Plane Owner
RoleDefinitionId   : e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5

    Nota:

    En este ejemplo, la RoleAssignmentId propiedad es /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.Authorization/roleAssignments/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1, que es otro ejemplo ficticio. Este ejemplo es un subconjunto de la salida típica de la implementación para mayor claridad.

  9. 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 a los datos mediante una identidad administrada.

Importante

La asignación de una definición de un rol requiere que ya tenga el identificador único de cualquier identidad a la que quiera conceder permisos de control de acceso basado en roles.

Validación del acceso basado en rol del plano de control en el código

Compruebe que ha concedido acceso correctamente mediante el código de aplicación y el SDK de administración de Azure.

using Azure.Identity;
using Azure.ResourceManager;

DefaultAzureCredential credential = new();

ArmClient client = new(credential);

const { CosmosDBManagementClient } = require('@azure/arm-cosmosdb');
const { DefaultAzureCredential } = require('@azure/identity');

const subscriptionId = "<subscription-id>";

const credential = new DefaultAzureCredential();

const client = new CosmosDBManagementClient(credential, subscriptionId);

import { CosmosDBManagementClient } from '@azure/arm-cosmosdb';
import { TokenCredential, DefaultAzureCredential } from '@azure/identity';

let subscriptionId: string = "<subscription-id>";

let credential: TokenCredential = new DefaultAzureCredential();

const client: CosmosDBManagementClient = new CosmosDBManagementClient(credential, subscriptionId);

from azure.mgmt.cosmosdb import CosmosDBManagementClient
from azure.identity import DefaultAzureCredential

subscription_id = "<subscription-id>"

credential = DefaultAzureCredential()

client = CosmosDBManagementClient(credential=credential, subscription=subscription_id)

package main

import (
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos"
)

const subscriptionId = "<subscription-id>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    
    client, _ := armcosmos.NewDatabaseClient(subscriptionId, credential, nil)
}

package com.example;

import com.azure.core.management.profile.AzureProfile;
import com.azure.core.management.AzureEnvironment;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.resourcemanager.cosmos.CosmosManager;

public class CosmosDB {
    public static void main(String[] args) {
        AzureProfile profile = new AzureProfile(AzureEnvironment.AZURE);
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
          .build();

        CosmosManager manager = CosmosManager.authenticate(credential, profile);
    }
}

Concesión de acceso basado en roles del plano de datos

El acceso al plano de datos hace referencia a la capacidad de leer y escribir datos dentro de un servicio de Azure sin la capacidad de administrar los recursos de la cuenta. Por ejemplo, el acceso al plano de datos de Azure Cosmos DB podría incluir la capacidad de:

  • Leer algunos metadatos de cuenta y recursos
  • Creación, lectura, actualización, revisión y eliminación de elementos
  • Ejecución de consultas NoSQL
  • Leer desde la fuente de cambios de un contenedor
  • Ejecución de procedimientos almacenados
  • Administrar conflictos en la fuente de conflictos

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. En esta guía, vas a preparar un rol personalizado. A continuación, 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

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

La creación de una nueva definición de rol del plano de datos requiere estos permisos de plano de control:

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

La creación de una nueva asignación de roles del 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

Advertencia

El control de acceso nativo basado en rol de Azure Cosmos DB para NoSQL no admite la notDataActions propiedad . Todas las acciones que no se especifican como permitidas dataAction se excluyen automáticamente.

  1. Enumere todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB para NoSQL mediante az cosmosdb sql role definition list.

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

  2. Cree un nuevo archivo JSON denominado role-definition.json, que se usa para la creación del rol personalizado. En este archivo, cree una definición de recurso que especifique las acciones de datos que se enumeran aquí:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Puede leer metadatos de nivel de cuenta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Puede realizar cualquier operación de datos de nivel de contenedor.
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Puede realizar cualquier operación en elementos con contenedores 
    {
  "RoleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "Type": "CustomRole",
  "AssignableScopes": [
    "/"
  ],
  "Permissions": [
    {
      "DataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ]
    }
  ]
}

  3. A continuación, use az cosmosdb sql role definition create para crear la definición de roles. Use el role-definition.json como entrada para el --body argumento .

    az cosmosdb sql role definition create \
    --resource-group "<name-of-existing-resource-group>" \
    --account-name "<name-of-existing-nosql-account>" \
    --body "@role-definition.json"

  4. Revise la salida del comando anterior. Busque la definición de rol que acaba de crear con el nombre Azure Cosmos DB para el propietario del plano de datos NOSQL. La salida contiene el identificador único de la definición de rol en la id propiedad . Registre este valor como se requiere para usarlo en el paso de asignación más adelante en esta guía como --role-definition-id

    {
  "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/bbbbbbbb-1111-2222-3333-cccccccccccc",
  "name": "bbbbbbbb-1111-2222-3333-cccccccccccc",
  "permissions": [
    {
      "dataActions": [
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
      ],
      "notDataActions": []
    }
  ],
  "resourceGroup": "msdocs-identity-example",
  "roleName": "Azure Cosmos DB for NoSQL Data Plane Owner",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions",
  "typePropertiesType": "CustomRole"
}

    Nota:

    En este ejemplo, el --role-definition-id valor sería bbbbbbbb-1111-2222-3333-cccccccccccc. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

  5. Use el id obtenido en el paso anterior y determine el --scope quitando todo después del nombre de la cuenta.

    Nota:

    En este ejemplo, el --scope valor 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.

  6. Asigne el nuevo rol mediante az cosmosdb sql role assignment create.
    Use los identificadores de definición de roles previamente registrados para el argumento --role-definition-id, el identificador único de su identidad para el argumento --principal-id, y finalmente, use el identificador de su 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"

    Sugerencia

    Si está intentando conceder el control de acceso basado en rol del plano de datos a su propia identidad, puede usar este comando para obtener la identidad:

    az ad signed-in-user show

    Para obtener más información, consulte az ad signed-in-user.

    Sugerencia

    En la implementación nativa de Azure Cosmos DB del control de acceso basado en rol, el ámbito hace referencia a la granularidad de los recursos dentro de una cuenta para la que desea aplicar el permiso. En el nivel más alto, puede definir el ámbito de una asignación de control de acceso basado en roles del plano de datos a toda la cuenta mediante el ámbito más grande. Este ámbito incluye todas las bases de datos y contenedores dentro de la cuenta:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

    O bien, puede definir el ámbito de la asignación de roles del plano de datos a una base de datos específica:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

    Por último, puede definir el ámbito de la asignación a un único contenedor, el ámbito más granular:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

    En muchos casos, puede usar el ámbito relativo en lugar del ámbito completamente calificado. Por ejemplo, puede usar este ámbito relativo para conceder permisos de control de acceso basado en rol del plano de datos a una base de datos y un contenedor específicos desde un comando de la CLI de Azure:

    /dbs/<database-name>/colls/<container-name>

    También puede conceder acceso universal a todas las bases de datos y contenedores mediante el ámbito relativo:

    /

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

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

  2. 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 rol en la id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    [
  ...,
  {
    "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:

    En este ejemplo, el id valor 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.

  3. Cree un nuevo archivo de Bicep para definir tu rol. Asigne al archivo el nombre data-plane-role-definition.bicep. Agregue estos elementos dataActions a la definición:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Puede leer metadatos de nivel de cuenta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Puede realizar cualquier operación de datos de nivel de contenedor.
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Puede realizar cualquier operación en elementos con contenedores 
    metadata description = 'Create RBAC definition for data plane access to Azure Cosmos DB for NoSQL.'

@description('Name of the Azure Cosmos DB for NoSQL account.')
param accountName string

@description('Name of the role definition.')
param roleDefinitionName string = 'Azure Cosmos DB for NoSQL Data Plane Owner'

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-05-15' existing = {
  name: accountName
}

resource definition 'Microsoft.DocumentDB/databaseAccounts/sqlRoleDefinitions@2024-05-15' = {
  name: guid(account.id, roleDefinitionName)
  parent: account
  properties: {
    roleName: roleDefinitionName
    type: 'CustomRole'
    assignableScopes: [
      account.id
    ]
    permissions: [
      {
        dataActions: [
          'Microsoft.DocumentDB/databaseAccounts/readMetadata'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*'
          'Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*'
        ]
      }
    ]
  }
}

output definitionId string = definition.id

    Sugerencia

    En la implementación nativa de Azure Cosmos DB del control de acceso basado en rol, el ámbito hace referencia a la granularidad de los recursos dentro de una cuenta para la que desea aplicar el permiso. En el nivel más alto, puede definir el ámbito de una asignación de control de acceso basado en roles del plano de datos a toda la cuenta mediante el ámbito más grande. Este ámbito incluye todas las bases de datos y contenedores dentro de la cuenta:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

    O bien, puede definir el ámbito de la asignación de roles del plano de datos a una base de datos específica:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

    Por último, puede definir el ámbito de la asignación a un único contenedor, el ámbito más granular:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

    En muchos casos, puede usar el ámbito relativo en lugar del ámbito completamente calificado. Por ejemplo, puede usar este ámbito relativo para conceder permisos de control de acceso basado en rol del plano de datos a una base de datos y un contenedor específicos desde un comando de la CLI de Azure:

    /dbs/<database-name>/colls/<container-name>

    También puede conceder acceso universal a todas las bases de datos y contenedores mediante el ámbito relativo:

    /

  4. Cree un nuevo archivo de parámetros de Bicep denominado data-plane-role-definition.bicepparam. En este archivo de parámetros, asigne el nombre de la cuenta de Azure Cosmos DB para NoSQL existente al accountName parámetro .

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

param accountName = '<name-of-existing-nosql-account>'

  5. Implemente la plantilla de Bicep usando az deployment group create.

    az deployment group create \
    --resource-group "<name-of-existing-resource-group>" \
    --parameters data-plane-role-definition.bicepparam \
    --template-file data-plane-role-definition.bicep

  6. 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 = deployer().objectId

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

  7. Cree un nuevo archivo de parámetros de Bicep denominado data-plane-role-assignmentbicepparam. En este archivo de parámetros, asigne el nombre de la cuenta de Azure Cosmos DB para NoSQL existente al accountName parámetro , los identificadores de definición de roles registrados anteriormente al roleDefinitionId parámetro y el identificador único de la identidad al 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>'

    Sugerencia

    Si está intentando conceder el control de acceso basado en rol del plano de datos a su propia identidad, puede omitir el parámetro identityId. A continuación, la plantilla de Bicep usa deployer().objectId para obtener la identidad del principal que implementó la plantilla. Para obtener más información, consulte deployer.

  8. Implemente la plantilla de 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

  9. 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. También puede repetir estos pasos para permitir que las aplicaciones accedan a los recursos mediante una identidad administrada.

  1. Use Get-AzCosmosDBSqlRoleDefinition para enumerar todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB para NoSQL.

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

  2. 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 rol en la Id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    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:

    En este ejemplo, el Id valor 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.

  3. Cree una nueva definición de roles mediante New-AzCosmosDBSqlRoleDefinition. Para el DataAction parámetro , especifique las acciones de datos que se enumeran aquí:

    Description
    Microsoft.DocumentDB/databaseAccounts/readMetadata Puede leer metadatos de nivel de cuenta
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/* Puede realizar cualquier operación de datos de nivel de contenedor.
    Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/* Puede realizar cualquier operación en elementos con contenedores 
    $parameters = @{
    ResourceGroupName = "<name-of-existing-resource-group>"
    AccountName = "<name-of-existing-nosql-account>"
    RoleName = "Azure Cosmos DB for NoSQL Data Plane Owner"
    Type = "CustomRole"
    AssignableScope = @(
        "/"
    )
    DataAction = @(
        "Microsoft.DocumentDB/databaseAccounts/readMetadata",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*",
        "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*"
    )
}
New-AzCosmosDBSqlRoleDefinition @parameters

    Sugerencia

    En la implementación nativa de Azure Cosmos DB del control de acceso basado en rol, el ámbito hace referencia a la granularidad de los recursos dentro de una cuenta para la que desea aplicar el permiso. En el nivel más alto, puede definir el ámbito de una asignación de control de acceso basado en roles del plano de datos a toda la cuenta mediante el ámbito más grande. Este ámbito incluye todas las bases de datos y contenedores dentro de la cuenta:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/

    O bien, puede definir el ámbito de la asignación de roles del plano de datos a una base de datos específica:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>

    Por último, puede definir el ámbito de la asignación a un único contenedor, el ámbito más granular:

    /subscriptions/<subscription-id>/resourcegroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<account-name>/dbs/<database-name>/colls/<container-name>

    En muchos casos, puede usar el ámbito relativo en lugar del ámbito completamente calificado. Por ejemplo, puede usar este ámbito relativo para conceder permisos de control de acceso basado en rol del plano de datos a una base de datos y un contenedor específicos desde un comando de la CLI de Azure:

    /dbs/<database-name>/colls/<container-name>

    También puede conceder acceso universal a todas las bases de datos y contenedores mediante el ámbito relativo:

    /

  4. Use Get-AzCosmosDBSqlRoleDefinition para enumerar todas las definiciones de roles asociadas a la cuenta de Azure Cosmos DB para NoSQL.

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

  5. Revise la salida del comando anterior. Busque la definición de rol que acaba de crear con el nombre Azure Cosmos DB para el propietario del plano de datos NOSQL. La salida contiene el identificador único de la definición de rol en la Id propiedad . Registre este valor como es necesario para usarlo en el paso de asignación más adelante en esta guía.

    Id                         : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc
RoleName                   : Azure Cosmos DB for NoSQL Data Plane Owner
Type                       : CustomRole
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/sqlDatabases/containers/items/*, Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*}
Permissions.NotDataActions :

    Nota:

    En este ejemplo, el Id valor sería /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/msdocs-identity-example/providers/Microsoft.DocumentDB/databaseAccounts/msdocs-identity-example-nosql/sqlRoleDefinitions/bbbbbbbb-1111-2222-3333-cccccccccccc. En este ejemplo se usan datos ficticios y el identificador sería distinto de este ejemplo.

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

  7. Observe la salida del comando anterior. Registre el valor de la Id propiedad 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:

    En este ejemplo, el Id valor 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.

  8. Use New-AzCosmosDBSqlRoleAssignment para asignar el nuevo rol. Utiliza los identificadores de definición de roles registrados anteriormente en el parámetro RoleDefinitionId y el identificador único para su 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

    Sugerencia

    Si está intentando conceder el control de acceso basado en rol del plano de datos a su propia identidad, puede usar este comando para obtener la identidad:

    Get-AzADUser -SignedIn | Format-List `
    -Property Id, DisplayName, Mail, UserPrincipalName

    Para obtener más información, consulte Get-AzADUser.

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

Advertencia

La administración del control de acceso basado en roles del plano de datos no se admite en el portal de Azure.

Validación de acceso basado en roles en el plano de datos dentro del código

Compruebe que ha concedido acceso correctamente mediante el código de aplicación y el SDK de Azure.

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<account-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential);

Container container = client.GetContainer("<database-name>", "<container-name>");

await container.ReadItemAsync<dynamic>("<item-id>", new PartitionKey("<partition-key>"));

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<account-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential});

const container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

import { Container, CosmosClient, CosmosClientOptions } from '@azure/cosmos'
import { TokenCredential, DefaultAzureCredential } from '@azure/identity'

let endpoint: string = '<account-endpoint>';

let credential: TokenCredential = new DefaultAzureCredential();

let options: CosmosClientOptions = {
  endpoint: endpoint,
  aadCredentials: credential
};

const client: CosmosClient = new CosmosClient(options);

const container: Container = client.database('<database-name>').container('<container-name>');

await container.item('<item-id>', '<partition-key>').read<String>();

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<account-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

container = client.get_database_client("<database-name>").get_container_client("<container-name>")

container.read_item(
    item="<item-id>",
    partition_key="<partition-key>",
)

import (
    "context"
    
    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
    "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos"
)

const endpoint = "<account-endpoint>"

func main() {
    credential, _ := azidentity.NewDefaultAzureCredential(nil)
    client, _ := azcosmos.NewClient(endpoint, credential, nil)
    
    database, _ := client.NewDatabase("<database-name>")
    container, _ := database.NewContainer("<container-name>")
    
    _, err := container.ReadItem(context.TODO(), azcosmos.NewPartitionKeyString("<partition-key>"), "<item-id>", nil)
    if err != nil {
        panic(err)
    }
}

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.PartitionKey;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL {
    public static void main(String[] args) {   
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
            
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<account-endpoint>")
            .credential(credential)
            .buildClient();

        CosmosContainer container = client.getDatabase("<database-name>").getContainer("<container-name>");

        container.readItem("<item-id>", new PartitionKey("<partition-key>"), Object.class);
    }
}

use azure_data_cosmos::CosmosClient;
use azure_identity::DefaultAzureCredential;

fn main() {
    let credential = DefaultAzureCredential::new().unwrap();
    let client = CosmosClient::new("<account-endpoint>", credential, None).unwrap();

    let container = client.database_client("<database-name>").container_client("<container-name>");

    let response = container.read_item("<partition-key>", "<item-id>", None);
    tokio::runtime::Runtime::new().unwrap().block_on(response).unwrap();
}

Contenido relacionado

  • Last updated on