Jak używać tożsamości zarządzanych do nawiązywania połączenia z usługą Azure Cosmos DB z maszyny wirtualnej platformy Azure

  • Artykuł

Uwaga

W tym artykule odwołuje się do systemu CentOS — dystrybucji systemu Linux, która zbliża się do stanu zakończenia życia (EOL). Rozważ odpowiednie użycie i zaplanuj. Aby uzyskać więcej informacji, zobacz wskazówki dotyczące zakończenia życia systemu CentOS.

W tym artykule skonfigurujemy maszynę wirtualną do używania tożsamości zarządzanych do nawiązywania połączenia z usługą Azure Cosmos DB. Usługa Azure Cosmos DB to w pełni zarządzana baza danych NoSQL do tworzenia nowoczesnych aplikacji. Tożsamości zarządzane dla zasobów platformy Azure umożliwiają aplikacjom uwierzytelnianie podczas uzyskiwania dostępu do usług obsługujących uwierzytelnianie firmy Microsoft Entra przy użyciu tożsamości zarządzanej przez platformę Azure.

Wymagania wstępne

Tworzenie grupy zasobów

Utwórz grupę zasobów o nazwie mi-test. Ta grupa zasobów jest używana dla wszystkich zasobów używanych w tym samouczku.

Tworzenie maszyny wirtualnej platformy Azure z tożsamością zarządzaną

Na potrzeby tego samouczka potrzebujesz maszyny wirtualnej platformy Azure. Utwórz maszynę wirtualną z włączoną tożsamością zarządzaną przypisaną przez system o nazwie mi-vm-01. Możesz również utworzyć tożsamość zarządzaną przypisaną przez użytkownika o nazwie mi-ua-01 w utworzonej wcześniej grupie zasobów (mi-test). Jeśli używasz tożsamości zarządzanej przypisanej przez użytkownika, możesz przypisać ją do maszyny wirtualnej podczas tworzenia.

Tworzenie maszyny wirtualnej z tożsamością zarządzaną przypisaną przez system

Aby utworzyć maszynę wirtualną platformy Azure z włączoną tożsamością zarządzaną przypisaną przez system, twoje konto wymaga przypisania roli Współautor maszyny wirtualnej. Nie są wymagane żadne inne przypisania ról firmy Microsoft Entra.

  • W witrynie Azure Portal wyszukaj maszyny wirtualne.
  • Wybierz pozycję Utwórz.
  • Na karcie Podstawy podaj wymagane informacje.
  • Wybierz pozycję Dalej: dyski >
  • Kontynuuj wypełnianie informacji zgodnie z potrzebami, a na karcie Zarządzanie znajdź sekcję Tożsamość i zaznacz pole wyboru obok pozycji Tożsamość zarządzana przypisana przez system

Obraz przedstawiający sposób włączania tożsamości zarządzanych przypisanych przez system podczas tworzenia maszyny wirtualnej.

Aby uzyskać więcej informacji, zapoznaj się z dokumentacją maszyn wirtualnych platformy Azure:

Tworzenie maszyny wirtualnej z tożsamością zarządzaną przypisaną przez użytkownika

W poniższych krokach pokazano, jak utworzyć maszynę wirtualną ze skonfigurowaną tożsamością zarządzaną przypisaną przez użytkownika.

Obecnie witryna Azure Portal nie obsługuje przypisywania tożsamości zarządzanej przypisanej przez użytkownika podczas tworzenia maszyny wirtualnej. Należy utworzyć maszynę wirtualną, a następnie przypisać do niej tożsamość zarządzaną przypisaną przez użytkownika.

Konfigurowanie tożsamości zarządzanych dla zasobów platformy Azure na maszynie wirtualnej przy użyciu witryny Azure Portal

Tworzenie konta usługi Azure Cosmos DB

Teraz, gdy mamy maszynę wirtualną z tożsamością zarządzaną przypisaną przez użytkownika lub tożsamością zarządzaną przypisaną przez system, potrzebujemy konta usługi Azure Cosmos DB dostępnego, jeśli masz uprawnienia administracyjne. Jeśli musisz utworzyć konto usługi Azure Cosmos DB na potrzeby tego samouczka, przewodnik Szybki start dotyczący usługi Azure Cosmos DB zawiera szczegółowe instrukcje dotyczące tego, jak to zrobić.

Uwaga

Tożsamości zarządzane mogą służyć do uzyskiwania dostępu do dowolnego zasobu platformy Azure obsługującego uwierzytelnianie firmy Microsoft Entra. W tym samouczku założono, że twoje konto usługi Azure Cosmos DB zostanie skonfigurowane, jak pokazano poniżej.

Ustawienie Wartość Opis
Subskrypcja Nazwa subskrypcji Wybierz subskrypcję platformy Azure, która ma być używana dla tego konta usługi Azure Cosmos DB.
Grupa zasobów Nazwa grupy zasobów Wybierz pozycję mi-test lub wybierz pozycję Utwórz nową, a następnie wprowadź unikatową nazwę nowej grupy zasobów.
Nazwa konta Unikatowa nazwa Wprowadź nazwę, aby zidentyfikować konto usługi Azure Cosmos DB. Ponieważ adres documents.azure.com jest dołączany do podanej nazwy w celu utworzenia identyfikatora URI, użyj unikatowej nazwy.

