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

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

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

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

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

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

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

  # 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 без параметров следующим образом:

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. Измененная цепочка выглядит следующим образом:

По мере того как настраивается больше параметров ключевых слов с префиксом 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
)

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

Обзор ChainedTokenCredential

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

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

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

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

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

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

• Проблемы отладки: При сбое проверки подлинности может быть сложно выполнить отладку и идентификацию проблемных учетных данных. Необходимо включить ведение журнала, чтобы увидеть прогрессию от одного учетных данных к следующему и состоянию успешности или сбоя каждого. Дополнительные сведения см. в разделе Отладка цепочки учетных данных.
• Потери производительности: Процесс последовательного пробования нескольких учетных данных может вызвать потери производительности. Например, при запуске на локальном компьютере разработки управляемое удостоверение недоступно. Следовательно, 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)}"
)

Для иллюстрации предположим, что для проверки подлинности запроса к учетной записи хранилища блобов используется форма без параметров 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 удалось выполнить успешно, дальнейшие учетные данные проверены не были.