Como usar identidades gerenciadas para se conectar ao Azure Cosmos DB a partir de uma máquina virtual do Azure

  • Artigo

Atenção

Este artigo faz referência ao CentOS, uma distribuição Linux que está se aproximando do status de Fim da Vida Útil (EOL). Por favor, considere o seu uso e planeje de acordo. Para obter mais informações, consulte as diretrizes de Fim da Vida Útil do CentOS.

Neste artigo, configuramos uma máquina virtual para usar identidades gerenciadas para se conectar ao Azure Cosmos DB. O Azure Cosmos DB é um banco de dados NoSQL totalmente gerenciado para desenvolvimento de aplicativos modernos. As identidades gerenciadas para recursos do Azure permitem que seus aplicativos se autentiquem ao acessar serviços que dão suporte à autenticação do Microsoft Entra usando uma identidade gerenciada pelo Azure.

Pré-requisitos

Criar um grupo de recursos

Crie um grupo de recursos chamado mi-test. Usamos esse grupo de recursos para todos os recursos usados neste tutorial.

Criar uma VM do Azure com uma identidade gerenciada

Para este tutorial, você precisa de uma máquina virtual (VM) do Azure. Crie uma máquina virtual com uma identidade gerenciada atribuída ao sistema habilitada chamada mi-vm-01. Você também pode criar uma identidade gerenciada atribuída pelo usuário chamada mi-ua-01 no grupo de recursos que criamos anteriormente (mi-test). Se você usar uma identidade gerenciada atribuída pelo usuário, poderá atribuí-la a uma VM durante a criação.

Criar uma VM com uma identidade gerenciada atribuída ao sistema

Para criar uma VM do Azure com a identidade gerenciada atribuída ao sistema habilitada, sua conta precisa da atribuição de função de Colaborador de Máquina Virtual . Nenhuma outra atribuição de função do Microsoft Entra é necessária.

  • No portal do Azure, procure máquinas virtuais.
  • Selecione Criar
  • Na guia Noções básicas, forneça as informações necessárias.
  • Escolha Next: Discos >
  • Continue preenchendo as informações conforme necessário e, na guia Gerenciamento, localize a seção Identidade e marque a caixa ao lado de Identidade gerenciada atribuída ao sistema

Imagem mostrando como habilitar identidades gerenciadas atribuídas ao sistema ao criar uma VM.

Para obter mais informações, consulte a documentação das máquinas virtuais do Azure:

Criar uma VM com uma identidade gerenciada atribuída pelo usuário

As etapas abaixo mostram como criar uma máquina virtual com uma identidade gerenciada atribuída pelo usuário configurada.

Atualmente, o portal do Azure não oferece suporte à atribuição de uma identidade gerenciada atribuída pelo usuário durante a criação de uma VM. Você deve criar uma máquina virtual e, em seguida, atribuir um usuário atribuído identidade gerenciada a ela.

Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do Azure

Criar uma conta do Azure Cosmos DB

Agora que temos uma VM com uma identidade gerenciada atribuída pelo usuário ou uma identidade gerenciada atribuída pelo sistema, precisamos de uma conta do Azure Cosmos DB disponível onde você tenha direitos administrativos. Se você precisar criar uma conta do Azure Cosmos DB para este tutorial, o início rápido do Azure Cosmos DB fornece etapas detalhadas sobre como fazer isso.

Nota

As identidades gerenciadas podem ser usadas para acessar qualquer recurso do Azure que ofereça suporte à autenticação do Microsoft Entra. Este tutorial pressupõe que sua conta do Azure Cosmos DB será configurada conforme mostrado abaixo.

Definição valor Description
Subscrição Nome da subscrição Selecione a subscrição do Azure que pretende utilizar para esta conta do Azure Cosmos DB.
Grupo de Recursos Nome do grupo de recursos Selecione mi-test ou Create new (Criar novo) e insira um nome exclusivo para o novo grupo de recursos.
Nome da Conta Um nome exclusivo Insira um nome para identificar sua conta do Azure Cosmos DB. Uma vez que documents.azure.com é anexado ao nome que indicar para criar o URI, utilize um nome exclusivo.

