Цепочки учетных данных в клиентской библиотеке удостоверений Azure для C++

Клиентская библиотека удостоверений Azure предоставляет креденциалы — общедоступные типы, производные от абстрактного базового класса TokenCredential библиотеки Azure Core. Учетные данные представляют собой отдельный процесс аутентификации для получения токена доступа от Microsoft Entra ID. Эти учетные данные можно объединить в цепочку, чтобы сформировать упорядоченную последовательность механизмов проверки подлинности, которые необходимо предпринять.

Как работает связанное удостоверение

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

Зачем использовать цепочки учетных данных?

Цепочка учётных данных может предложить следующие преимущества:

• Осведомленность о среде. Автоматически выбирает наиболее подходящие учетные данные в зависимости от среды, в которой выполняется приложение. Без этого вам потребуется написать код следующим образом:

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::AzureCliCredential>();
  }
  

• Плавный переход: Ваше приложение может перейти от локальной разработки к тестовой или рабочей среде без изменения кода аутентификации.

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

Как выбрать цепочку учетных данных

При использовании C++существует два варианта цепочки учетных данных:

• Использовать предварительно настроенную цепочку: используйте предварительно настроенную цепочку, реализованную типом DefaultAzureCredential. Для этого подхода см. раздел " Общие сведения о DefaultAzureCredential".
• создать настраиваемую цепочку учетных данных: начните с пустой цепочки и включите только то, что вам нужно. Для этого подхода см. раздел " Обзор ChainedTokenCredential ".

Обзор DefaultAzureCredential

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

Порядок, в котором DefaultAzureCredential проверяет учетные данные, следующий.

В самой простой форме можно использовать версию DefaultAzureCredential без параметров следующим образом:

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Как настроить DefaultAzureCredential

В следующих разделах описываются стратегии управления учетными данными, включенными в цепочку.

Исключить категорию типа учетных данных

Чтобы исключить все Developer tool или Deployed service учетные данные, установите значение переменной среды AZURE_TOKEN_CREDENTIALS на prod или dev, соответственно. Если используется значение prod, основная цепочка учетных данных выглядит следующим образом:

Если используется значение dev, цепочка включает только AzureCliCredential.

Использование определенных учетных данных

Чтобы исключить все учетные данные, кроме одного, задайте для переменной AZURE_TOKEN_CREDENTIALS среды имя учетных данных. Например, можно уменьшить цепочку, установив для нее DefaultAzureCredential значение AzureCliCredentialAZURE_TOKEN_CREDENTIALS .AzureCliCredential Сравнение строк выполняется без учета регистра. Допустимые строковые значения для переменной среды:

• AzureCliCredential
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Обзор ChainedTokenCredential

ChainedTokenCredential — это пустая цепочка, в которую добавляются учетные данные в соответствии с потребностями приложения. Рассмотрим пример.

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

В предыдущем примере кода создается настраиваемая цепочка учетных данных, состоящая из двух учетных данных. Сначала предпринимается попытка с использованием ManagedIdentityCredential, а затем AzureCliCredential, если это необходимо. В графической форме цепочка выглядит следующим образом:

Руководство по использованию по DefaultAzureCredential

DefaultAzureCredential, несомненно, самый простой способ приступить к работе с клиентской библиотекой удостоверений Azure, но это удобство связано с определенными компромиссами. После развертывания приложения в Azure необходимо понять требования к проверке подлинности приложения. По этой причине замените DefaultAzureCredential определенной реализацией TokenCredential, например ManagedIdentityCredential.

Для этого есть следующие причины.

• Проблемы отладки: При сбое проверки подлинности может быть сложно выполнить отладку и идентификацию проблемных учетных данных. Необходимо включить ведение журнала, чтобы увидеть переход от одной учетной записи к следующей и успешное/неуспешное состояние их. Дополнительные сведения см. в разделе Отладка цепочки учетных данных.
• Потери производительности: Процесс последовательной проверки нескольких учетных данных может привести к перегрузке производительности. Например, управляемая идентификация недоступна, когда вы запускаете программу на локальной машине для разработки. Следовательно, ManagedIdentityCredential всегда терпит сбой в локальной среде.
• Непредсказуемое поведение: DefaultAzureCredential проверяет наличие определенных переменных среды. Возможно, кто-то может добавить или изменить эти переменные среды на уровне системы на хост-компьютере. Эти изменения применяются глобально и поэтому изменяют поведение DefaultAzureCredential во время выполнения в любом приложении, работающем на этом компьютере.

Отладка цепочки учетных данных

Чтобы диагностировать непредвиденную проблему или понять, как работают связанные учетные данные, включите ведение журнала в вашем приложении. Для примера предположим, что форма без параметров DefaultAzureCredential используется для аутентификации запроса к учетной записи Blob Storage. Приложение выполняется в локальной среде разработки, и разработчик прошел проверку подлинности в Azure с помощью Azure CLI. При запуске приложения в выходных данных отображаются следующие соответствующие записи:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

В предыдущих выходных данных обратите внимание, что:

• EnvironmentCredential, WorkloadIdentityCredential, и ManagedIdentityCredential каждый не получил токен доступа Microsoft Entra в этом порядке.
• ManagedIdentityCredential выполняется успешно, как указано в записи, начинающейся с "Successfully got token from ManagedIdentityCredential".