Поделиться через

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

  • Статья

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

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

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

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

Почему используются цепочки учетных данных

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

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

    # Set up credential based on environment (Azure or local development)
if os.getenv("WEBSITE_HOSTNAME"):
    credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
else:
    credential = AzureCliCredential()

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

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

Выбор цепочки учетных данных

Существует две разрозненные философии для цепочки учетных данных:

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

Обзор DefaultAzureCredential

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

Схема, на которую показан поток проверки подлинности DefaultAzureCredential.

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

Порядок Подтверждение компетенции Description Включено по умолчанию?
1 Среда Считывает коллекцию переменных среды, чтобы определить, настроен ли субъект-служба приложений (пользователь приложения) для приложения. В этом случае использует эти значения для DefaultAzureCredential проверки подлинности приложения в Azure. Этот метод чаще всего используется в средах сервера, но также может использоваться при разработке локально. Да
2 Удостоверение рабочей нагрузки Если приложение развернуто на узле Azure с включенным удостоверением рабочей нагрузки, выполните проверку подлинности этой учетной записи. Да
3 управляемое удостоверение; Если приложение развернуто на узле Azure с включенным управляемым удостоверением, выполните проверку подлинности приложения в Azure с помощью этого управляемого удостоверения. Да
4 Кэш общих маркеров Только в Windows, если разработчик прошел проверку подлинности в Azure, войдите в Visual Studio, выполните проверку подлинности приложения в Azure с помощью той же учетной записи. Да
5 Azure CLI Если разработчик прошел проверку подлинности в Azure с помощью команды Azure CLI az login , выполните проверку подлинности приложения в Azure с помощью той же учетной записи. Да
6 Azure PowerShell Если разработчик прошел проверку подлинности в Azure с помощью командлета Connect-AzAccount Azure PowerShell, выполните проверку подлинности приложения в Azure с помощью той же учетной записи. Да
7 Интерфейс командной строки разработчика Azure Если разработчик прошел проверку подлинности в Azure с помощью команды Azure Developer CLI azd auth login , выполните проверку подлинности с помощью этой учетной записи. Да
8 Интерактивный браузер Если этот параметр включен, в интерактивном режиме выполняется проверка подлинности разработчика через браузер по умолчанию текущей системы. No

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

Настройка DefaultAzureCredential

Чтобы удалить учетные данные, DefaultAzureCredentialиспользуйте соответствующий excludeпараметр ключевого слова с префиксом. Например:

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

В предыдущем примере EnvironmentCredential кода и WorkloadIdentityCredential удаляются из цепочки учетных данных. В результате первая попытка выполнить попытку ManagedIdentityCredentialучетных данных. Измененная цепочка выглядит следующим образом:

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

Примечание.

InteractiveBrowserCredential по умолчанию исключается и поэтому не отображается на предыдущей схеме. Чтобы включить InteractiveBrowserCredential, задайте для параметра ключевого exclude_interactive_browser_credential слова значение False при вызове конструктора DefaultAzureCredential .

По мере настройки дополнительных excludeпараметров ключевого слова с префиксом (настраиваются True исключения учетных данных), преимущества использования уменьшается DefaultAzureCredential . В таких случаях ChainedTokenCredential лучше выбрать и требовать меньше кода. Чтобы проиллюстрировать, эти два примера кода ведут себя так же:

credential = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

Обзор ChainedTokenCredential

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

credential = ChainedTokenCredential(
    ManagedIdentityCredential(client_id=user_assigned_client_id),
    AzureCliCredential()
)

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

Схема, на которой показан поток проверки подлинности для экземпляра ChainedTokenCredential, состоящего из учетных данных управляемого удостоверения и учетных данных Azure CLI.

Совет

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

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

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

  • Определенная реализация учетных данных, например ManagedIdentityCredential.
  • Реализация, оптимизированная ChainedTokenCredential для среды Azure, в которой выполняется приложение.

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

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

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

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

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Для иллюстрации предположим, что для проверки подлинности запроса к учетной записи хранения BLOB-объектов используется без DefaultAzureCredential параметров. Приложение выполняется в локальной среде разработки, и разработчик прошел проверку подлинности в Azure с помощью Azure CLI. Предположим, что для уровня ведения журнала задано значение logging.DEBUG. При запуске приложения в выходных данных отображаются следующие соответствующие записи:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

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

  • EnvironmentCredential, ManagedIdentityCredentialи SharedTokenCacheCredential каждый из них не получил маркер доступа Microsoft Entra в этом порядке.
  • Вызов AzureCliCredential.get_token завершается успешно, а выходные данные также указывают на получение DefaultAzureCredential маркера из AzureCliCredential. После AzureCliCredential успешного выполнения учетные данные за его пределами не были проверены.

Примечание.

В предыдущем примере для уровня ведения журнала задано значение logging.DEBUG. Будьте осторожны при использовании этого уровня ведения журнала, так как он может выводить конфиденциальную информацию. Например, в этом случае идентификатор клиента, идентификатор клиента и идентификатор объекта субъекта-пользователя разработчика в Azure. Все сведения о обратной трассировке удалены из выходных данных для ясности.