Проверка подлинности приложений C++, размещённых в Azure, для ресурсов Azure с помощью назначенного пользователем управляемого удостоверения.

Рекомендуемый подход к проверке подлинности Azure приложения для доступа к другим ресурсам Azure — использовать управляемое удостоверение. Этот подход поддерживается для большинства служб Azure, включая приложения, размещенные на Azure App Service, Azure Container Apps и Azure Virtual Machines. Узнайте больше о различных методах и подходах аутентификации на странице обзор методов аутентификации. В следующих разделах вы узнаете:

• Основные понятия управляемой идентификации
• Как создать управляемое удостоверение, назначаемое пользователем для вашего приложения
• Назначение ролей управляемому удостоверению, назначенному пользователем
• Как выполнить проверку подлинности с использованием управляемого удостоверения, назначенного пользователем, из кода приложения

Основные понятия управляемой идентификации

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

Существуют два типа управляемых удостоверений, которые следует учитывать при настройке хостингового приложения:

• System-assigned удостоверения, управляемые системой, активируются непосредственно на ресурсе Azure и связаны с его жизненным циклом. Когда ресурс удаляется, Azure автоматически удаляет удостоверение для вас. Системные идентификаторы обеспечивают простой подход к использованию управляемых удостоверений.
• назначаемые пользователем управляемые удостоверения создаются как автономные ресурсы Azure и обеспечивают большую гибкость и возможности. Они идеально подходят для решений с несколькими Azure ресурсами, которые должны совместно использовать одинаковые удостоверения и разрешения. Например, если нескольким виртуальным машинам требуется доступ к одному набору ресурсов Azure, управляемое удостоверение, назначаемое пользователем, обеспечивает повторное использование и оптимизированное управление.

Подсказка

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

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

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

Управляемые удостоверения, назначаемые пользователем, создаются как автономные ресурсы в вашей подписке Azure с использованием портала Azure или Azure CLI. команды Azure CLI можно выполнять в Azure Cloud Shell или на рабочей станции с установленным Azure CLI.

Azure

1. На портале Azure введите Управляемые идентификаторы в главную строку поиска и выберите соответствующий результат в разделе Службы.

2. На странице управляемых удостоверений выберите + Создать.

   

3. На странице Создание управляемого удостоверения, назначаемого пользователем, выберите подписку, группу ресурсов и регион для управляемого удостоверения, назначаемого пользователем, а затем укажите имя.

4. Выберите Проверить и создать для проверки входных данных.

   

5. Выберите Создать, чтобы создать управляемое удостоверение, назначаемое пользователем.

6. После создания идентичности выберите Перейти к ресурсу.

7. На странице обзора нового удостоверения скопируйте значение идентификатора клиента, чтобы использовать его позже при настройке кода приложения.

Azure CLI

Используйте команду Azure CLI az identity create для создания управляемого удостоверения:

az identity create \
    --resource-group <resource-group-name> \
    --name <identity-name> \
    --query 'clientId' \
    --output json

В выводе команды указывается идентификатор клиента для созданного управляемого удостоверения, назначенного пользователем. Идентификатор клиента используется для конфигурации кода приложения, который зависит от идентичности.

Свойства управляемого удостоверения можно просмотреть снова с помощью команды az identity show:

az identity show \
    --resource-group <your-resource-group> \
    --name <your-managed-identity-name> \
    --output json

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

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

Azure

1. На портале Azure перейдите к ресурсу, в котором размещен код вашего приложения, например, Azure App Service или инстанция Azure Container Apps.

2. На странице Обзор ресурса разверните Настройки и выберите Идентификация в панели навигации.

3. На странице Идентификация перейдите на вкладку Назначенные пользователи.

4. Выберите + Добавить, чтобы открыть панель для добавления управляемого удостоверения с назначением пользователя.

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

6. Выберите учетную запись и нажмите Добавить внизу панели, чтобы продолжить.

   

Azure CLI

Azure CLI предоставляет различные команды для назначения назначаемой пользователем управляемой идентичности различным типам служб размещения.

1. Чтобы назначить управляемое удостоверение, назначаемое пользователем, ресурсу, например веб-приложению Azure App Service, с помощью Azure CLI потребуется идентификатор удостоверения. Используйте команду az identity show для получения идентификатора ресурса:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query id
   

2. После получения идентификатора ресурса используйте команду Azure CLI az <resourceType> identity assign для связывания управляемого удостоверения, назначаемого пользователем, с различными ресурсами, например следующим образом:

   Для Azure App Service используйте команду Azure CLI az webapp identity assign:

   az webapp identity assign \
       --resource-group <resource-group-name> \
       --name <webapp-name> \
       --identities <user-assigned-identity-resource-id>
   

   Для Azure Container Apps используйте команду Azure CLI az containerapp identity assign:

   az containerapp identity assign \
       --resource-group <resource-group-name> \
       --name <containerapp-name> \
       --user-assigned <user-assigned-identity-resource-id>
   

   Для Azure Virtual Machines используйте команду Azure CLI az vm identity assign:

   az vm identity assign \
       --resource-group <resource-group-name> \
       --name <vm-name> \
       --identities <user-assigned-identity-resource-id>
   

Назначьте роли управляемому удостоверению

Затем определите, какие роли нужны вашему приложению, и назначьте эти роли для управляемого удостоверения. Роли можно назначить управляемым идентичностям на следующих уровнях:

• Ресурс: назначенные роли применяются только к этому конкретному ресурсу.
• Группа ресурсов: назначенные роли применяются ко всем ресурсам, содержащимся в данной группе.
• Подписка: Назначенные роли применяются ко всем ресурсам, входящим в состав подписки.

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

Azure

1. Перейдите на страницу Обзор группы ресурсов, в которой находится приложение с управляемым удостоверением, назначенным пользователем.

2. Выберите Управление доступом (IAM) на панели навигации слева.

3. На странице управления доступом (IAM) выберите + Добавить в верхнем меню, а затем выберите Назначение роли, чтобы перейти на страницу Назначение роли.

   

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

5. Выберите роль из результатов и выберите Далее, чтобы перейти на вкладку Участники.

6. Для параметра Назначить доступ к выберите Управляемое удостоверение.

7. Для параметра "Члены" выберите + "Выбор участников", чтобы открыть панель "Выбор управляемых удостоверений".

8. На панели Выбор управляемых удостоверений используйте раскрывающиеся списки Подписка и Управляемое удостоверение, чтобы отфильтровать результаты поиска для ваших удостоверений. Используйте поле поиска Select, чтобы найти управляемое удостоверение с пользовательским назначением, которое вы включили для ресурса Azure, где размещено ваше приложение.

   

9. Определите личность и выберите Выбрать в нижней части панели, чтобы продолжить.

10. Выберите Проверить и назначить в нижней части страницы.

11. На вкладке "Окончательная проверка и назначение " выберите "Проверка и назначение" для завершения рабочего процесса.

Azure CLI

1. Чтобы назначить роль управляемому удостоверению, назначенному пользователем, с помощью Azure CLI, потребуется идентификатор субъекта (principal ID) этого удостоверения. Используйте команду az identity show для получения основного идентификатора:

   az identity show \
       --resource-group <your-resource-group> \
       --name <your-managed-identity-name> \
       --output json \
       --query principalId
   

2. Используйте команду az role definition list, чтобы изучить, какие роли можно назначить управляемой идентичности.

   az role definition list \
       --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
       --output table
   

3. Назначьте роль управляемому удостоверению с помощью команды az role assignment create:

   az role assignment create \
       --assignee <your-principal-id> \
       --role <role-name> \
       --scope <scope>
   

   Например, чтобы разрешить управляемому удостоверению с идентификатором 99999999-9999-9999-9999-999999999999 права на чтение, запись и удаление к контейнерам и данным BLOB-объектов Azure Storage во всех учетных записях хранения в msdocs-sdk-auth-example группе ресурсов, назначьте субъект-справочник приложения участнику роли Вкладчик в данные BLOB-объектов хранилища с помощью следующей команды:

   az role assignment create \
       --assignee 99999999-9999-9999-9999-999999999999 \
       --role "Storage Blob Data Contributor" \
       --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-sdk-auth-example"
   

Сведения о назначении разрешений на уровне ресурса или подписки с помощью Azure CLI см. в статье Назначение ролей Azure с использованием Azure CLI.

Аутентификация для подключения к службам Azure из вашего приложения

Библиотека Azure Identity предоставляет различные классы учетных данных—и их реализации TokenCredential, адаптированные для поддержки различных сценариев и потоков проверки подлинности Microsoft Entra. Так как управляемое удостоверение недоступно при локальном выполнении, следующие действия демонстрируют, какие учетные данные следует использовать в каком сценарии:

• Локальная среда разработки: Используйте класс DefaultAzureCredential только во время локальной разработки для предварительно настроенной цепочки учетных данных. DefaultAzureCredential обнаруживает учетные данные пользователя из локального инструмента или интегрированной среды разработки, например Azure CLI или Visual Studio. Она также обеспечивает гибкость и удобство повторных попыток, время ожидания ответов и поддержку нескольких вариантов проверки подлинности. Дополнительные сведения см. в статье Аутентификация в службах Azure во время локальной разработки.
• Приложения, размещенные в Azure: Если ваше приложение запущено в Azure, используйте ManagedIdentityCredential для безопасного обнаружения управляемой идентичности, настроенной для вашего приложения. Указание этого точного типа учетных данных предотвращает неожиданное получение других доступных учетных данных.

Реализация кода

1. Добавьте пакет azure-identity-cpp в приложение с помощью vcpkg.

   В выбранном терминале перейдите к каталогу проекта приложения и выполните следующую команду:

   vcpkg add port azure-identity-cpp
   

2. Добавьте следующее в файл CMake:

   find_package(azure-identity-cpp CONFIG REQUIRED)
   target_link_libraries(<your project name> PRIVATE Azure::azure-identity)
   