Nazwa może zawierać tylko małe litery, cyfry i znaki łącznika (-). Musi mieć długość od 3 do 44 znaków.
interfejs API Typ konta do utworzenia Wybierz pozycję Azure Cosmos DB for NoSQL , aby utworzyć bazę danych dokumentów i wykonywać zapytania przy użyciu składni JĘZYKA SQL.

Dowiedz się więcej o interfejsie API SQL.
Lokalizacja Region najbliżej Twoich użytkowników Wybierz lokalizację geograficzną, w której będzie hostowane konto usługi Azure Cosmos DB. Użyj lokalizacji znajdującej się najbliżej Twoich użytkowników, aby zapewnić im najszybszy dostęp do danych.

Uwaga

Jeśli testujesz, możesz zastosować rabat na warstwę bezpłatną usługi Azure Cosmos DB. Dzięki warstwie Bezpłatna usługi Azure Cosmos DB uzyskasz pierwsze 1000 RU/s i 25 GB miejsca do magazynowania bezpłatnie na koncie. Dowiedz się więcej o warstwie Bezpłatna. Należy pamiętać, że na potrzeby tego samouczka ten wybór nie ma znaczenia.

Udzielanie dostępu

Na tym etapie powinniśmy mieć zarówno maszynę wirtualną skonfigurowaną przy użyciu tożsamości zarządzanej, jak i konta usługi Azure Cosmos DB. Zanim przejdziemy dalej, musimy udzielić tożsamości zarządzanej kilku różnych ról.

  • Najpierw przyznaj dostęp do płaszczyzny zarządzania usługi Azure Cosmos DB przy użyciu kontroli dostępu opartej na rolach platformy Azure. Tożsamość zarządzana musi mieć przypisaną rolę Współautor konta usługi DocumentDB w celu utworzenia baz danych i kontenerów.

  • Musisz również udzielić tożsamości zarządzanej roli współautora przy użyciu kontroli dostępu opartej na rolach usługi Azure Cosmos DB. Poniżej przedstawiono konkretne kroki.

Uwaga

Użyjemy roli współautora danych wbudowanych usługi Cosmos DB. Aby udzielić dostępu, musisz skojarzyć definicję roli z tożsamością. W naszym przypadku tożsamość zarządzana skojarzona z naszą maszyną wirtualną.

Obecnie w witrynie Azure Portal nie jest dostępna opcja przypisania roli

Uzyskiwanie dostępu do danych

Uzyskanie dostępu do usługi Azure Cosmos DB przy użyciu tożsamości zarządzanych można osiągnąć przy użyciu biblioteki Azure.identity w celu włączenia uwierzytelniania w aplikacji. Możesz wywołać metodę ManagedIdentityCredential bezpośrednio lub użyć wartości DefaultAzureCredential.

Klasa ManagedIdentityCredential próbuje uwierzytelnić się przy użyciu tożsamości zarządzanej przypisanej do środowiska wdrażania. Klasa DefaultAzureCredential przechodzi przez różne opcje uwierzytelniania w kolejności. Drugą opcją uwierzytelniania domyślnąAzureCredential jest tożsamość zarządzana.

W poniższym przykładzie tworzysz bazę danych, kontener, element w kontenerze i odczytujesz nowo utworzony element przy użyciu przypisanej przez system tożsamości zarządzanej maszyny wirtualnej. Jeśli chcesz użyć tożsamości zarządzanej przypisanej przez użytkownika, musisz określić tożsamość zarządzaną przypisaną przez użytkownika, określając identyfikator klienta tożsamości zarządzanej.

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

Aby użyć poniższego przykładu, musisz mieć następujące pakiety NuGet:

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

Oprócz powyższych pakietów NuGet należy również włączyć opcję Uwzględnij wersję wstępną , a następnie dodać usługę 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();
        }
    }
}

Przykłady specyficzne dla języka korzystające z elementu ManagedIdentityCredential:

.NET

Zainicjuj klienta usługi Azure Cosmos DB:

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

Następnie odczyt i zapis danych.

Java

Zainicjuj klienta usługi Azure Cosmos DB:

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

Następnie odczytaj i zapisz dane zgodnie z opisem w tych przykładach

JavaScript

Zainicjuj klienta usługi Azure Cosmos DB:

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

Następnie odczytaj i zapisz dane zgodnie z opisem w tych przykładach

Kroki czyszczenia

Napiwek

Kroki opisane w tym artykule mogą się nieznacznie różnić w zależności od portalu, od którego zaczynasz.

  1. Zaloguj się w witrynie Azure Portal.

  2. Wybierz zasób, który chcesz usunąć.

  3. Wybierz Usuń.

  4. Po wyświetleniu monitu potwierdź usunięcie.

Następne kroki

Dowiedz się więcej o tożsamościach zarządzanych dla zasobów platformy Azure:

Dowiedz się więcej o usłudze Azure Cosmos DB: