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

En este artículo, se configura una máquina virtual para usar identidades administradas para conectarse a Cosmos. 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 Azure AD mediante una identidad administrada por Azure.

Prerrequisitos

  • 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. Usaremos este grupo de recursos con todos los recursos que se usarán 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 es necesaria ninguna otra asignación de roles de Azure AD.

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

Image showing how to enable system assigned managed identities while creating a VM.

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 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 Cosmos DB disponible donde tenga derechos administrativos. Si necesita crear una cuenta de Cosmos DB para este tutorial, consulte el inicio rápido de Cosmos DB para obtener 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 Azure Active Directory. En este tutorial se da por supuesto que la cuenta de Cosmos DB tendrá la siguiente configuración.

Configuración Value Descripción
Suscripción Nombre de suscripción Seleccione la suscripción de Azure que desea usar para esta cuenta de Azure Cosmos.
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. 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 Core(SQL) para crear una base de datos de documentos y consultarla 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 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 Cosmos 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 Cosmos. 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 Cosmos 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)
        {
            var subscriptionId = "Your subscription ID";
            var resourceGroupName = "You resource group";
            var accountName = "Cosmos DB Account name";
            var databaseName = "mi-test";
            var containerName = "container01";

            var tokenCredential = new DefaultAzureCredential();

            // create the management clientSS
            var managementClient = new CosmosDBManagementClient(subscriptionId, tokenCredential);

            // create the data client
            var dataClient = new CosmosClient("https://[Account].documents.azure.com:443/", tokenCredential);

            // create a new database 
            var createDatabaseOperation = await managementClient.SqlResources.StartCreateUpdateSqlDatabaseAsync(resourceGroupName, accountName, databaseName,
                new SqlDatabaseCreateUpdateParameters(new SqlDatabaseResource(databaseName), new CreateUpdateOptions()));
            await createDatabaseOperation.WaitForCompletionAsync();

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


            // create a new item 
            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
            var pointReadResult = await dataClient.GetContainer(databaseName, containerName)
                .ReadItemAsync<dynamic>(id, new PartitionKey(partitionKey));


            // run a query
            await dataClient.GetContainer(databaseName, containerName)
                .GetItemQueryIterator<dynamic>("SELECT * FROM c")
                .ReadNextAsync();
        }
    }
}

Ejemplos específicos del lenguaje mediante ManagedIdentityCredential:

.NET

Inicialice el cliente de Cosmos DB:

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

A continuación, lea y escriba los datos.

Java

Inicialice el cliente de 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 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

  1. En el portal, seleccione el recurso que quiere eliminar.

  2. Seleccione Eliminar.

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

Pasos siguientes

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

Más información sobre Azure Cosmos