Использование управляемых удостоверений для подключения к Azure Cosmos DB из виртуальной машины Azure

  • Статья

Внимание

Эта статья ссылается на CentOS, дистрибутив Linux, который приближается к состоянию конца жизни (EOL). Обратите внимание на использование и план соответствующим образом. Дополнительные сведения см. в руководстве centOS End Of Life.

В этой статье мы настроили виртуальную машину для использования управляемых удостоверений для подключения к Azure Cosmos DB. Azure Cosmos DB является полностью управляемой базой данных NoSQL для разработки современных приложений. Управляемые удостоверения для ресурсов Azure позволяют приложениям проходить проверку подлинности при доступе к службам, поддерживающим проверку подлинности Microsoft Entra с помощью удостоверения, управляемого Azure.

Необходимые компоненты

  • Базовое представление об управляемых удостоверениях. Чтобы получить дополнительные сведения об управляемых удостоверениях для ресурсов Azure, прежде чем продолжить работу, просмотрите обзор управляемых удостоверений.
  • Подготовьте учетную запись Azure с активной подпиской. Создайте учетную запись бесплатно .
  • Вам может потребоваться либо PowerShell, либо CLI.
  • Выпуск Visual Studio Community или другая среда разработки по вашему выбору.

Создание или изменение группы ресурсов

Создайте группу ресурсов с именем mi-test. Мы используем эту группу ресурсов для всех ресурсов, используемых в этом руководстве.

Создание виртуальной машины Azure с управляемым удостоверением

Для работы с этим учебником вам потребуется виртуальная машина Azure. Создайте виртуальную машину с включенным управляемым удостоверением, назначаемым системой, с именем mi-vm-01. Вы также можете создать управляемое удостоверение, назначаемое пользователем, с именем mi-ua-01 в созданной ранее группе ресурсов (mi-test). Если вы используете управляемое удостоверение, назначаемое пользователем, во время создания его можно назначить виртуальной машине.

Создание службы с управляемым удостоверением, назначаемым системой

Чтобы создать виртуальную машину Azure с включенным управляемым удостоверением, назначаемым системой, вашей учетной записи должна быть назначена роль Участник виртуальных машин. Другие назначения ролей Microsoft Entra не требуются.

  • На портале Azure найдите виртуальные машины.
  • нажмите кнопку Создать.
  • На вкладке "Основные сведения" введите требуемые значения.
  • Выберите Далее: Диски >.
  • Продолжайте заполнять информацию по мере необходимости. На вкладке Управление найдите раздел Удостоверение и установите флажок рядом с параметром Управляемое удостоверение, назначаемое системой.

Изображение, на котором показано, как включить управляемые удостоверения, назначаемые системой, при создании виртуальной машины.

Дополнительные сведения см. в документации по виртуальным машинам Azure:

Создание виртуальной машины с управляемым удостоверением, назначаемым пользователем

Ниже описаны действия по созданию виртуальной машины с настроенным управляемым удостоверением, назначаемым пользователем.

Сейчас портал Azure не поддерживает назначение управляемого удостоверения, назначаемого пользователем, во время создания виртуальной машины. Необходимо создать виртуальную машину, а затем назначить ей управляемое удостоверение, назначаемое пользователем.

Настройка управляемых удостоверений для ресурсов Azure на виртуальной машине с помощью портал Azure

Создание учетной записи Azure Cosmos DB

Теперь, когда у нас есть виртуальная машина с управляемым удостоверением, назначаемое пользователем, или управляемое удостоверение, назначаемое системой, требуется учетная запись Azure Cosmos DB, доступная для прав администратора. Если вам нужно создать учетную запись Azure Cosmos DB для этого руководства, краткое руководство по Azure Cosmos DB содержит подробные инструкции по этому способу.

Примечание.

Управляемые удостоверения можно использовать для доступа к любому ресурсу Azure, поддерживающим проверку подлинности Microsoft Entra. В этом руководстве предполагается, что учетная запись Azure Cosmos DB будет настроена, как показано ниже.