3. Azure службы доступны с помощью специализированных клиентов из различных клиентских библиотек Azure SDK. Для любого кода C++, создающего экземпляр клиента Azure SDK в приложении, необходимо:

   1. Включите azure/identity.hpp заголовок.
   2. Создайте экземпляр DefaultAzureCredential.
   3. Передайте экземпляр DefaultAzureCredential конструктору клиента Azure SDK.
   4. Задайте для переменной AZURE_CLIENT_ID среды идентификатор клиента назначенного пользователем управляемого удостоверения.
   5. Установите переменную среды AZURE_TOKEN_CREDENTIALS в значение ManagedIdentityCredential, чтобы гарантировать, что DefaultAzureCredential использует учетные данные управляемого удостоверения. Эта практика делает процесс аутентификации более предсказуемым и упрощает отладку при развертывании в Azure. Дополнительные сведения см. в разделе "Использование определенных учетных данных".

   Пример этих действий показан в следующем фрагменте кода с клиентом Azure Storage Blob.

   #include <azure/identity.hpp>
   #include <azure/storage/blobs.hpp>
   #include <iostream>
   #include <memory>
   #include <cstdlib>
   
   int main() {
       try {
           // Set the AZURE_CLIENT_ID environment variable to your user-assigned managed identity client ID
           // This can be done in your deployment environment or in code (shown below for demonstration)
           // std::putenv("AZURE_CLIENT_ID=your-user-assigned-identity-client-id");
   
           // Create a credential - DefaultAzureCredential will use the AZURE_CLIENT_ID environment variable
           // Create a credential - DefaultAzureCredential will use the AZURE_CLIENT_ID and AZURE_TOKEN_CREDENTIALS environment variables
           auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);
   
           // Create a client for the specified storage account
           std::string accountUrl = "https://<replace_with_your_storage_account_name>.blob.core.windows.net/";
           Azure::Storage::Blobs::BlobServiceClient blobServiceClient(accountUrl, credential);
   
           // Get a reference to a container
           std::string containerName = "sample-container";
           auto containerClient = blobServiceClient.GetBlobContainerClient(containerName);
   
           // Get a reference to a blob
           std::string blobName = "sample-blob";
           auto blobClient = containerClient.GetBlobClient(blobName);
   
           // TODO: perform some action with the blob client
           // auto downloadResult = blobClient.DownloadTo("path/to/local/file");
   
           std::cout << "Successfully authenticated using user-assigned managed identity." << std::endl;
   
       } catch (const std::exception& ex) {
           std::cout << "Exception: " << ex.what() << std::endl;
           return 1;
       }
   
       return 0;
   }
   

Как описано в статье Azure SDK для проверки подлинности C++, DefaultAzureCredential поддерживает несколько методов проверки подлинности и определяет метод проверки подлинности, используемый во время выполнения. Преимуществом этого подхода является то, что приложение может использовать различные методы проверки подлинности в разных средах без реализации кода для конкретной среды. При запуске предыдущего кода на рабочей станции в ходе локальной разработки DefaultAzureCredential используется либо основная учетная запись службы приложения, как это определено параметрами среды, либо учетные данные средств разработчика для аутентификации с другими ресурсами Azure. Таким образом, один и тот же код можно использовать для проверки подлинности приложения для Azure ресурсов во время локальной разработки и при развертывании в Azure.

Это важно

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

Альтернативой DefaultAzureCredential является использование ManagedIdentityCredential. Шаги для использования ManagedIdentityCredential такие же, как для использования типа DefaultAzureCredential.

Пример этих действий показан в следующем фрагменте кода с клиентом Azure Storage Blob.

#include <azure/identity.hpp>
#include <azure/storage/blobs.hpp>
#include <iostream>
#include <memory>

int main() {
    try {
        // Create a user-assigned managed identity credential with the client ID
        Azure::Identity::ManagedIdentityCredentialOptions options;
        options.ClientId = "abcd1234-..."; // Replace with your user-assigned managed identity client ID
        auto credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>(options);
        
        // Create a client for the specified storage account
        std::string accountUrl = "https://<replace_with_your_storage_account_name>.blob.core.windows.net/";
        Azure::Storage::Blobs::BlobServiceClient blobServiceClient(accountUrl, credential);
        
        // Get a reference to a container
        std::string containerName = "sample-container";
        auto containerClient = blobServiceClient.GetBlobContainerClient(containerName);
        
        // Get a reference to a blob
        std::string blobName = "sample-blob";
        auto blobClient = containerClient.GetBlobClient(blobName);
        
        // TODO: perform some action with the blob client
        // auto downloadResult = blobClient.DownloadTo("path/to/local/file");
        
        std::cout << "Successfully authenticated using user-assigned managed identity." << std::endl;
        
    } catch (const std::exception& ex) {
        std::cout << "Exception: " << ex.what() << std::endl;
        return 1;
    }
    
    return 0;
}