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

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

Предварительные требования

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

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

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

Получить доступ к Cosmos с помощью управляемых удостоверений можно через библиотеку 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)
        {
            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();
        }
    }
}

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

.NET

Инициализируйте ваш клиент Cosmos DB с помощью следующей команды:

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

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

Java

Инициализируйте ваш клиент Cosmos DB с помощью следующей команды:

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

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

JavaScript

Инициализируйте ваш клиент Cosmos DB с помощью следующей команды:

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

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

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

  1. На портале выберите ресурс, который нужно удалить.

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

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

Дальнейшие действия

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

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