Параметр значение Описание
Подписка Имя подписки Выберите подписку Azure, которую вы хотите использовать для этой учетной записи Azure Cosmos DB.
Группа ресурсов Имя группы ресурсов Выберите mi-test или Создать, а затем введите уникальное имя для новой группы ресурсов.
Имя учетной записи Уникальное имя Введите имя для идентификации учетной записи Azure Cosmos DB. Так как элемент documents.azure.com добавляется к указанному вами имени для создания URI, используйте уникальное имя.

Имя может содержать только строчные буквы, цифры и знак дефиса (-). Длина — от 3 до 44 знаков.
API Тип учетной записи, которую нужно создать. Выберите Azure Cosmos DB для NoSQL , чтобы создать базу данных документов и выполнить запрос с помощью синтаксиса SQL.

Дополнительные сведения об API SQL
Расположение Ближайший к пользователям регион Выберите географическое расположение для размещения учетной записи Azure Cosmos DB. Используйте ближайшее к пользователям расположение, чтобы предоставить им максимально быстрый доступ к данным.

Примечание.

Если вы выполняете проверку, можете применить скидку на основе категории "Бесплатный" для Azure Cosmos DB. С помощью бесплатного уровня Azure Cosmos DB вы получите первые 1000 ЕЗ/с и 25 ГБ хранилища бесплатно в учетной записи. Ознакомьтесь с дополнительными сведениями о категории "Бесплатный". Не забывайте, что для выполнения инструкций из этого учебника не имеет значения, что вы выберите.

Предоставление доступа

На этом этапе у нас должна быть виртуальная машина, настроенная с помощью управляемого удостоверения и учетной записи Azure Cosmos DB. Прежде чем продолжить, необходимо предоставить управляемому удостоверению несколько различных ролей.

  • Сначала предоставьте доступ к плоскости управления Azure Cosmos DB с помощью Azure RBAC. Управляемому удостоверению необходимо назначить роль участника учетной записи DocumentDB для создания баз данных и контейнеров.

  • Кроме того, необходимо предоставить управляемому удостоверению роль участник с помощью RBAC Azure Cosmos DB. Ниже приведены конкретные действия.

Примечание.

Мы будем использовать роль встроенного участника данных Cosmos DB. Чтобы предоставить доступ, необходимо связать определение роли с удостоверением. В нашем случае управляемое удостоверение связано с виртуальной машиной.

Сейчас параметр назначения роли недоступен на портале Azure

Доступ к данным

Получение доступа к Azure Cosmos DB с помощью управляемых удостоверений может быть достигнуто с помощью библиотеки удостоверений Azure.identity для включения проверки подлинности в приложении. Вы можете напрямую вызвать ManagedIdentityCredential или использовать DefaultAzureCredential.

Класс ManagedIdentityCredential пытается выполнить проверку подлинности с помощью управляемого удостоверения, назначенного среде развертывания. Класс DefaultAzureCredential по порядку проходит по различным параметрам проверки подлинности. Второй вариант проверки подлинности, который пробует применить DefaultAzureCredential — это управляемые удостоверения.

В приведенном ниже примере создаются база данных, контейнер и элемент в контейнере, и созданные элементы считываются с помощью назначаемого системой управляемого удостоверения виртуальной машины. Если вы хотите использовать управляемое удостоверение, назначаемое пользователем, необходимо определить это удостоверение, указав идентификатор клиента управляемого удостоверения.

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

Чтобы использовать приведенный ниже пример, необходимо иметь следующие пакеты NuGet:

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

Кроме указанных выше пакетов NuGet, вам также необходимо активировать параметр Включить предварительные выпуски, а затем добавить 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();
        }
    }
}

Примеры для конкретного языка с использованием ManagedIdentityCredential:

.NET

Инициализировать клиент Azure Cosmos DB:

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

Затем прочтите и запишите данные.

Java

Инициализировать клиент Azure Cosmos DB:

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

Затем прочтите и запишите данные, как описано в этих примерах

JavaScript

Инициализировать клиент Azure Cosmos DB:

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

Затем прочтите и запишите данные, как описано в этих примерах

Завершающие шаги

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

  1. Войдите на портал Azure.

  2. Выберите ресурс, который требуется удалить.

  3. Выберите команду Удалить.

  4. При появлении запроса подтвердите удаление.

Следующие шаги

Дополнительные сведения об управляемых удостоверениях для ресурсов Azure:

Дополнительные сведения об Azure Cosmos DB: