Como usar identidades geridas para ligar à Cosmos DB a partir de uma máquina virtual Azure

Neste artigo, criamos uma máquina virtual para usar identidades geridas para ligar ao Cosmos. Azure Cosmos DB é uma base de dados NoSQL totalmente gerida para o desenvolvimento de aplicações modernas. As identidades geridas para os recursos Azure permitem que as suas aplicações autentem a autenticação ao aceder a serviços que suportam Azure AD autenticação utilizando uma identidade gerida pela Azure.

Pré-requisitos

Criar um grupo de recursos

Criar um grupo de recursos chamado mi-test. Usaremos este grupo de recursos para todos os recursos usados neste tutorial.

Criar um VM Azure com uma identidade gerida

Para este tutorial, você precisa de uma máquina virtual Azure (VM). Crie uma máquina virtual com uma identidade gerida atribuída pelo sistema chamada mi-vm-01. Também pode criar uma identidade gerida atribuída ao utilizador chamada mi-ua-01 no grupo de recursos que criamos anteriormente (mi-test). Se utilizar uma identidade gerida atribuída pelo utilizador, pode atribuí-la a um VM durante a criação.

Criar um VM com uma identidade gerida atribuída ao sistema

Para criar um Azure VM com a identidade gerida atribuída ao sistema ativada, a sua conta precisa da atribuição de função de Contribuinte de Máquina Virtual . Não são necessárias outras atribuições de Azure AD funções.

  • Do portal do Azure procura por máquinas virtuais.
  • Selecione Criar
  • No separador Básicos, forneça as informações necessárias.
  • Escolha a seguir: Discos >
  • Continue a preencher informações conforme necessário e no separador Gestão encontre a secção identidade e verifique a caixa ao lado do Sistema de identidade gerida atribuída

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

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

Criar um VM com uma identidade gerida atribuída pelo utilizador

Os passos abaixo mostram-lhe como criar uma máquina virtual com uma identidade gerida atribuída pelo utilizador configurada.

Hoje, o portal do Azure não suporta a atribuição de uma identidade gerida pelo utilizador durante a criação de um VM. Deve criar uma máquina virtual e, em seguida, atribuir-lhe a identidade gerida por um utilizador.

Configure identidades geridas para os recursos da Azure num VM utilizando o portal do Azure

Criar uma conta do Cosmos DB

Agora que temos um VM com uma identidade gerida atribuída pelo utilizador ou uma identidade gerida atribuída ao sistema, precisamos de uma conta Cosmos DB disponível onde você tem direitos administrativos. Se você precisa criar uma conta Cosmos DB para este tutorial, o início rápido cosmos DB fornece passos detalhados sobre como fazê-lo.

Nota

As identidades geridas podem ser utilizadas para aceder a qualquer recurso Azure que suporte Azure Ative Directory autenticação. Este tutorial pressupõe que a sua conta Desmesubo cosmos será configurada como mostrado abaixo.

Definição Valor Descrição
Subscrição Nome da subscrição Selecione a subscrição do Azure que quer utilizar para esta conta do Azure Cosmos.
Grupo de Recursos Nome do grupo de recursos Selecione mi-teste ou selecione Criar novo e, em seguida, introduzir um nome único para o novo grupo de recursos.
Nome da Conta Um nome exclusivo Introduza um nome para identificar a conta do Azure Cosmos. 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 a 44 caracteres de comprimento.
API O tipo de conta a criar Selecione Núcleo (SQL) para criar uma base de dados de documentos e consultar com a sintaxe SQL.

Saiba mais sobre a API SQL.
Localização 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 estiver a testar, pode querer aplicar desconto de nível gratuito Azure Cosmos DB. Com o nível livre Azure Cosmos DB, você receberá os primeiros 1000 RU/s e 25 GB de armazenamento gratuitamente numa conta. Saiba mais sobre o free tier. Tenha em mente que, para efeitos deste tutorial, esta escolha não faz diferença.

Conceder acesso

Neste momento, devemos ter uma máquina virtual configurada com uma identidade gerida e uma conta Cosmos DB. Antes de continuarmos, precisamos de conceder à identidade gerida um par de papéis diferentes.

  • Primeiro conceder acesso ao avião de gestão Cosmos usando a Azure RBAC. A identidade gerida precisa de ter a função de Contribuinte de Conta DocumentDB atribuída para criar Bases de Dados e contentores.

  • Também precisa de conceder à identidade gerida um papel de contribuinte utilizando o Cosmos RBAC. Pode ver passos específicos abaixo.

Nota

Usaremos o papel de colaborador de dados incorporados da Cosmos DB . Para conceder acesso, é necessário associar a definição de função à identidade. No nosso caso, a identidade gerida associada à nossa máquina virtual.

Neste momento não existe nenhuma opção de atribuição de funções disponível no portal do Azure

Aceder a dados

O acesso ao Cosmos utilizando identidades geridas pode ser alcançado utilizando a biblioteca Azure.identity para permitir a autenticação na sua aplicação. Pode ligar diretamente para o ManagedIdentityCredential ou utilizar o DefaultAzureCredential.

A classe ManagedIdentityCredential tenta autenticar utilizando uma identidade gerida atribuída ao ambiente de implantação. A classe DefaultAzureCredential passa por diferentes opções de autenticação por ordem. A segunda opção de autenticação que o DefaultAzureCredential tenta são identidades geridas.

No exemplo mostrado abaixo, cria-se uma base de dados, um contentor, um item no recipiente, e lê-se o produto recém-criado utilizando o sistema da máquina virtual atribuído à identidade gerida. Se pretender utilizar uma identidade gerida atribuída ao utilizador, tem de especificar a identidade gerida atribuída pelo utilizador especificando o ID do cliente gerido.

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

Para utilizar a amostra abaixo, é necessário ter os seguintes pacotes NuGet:

  • Azure.Identidade
  • Microsoft.Azure.Cosmos
  • Microsoft.Azure.Management.CosmosDB

Além dos pacotes NuGet acima, também precisa de ativar incluir pré-lançamento e, em seguida, 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)
        {
            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();
        }
    }
}

Exemplos específicos da linguagem utilizando ManagedIdentityCredential:

.NET

Inicialize o seu cliente Cosmos DB:

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

Então leia e escreva dados.

Java

Inicialize o seu cliente Cosmos DB:

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

Em seguida, leia e escreva dados como descrito nestas amostras

JavaScript

Inicialize o seu cliente Cosmos DB:

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

Em seguida, leia e escreva dados como descrito nestas amostras

Limpar os passos

  1. No portal, selecione o recurso que pretende eliminar.

  2. Selecione Eliminar.

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

Passos seguintes

Saiba mais sobre identidades geridas para recursos Azure:

Saiba mais sobre a Azure Cosmos