O nome só pode conter letras minúsculas, números e o caráter de hífen (-). Deve ter entre 3 e 44 caracteres de comprimento.
API O tipo de conta a criar Selecione Azure Cosmos DB para NoSQL para criar um banco de dados de documentos e consultar usando a sintaxe SQL.

Saiba mais sobre a API SQL.
Location A região mais próxima dos seus utilizadores Selecione a localização geográfica para alojar a sua conta do Azure Cosmos DB. Utilize a localização mais próxima dos utilizadores para lhes dar o acesso mais rápido aos dados.

Nota

Se você estiver testando, talvez queira aplicar o desconto de camada gratuita do Azure Cosmos DB. Com o nível gratuito do Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente em uma conta. Saiba mais sobre o nível gratuito. Tenha em mente que, para o propósito deste tutorial, essa escolha não faz diferença.

Conceder acesso

Neste ponto, devemos ter uma máquina virtual configurada com uma identidade gerenciada e uma conta do Azure Cosmos DB. Antes de continuarmos, precisamos conceder à identidade gerenciada algumas funções diferentes.

  • Primeiro, conceda acesso ao plano de gerenciamento do Azure Cosmos DB usando o Azure RBAC. A identidade gerenciada precisa ter a função de Colaborador da Conta do Banco de Dados de Documentos atribuída para criar bancos de dados e contêineres.

  • Você também precisa conceder à identidade gerenciada uma função de colaborador usando o Azure Cosmos DB RBAC. Você pode ver etapas específicas abaixo.

Nota

Usaremos a função de contribuidor de dados internos do Cosmos DB. Para conceder acesso, você precisa associar a definição de função à identidade. No nosso caso, a identidade gerenciada associada à nossa máquina virtual.

No momento, não há nenhuma opção de atribuição de função disponível no portal do Azure

Aceder a dados

Obter acesso ao Azure Cosmos DB usando identidades gerenciadas pode ser obtido usando a biblioteca Azure.identity para habilitar a autenticação em seu aplicativo. Você pode chamar ManagedIdentityCredential diretamente ou usar DefaultAzureCredential.

A classe ManagedIdentityCredential tenta autenticar usando uma identidade gerenciada atribuída ao ambiente de implantação. A classe DefaultAzureCredential passa por diferentes opções de autenticação na ordem. A segunda opção de autenticação que DefaultAzureCredential tenta é Identidades gerenciadas.

No exemplo mostrado abaixo, você cria um banco de dados, um contêiner, um item no contêiner e lê de volta o item recém-criado usando a identidade gerenciada atribuída ao sistema da máquina virtual. Se você quiser usar uma identidade gerenciada atribuída pelo usuário, precisará especificar a identidade gerenciada atribuída pelo usuário especificando a ID do cliente da identidade gerenciada.

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

Para usar o exemplo abaixo, você precisa ter os seguintes pacotes NuGet:

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

Além dos pacotes NuGet acima, você também precisa habilitar Incluir pré-lançamento e adicionar 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();
        }
    }
}

Exemplos específicos do idioma usando ManagedIdentityCredential:

.NET

Inicialize seu cliente do Azure Cosmos DB:

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

Em seguida, leia e grave dados.

Java

Inicialize seu cliente do Azure Cosmos DB:

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

Em seguida, leia e grave os dados conforme descrito nestes exemplos

JavaScript

Inicialize seu cliente do Azure Cosmos DB:

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

Em seguida, leia e grave os dados conforme descrito nestes exemplos

Etapas de limpeza

Gorjeta

As etapas neste artigo podem variar ligeiramente com base no portal a partir do qual você começou.

  1. Inicie sessão no portal do Azure.

  2. Selecione o recurso que deseja excluir.

  3. Selecione Eliminar.

  4. Quando lhe for perguntado, confirme a eliminação.

Próximos passos

Saiba mais sobre identidades gerenciadas para recursos do Azure:

Saiba mais sobre o Azure Cosmos DB: