Compartilhar via

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

  • Artigo

Neste artigo, vamos configurar uma máquina virtual para usar identidades gerenciadas a fim de nos conectarmos ao Azure Cosmos DB. O Azure Cosmos DB é um banco de dados NoSQL totalmente gerenciado para o 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. Usaremos 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 VM (máquina virtual) do Azure. Crie uma máquina virtual com uma identidade gerenciada atribuída pelo sistema chamada mi-vm-01 habilitada. 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ê usa uma identidade gerenciada atribuída pelo usuário, pode atribuí-la a uma VM durante a criação.

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

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

  • No portal do Azure, pesquise por máquinas virtuais.
  • Escolha Criar
  • Na guia Básico, forneça as informações necessárias.
  • Escolha Avançar: Discos >
  • Continue preenchendo as informações conforme necessário e, na guia Gerenciamento, encontre a seção Identidade e marque a caixa ao lado de Identidade gerenciada atribuída pelo sistema

Imagem mostrando como habilitar identidades gerenciadas atribuídas pelo sistema durante a criação de uma VM.

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

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

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

Hoje em dia, o portal do Azure não dá suporte à atribuição de uma identidade gerenciada atribuída pelo usuário durante a criação de uma VM. Você precisa criar uma máquina virtual e atribuir uma identidade gerenciada atribuída pelo usuário 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 ter uma conta do Azure Cosmos DB disponível em que você tenha direitos administrativos. Caso você precise criar uma conta do Azure Cosmos DB para este tutorial, o guia de início rápido do Azure Cosmos DB fornece etapas detalhadas de como fazer isso.

Observação

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

Configuração Valor Descrição
Subscription Nome da assinatura Selecione a assinatura do Azure que você deseja usar para essa conta do Azure Cosmos DB.
Grupo de recursos Nome do grupo de recursos Selecione mi-test ou Criar e insira um nome exclusivo para o novo grupo de recursos.
Nome da Conta Um nome exclusivo Insira um nome para identificar a conta do Azure Cosmos DB. Já que documents.Azure.com é acrescentado ao nome que você fornece para criar o URI, use um nome exclusivo.

O nome pode conter apenas letras minúsculas, números e o caractere de hífen (-). Ele deve ter entre 3 e 44 caracteres.
API O tipo de conta a ser criada Selecione Azure Cosmos DB for NoSQL para criar um banco de dados de documentos e uma consulta usando a sintaxe SQL.

Saiba mais sobre a API do SQL.
Location A região mais próxima dos usuários Selecione uma localização geográfica para hospedar a sua conta do Azure Cosmos DB. Use a localização mais próxima dos usuários para fornecer a eles acesso mais rápido aos dados.

Observação

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

Permitir 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 algumas funções diferentes à identidade gerenciada.

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

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

Observação

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

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

Acessar dados

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

A classe ManagedIdentityCredential tenta a autenticação 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 são as identidades gerenciadas.

No exemplo mostrado abaixo, você cria um banco de dados, um contêiner, um item no contêiner e lê novamente o item recém-criado usando a identidade gerenciada atribuída pelo sistema da máquina virtual. Se você quiser usar uma identidade gerenciada atribuída pelo usuário, precisará especificá-la informando 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 do NuGet:

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

Além dos pacotes do NuGet acima, você também precisa habilitar Incluir pré-lançamento e adicionar o 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 a um idioma usando ManagedIdentityCredential:

.NET

Inicialize o cliente do Azure Cosmos DB:

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

Depois, leia e grave os dados.

Java

Inicialize o 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 o 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

Dica

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

  1. Entre no portal do Azure.

  2. Selecione o recurso que você quer excluir.

  3. Selecione Excluir.

  4. Quando receber a solicitação, confirme a exclusão.

Próximas etapas

Saiba mais sobre identidades gerenciadas para recursos do Azure:

Saiba mais sobre o Azure Cosmos DB: