Uso de identidades administradas para conectarse a Azure Cosmos DB desde una máquina virtual de Azure

  • Artículo

Precaución

En este artículo se hace referencia a CentOS, una distribución de Linux que está cerca de su estado Final de ciclo vida (EOL). Tenga en cuenta su uso y planifique en consecuencia. Para obtener más información, consulte la Guía de fin de ciclo de vida de CentOS.

En este artículo, se configura una máquina virtual para usar identidades administradas para conectarse a Azure Cosmos DB. Azure Cosmos DB es una base de datos NoSQL totalmente administrada para el desarrollo de aplicaciones modernas. Las identidades administradas para recursos de Azure permiten que las aplicaciones se autentiquen al acceder a servicios que admiten la autenticación de Microsoft Entra mediante una identidad administrada por Azure.

Requisitos previos

  • Conocimientos básicos sobre identidades administradas. Si desea obtener más información sobre las identidades administradas para los recursos de Azure antes de continuar, revise la introducción a las identidades administradas.
  • Debe disponer de una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
  • Puede que necesite PowerShell o la CLI.
  • Visual Studio Community Edition o algún otro entorno de desarrollo de su elección.

Crear un grupo de recursos

Cree un nuevo grupo de recursos denominado mi-test. Utilizamos este grupo de recursos para todos los recursos utilizados en este tutorial.

Creación de una máquina virtual de Azure con una identidad administrada

Para este tutorial, necesita una máquina virtual de Azure. Cree un conjunto de escalado de máquinas virtuales con una identidad administrada asignada por el sistema habilitada denominada mi-vm-01. También puede crear una identidad administrada asignada por el usuario denominada mi-ua-01 en el grupo de recursos que creamos anteriormente (mi-test). Si usa una identidad administrada asignada por el usuario, puede asignarla a una máquina virtual durante la creación.

Creación de una máquina virtual con una identidad administrada asignada por el sistema

Para crear una máquina virtual de Azure que tenga habilitada la identidad administrada asignada por el sistema, la cuenta debe tener la asignación de roles Colaborador de la máquina Virtual. No se requiere ninguna otra asignación de roles de Microsoft Entra.

  • En Azure Portal, busque máquinas virtuales.
  • Elija Crear.
  • En la pestaña Aspectos básicos, proporcione la información necesaria.
  • Elija Siguiente: Discos >.
  • Rellene la información según sea necesario y, en la pestaña Administración, busque la sección Identidad y active la casilla situada junto a Identidad administrada asignada por el sistema.

Imagen que muestra cómo habilitar identidades administradas asignadas por el sistema al crear una máquina virtual.

Para más información, consulte la documentación sobre máquinas virtuales de Azure:

Creación de una máquina virtual con una identidad administrada asignada por el usuario

En los pasos siguientes se muestra cómo crear una máquina virtual con una identidad administrada asignada por el usuario configurada.

En la actualidad, Azure Portal no permite asignar una identidad administrada asignada por el usuario durante el proceso de creación de una VM. Debe crear una máquina virtual y, a continuación, asignarle una identidad administrada asignada por el usuario.

Configurar identidades administradas para recursos de Azure en una VM mediante Azure Portal

Creación de una cuenta de Azure Cosmos DB

Ahora que tenemos una máquina virtual con una identidad administrada asignada por el usuario o por el sistema, necesitamos una cuenta de Azure Cosmos DB disponible donde tenga derechos administrativos. Si necesita crear una cuenta de Azure Cosmos DB para este tutorial, el inicio rápido de Azure Cosmos DB proporciona pasos detallados sobre cómo hacerlo.

Nota:

Las identidades administradas se pueden usar para acceder a cualquier recurso de Azure que admita la autenticación de Microsoft Entra. En este tutorial se da por supuesto que la cuenta de Azure Cosmos DB tendrá la siguiente configuración.

Configuración valor Descripción
Subscription Nombre de suscripción Seleccione la suscripción de Azure que quiere usar para esta cuenta de Azure Cosmos DB.
Grupo de recursos Definición de un nombre de grupo de recursos Seleccione mi-test o seleccione Crear nuevo y escriba un nombre único para el grupo de recursos nuevo.
Nombre de cuenta Un nombre único Escriba un nombre para identificar la cuenta de Azure Cosmos DB. Dado que documents.azure.com se anexa al nombre que se proporciona para crear el identificador URI, debe usar un nombre único.

El nombre solo puede contener letras minúsculas, números y el carácter de guion (-). Debe tener una longitud de entre 3 y 44 caracteres.
API El tipo de cuenta que se va a crear Seleccione Azure Cosmos DB for NoSQL para crear una base de datos de documentos y una consulta mediante la sintaxis SQL.

Más información acerca de SQL API.
Location Región más cercana a los usuarios Seleccione una ubicación geográfica para hospedar la cuenta de Azure Cosmos DB. Use la ubicación más cercana a los usuarios para que puedan acceder de la forma más rápida posible a los datos.

Nota:

Si va a realizar pruebas, puede que desee aplicar el descuento por nivel Gratis de Azure Cosmos DB. Con el nivel Gratis de Azure Cosmos DB, recibirá los primeros 1000 RU/s y 25 GB de almacenamiento gratis en una cuenta. Más información acerca del nivel Gratis. Tenga en cuenta que, para este tutorial, esta opción no supone ninguna diferencia.

Conceder acceso

En este punto, deberíamos tener una máquina virtual configurada con una identidad administrada y una cuenta de Azure Cosmos DB. Antes de continuar, es necesario conceder a la identidad administrada un par de roles diferentes.

  • En primer lugar, conceda acceso al plano de administración de Azure Cosmos DB mediante RBAC de Azure. La identidad administrada debe tener asignado el rol Colaborador de cuenta de DocumentDB para crear bases de datos y contenedores.

  • También debe conceder a la identidad administrada un rol de colaborador mediante RBAC de Azure Cosmos DB. Puede ver los pasos concretos a continuación.

Nota:

Usaremos el rol Colaborador de datos integrado de Cosmos DB. Para conceder acceso, debe asociar la definición de rol a la identidad. En nuestro caso, la identidad administrada asociada a nuestra máquina virtual.

En este momento no hay ninguna opción de asignación de roles disponible en Azure Portal

Acceso a los datos

El acceso a Azure Cosmos DB mediante identidades administradas se puede lograr mediante la biblioteca Azure.identity para habilitar la autenticación en la aplicación. Puede llamar directamente a ManagedIdentityCredential o usar DefaultAzureCredential.

La clase ManagedIdentityCredential intenta realizar la autenticación mediante una identidad administrada asignada al entorno de implementación. La clase DefaultAzureCredential pasa por diferentes opciones de autenticación en orden. La segunda opción de autenticación que DefaultAzureCredential intenta son las identidades administradas.

En el ejemplo que se muestra a continuación, se muestra la creación de una base de datos, un contenedor, un elemento en ese contenedor y, además, la lectura del elemento recién creado mediante la identidad administrada asignada por el sistema de la VM. Si desea usar una identidad administrada asignada por el usuario, debe especificarla mediante el identificador de cliente de la identidad administrada.

string userAssignedClientId = "<your managed identity client Id>";
var tokenCredential = new DefaultAzureCredential(new DefaultAzureCredentialOptions { ManagedIdentityClientId = userAssignedClientId });

Para usar el ejemplo siguiente, debe tener los siguientes paquetes NuGet:

  • Azure.Identity
  • Microsoft.Azure.Cosmos
  • Microsoft.Azure.Management.CosmosDB

Además de los paquetes NuGet anteriores, también debe habilitar Incluir versión preliminar y, después, agregar Azure.ResourceManager.CosmosDB.

using Azure.Identity;
using Azure.ResourceManager.CosmosDB;
using Azure.ResourceManager.CosmosDB.Models;
using Microsoft.Azure.Cosmos;
using System;
using System.Threading.Tasks;

namespace MITest
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // Replace the placeholders with your own values
            var subscriptionId = "Your subscription ID";
            var resourceGroupName = "You resource group";
            var accountName = "Cosmos DB Account name";
            var databaseName = "mi-test";
            var containerName = "container01";

            // Authenticate to Azure using Managed Identity (system-assigned or user-assigned)
            var tokenCredential = new DefaultAzureCredential();

            // Create the Cosmos DB management client using the subscription ID and token credential
            var managementClient = new CosmosDBManagementClient(tokenCredential)
            {
                SubscriptionId = subscriptionId
            };

            // Create the Cosmos DB data client using the account URL and token credential
            var dataClient = new CosmosClient($"https://{accountName}.documents.azure.com:443/", tokenCredential);

            // Create a new database using the management client
            var createDatabaseOperation = await managementClient.SqlResources.StartCreateUpdateSqlDatabaseAsync(
                resourceGroupName,
                accountName,
                databaseName,
                new SqlDatabaseCreateUpdateParameters(new SqlDatabaseResource(databaseName), new CreateUpdateOptions()));
            await createDatabaseOperation.WaitForCompletionAsync();

            // Create a new container using the management client
            var createContainerOperation = await managementClient.SqlResources.StartCreateUpdateSqlContainerAsync(
                resourceGroupName,
                accountName,
                databaseName,
                containerName,
                new SqlContainerCreateUpdateParameters(new SqlContainerResource(containerName), new CreateUpdateOptions()));
            await createContainerOperation.WaitForCompletionAsync();

            // Create a new item in the container using the data client
            var partitionKey = "pkey";
            var id = Guid.NewGuid().ToString();
            await dataClient.GetContainer(databaseName, containerName)
                .CreateItemAsync(new { id = id, _partitionKey = partitionKey }, new PartitionKey(partitionKey));

            // Read back the item from the container using the data client
            var pointReadResult = await dataClient.GetContainer(databaseName, containerName)
                .ReadItemAsync<dynamic>(id, new PartitionKey(partitionKey));

            // Run a query to get all items from the container using the data client
            await dataClient.GetContainer(databaseName, containerName)
                .GetItemQueryIterator<dynamic>("SELECT * FROM c")
                .ReadNextAsync();
        }
    }
}

Ejemplos específicos del lenguaje mediante ManagedIdentityCredential:

.NET

Inicialice el cliente de Azure Cosmos DB:

CosmosClient client = new CosmosClient("<account-endpoint>", new ManagedIdentityCredential());

A continuación, lea y escriba los datos.

Java

Inicialice el cliente de Azure Cosmos DB:

CosmosAsyncClient Client = new CosmosClientBuilder().endpoint("<account-endpoint>") .credential(new ManagedIdentityCredential()) .build();

A continuación, lea y escriba los datos como se indica en estos ejemplos.

JavaScript

Inicialice el cliente de Azure Cosmos DB:

const client = new CosmosClient({ "<account-endpoint>", aadCredentials: new ManagedIdentityCredential() });

A continuación, lea y escriba los datos como se indica en estos ejemplos.

Pasos de limpieza

Sugerencia

Los pasos de este artículo pueden variar ligeramente en función del portal desde donde comienza.

  1. Inicie sesión en Azure Portal.

  2. Seleccione el recurso que desea eliminar.

  3. Seleccione Eliminar.

  4. Cuando se le solicite, confirme la eliminación.

Pasos siguientes

Obtenga más información sobre las identidades administradas para recursos de Azure:

Obtenga más información sobre Azure Cosmos DB: