Клиентская библиотека удостоверений Azure для Python — версия 1.14.1
Библиотека удостоверений Azure обеспечивает поддержку проверки подлинности маркеров Azure Active Directory (Azure AD) в пакете Azure SDK. Он предоставляет набор реализацийTokenCredential, которые можно использовать для создания клиентов пакета SDK Azure, поддерживающих проверку подлинности Azure AD маркером.
Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | APIдокументация по Azure AD
Начало работы
Установка пакета
Установите Удостоверение Azure с помощью pip:
pip install azure-identity
Предварительные требования
- Подписка Azure
- Python 3.7 или последняя версия Python 3 (эта библиотека не поддерживает версии с окончанием срока службы)
Проверка подлинности во время локальной разработки
При отладке и выполнении кода локально разработчики обычно используют собственные учетные записи для проверки подлинности вызовов служб Azure. Библиотека удостоверений Azure поддерживает проверку подлинности с помощью средств разработчика, чтобы упростить локальную разработку.
Проверка подлинности с помощью Visual Studio Code
Разработчики, использующие Visual Studio Code, могут использовать расширение учетной записи Azure для проверки подлинности с помощью редактора. Приложения, использующие DefaultAzureCredential или VisualStudioCodeCredential , затем могут использовать эту учетную запись для проверки подлинности вызовов в своем приложении при локальном запуске.
Для проверки подлинности в Visual Studio Code убедитесь, что установлено расширение учетной записи Azure. После установки откройте палитру команд и выполните команду Azure: Вход .
Это известная проблема , которая VisualStudioCodeCredential не работает с расширениями учетной записи Azure более поздних версий , чем 0.9.11. В настоящее время выполняется решение этой проблемы в долгосрочной перспективе. Тем временем рассмотрите возможность проверки подлинности с помощью Azure CLI.
Проверка подлинности с помощью Azure CLI
DefaultAzureCredential и AzureCliCredential может проходить проверку подлинности как пользователь, вошедшего в Azure CLI. Чтобы войти в Azure CLI, выполните команду az login. В системе с веб-браузером по умолчанию Azure CLI запустит браузер для проверки подлинности пользователя.
Если браузер по умолчанию недоступен, az login будет использовать поток проверки подлинности кода устройства. Этот поток также можно выбрать вручную, запустив az login --use-device-code.
Проверка подлинности с помощью Azure Developer CLI
Разработчики, кодирующие вне интегрированной среды разработки, также могут использовать Azure Developer CLI для проверки подлинности. Затем приложения, использующие DefaultAzureCredential или AzureDeveloperCliCredential, могут использовать эту учетную запись для проверки подлинности вызовов в своем приложении при локальном запуске.
Для проверки подлинности с помощью Azure Developer CLI пользователи могут выполнить команду azd auth login. Для пользователей, работающих в системе с веб-браузером по умолчанию, Azure Developer CLI запустит браузер для проверки подлинности пользователя.
Для систем без веб-браузера по умолчанию команда azd auth login --use-device-code будет использовать поток проверки подлинности в коде устройства.
Основные понятия
Подтверждение компетенции
Учетные данные — это класс, который содержит или может получать данные, необходимые клиенту службы для аутентификации запросов. Клиенты служб в пакете AZURE SDK принимают экземпляр учетных данных при создании и используют эти учетные данные для проверки подлинности запросов.
Библиотека удостоверений Azure фокусируется на проверке подлинности OAuth с помощью Azure AD. Он предлагает различные классы учетных данных, способные получить маркер доступа Azure AD. Список классов учетных данных этой библиотеки см. в разделе учетных данных ниже.
DefaultAzureCredential
DefaultAzureCredential подходит для большинства приложений, которые будут выполняться в Azure, так как в нем объединяются общие рабочие учетные данные с учетными данными разработки. DefaultAzureCredential пытается выполнить проверку подлинности с помощью следующих механизмов в этом порядке, чтобы остановить при успешном выполнении:
Примечание.
DefaultAzureCredentialПредназначено для упрощения работы с библиотекой за счет обработки распространенных сценариев с разумным поведением по умолчанию. Разработчикам, которым требуется больше возможностей управления или сценарий которых не обслуживается параметрами по умолчанию, следует использовать другие типы учетных данных.
- Среды -
DefaultAzureCredentialбудет считывать сведения об учетной записи, указанные с помощью , и использовать их для проверки подлинности. - Удостоверение рабочей нагрузки. Если приложение развернуто в Служба Azure Kubernetes с включенным управляемым удостоверением,
DefaultAzureCredentialвыполняет проверку подлинности с помощью него. - Управляемое удостоверение . Если приложение развернуто на узле Azure с включенным управляемым удостоверением,
DefaultAzureCredentialвыполняет проверку подлинности с помощью него. - Azure CLI . Если пользователь выполнил вход с помощью команды Azure CLI
az login,DefaultAzureCredentialбудет проходить проверку подлинности от имени этого пользователя. - Azure PowerShell . Если пользователь выполнил вход с помощью команды Azure PowerShell
Connect-AzAccount,DefaultAzureCredentialбудет проходить проверку подлинности от имени этого пользователя. - Azure Developer CLI . Если разработчик прошел проверку подлинности с помощью команды Azure Developer CLI
azd auth login, выполняет проверку подлинностиDefaultAzureCredentialс помощью этой учетной записи. - Интерактивный браузер — если он включен,
DefaultAzureCredentialбудет выполнять интерактивную проверку подлинности пользователя с помощью браузера по умолчанию. Этот тип учетных данных отключен по умолчанию.
Примечание о VisualStudioCodeCredential
Из-за известной проблемыVisualStudioCodeCredential удален из цепочки маркеровDefaultAzureCredential. Когда проблема будет устранена в будущем выпуске, это изменение будет отменено.
Примеры
Ниже приведены примеры.
- Проверка подлинности с помощью DefaultAzureCredential
- Определение настраиваемого потока проверки подлинности с помощью ChainedTokenCredential
- Асинхронные учетные данные
Проверка подлинности с помощью DefaultAzureCredential
Дополнительные сведения о настройке среды для использования DefaultAzureCredential можно найти в справочной документации по классу.
В этом примере демонстрируется проверка подлинности BlobServiceClient из библиотеки azure-storage-blob с помощью DefaultAzureCredential.
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
default_credential = DefaultAzureCredential()
client = BlobServiceClient(account_url, credential=default_credential)
Включение интерактивной проверки подлинности с помощью DefaultAzureCredential
Интерактивная проверка подлинности по умолчанию отключена DefaultAzureCredential в и может быть включена с помощью ключевое слово аргумента:
DefaultAzureCredential(exclude_interactive_browser_credential=False)
Если этот параметр включен, DefaultAzureCredential возвращается к интерактивной проверке подлинности через веб-браузер по умолчанию системы, если другие учетные данные недоступны.
Укажите управляемое удостоверение, назначаемое пользователем, для DefaultAzureCredential
Многие узлы Azure позволяют назначать управляемое удостоверение, назначаемое пользователем. Чтобы настроить DefaultAzureCredential проверку подлинности удостоверения, назначаемого пользователем, используйте managed_identity_client_id аргумент ключевое слово:
DefaultAzureCredential(managed_identity_client_id=client_id)
Кроме того, можно задать для переменной AZURE_CLIENT_ID среды идентификатор клиента удостоверения.
Определение настраиваемого потока проверки подлинности с помощью ChainedTokenCredential
DefaultAzureCredential Как правило, это самый быстрый способ приступить к разработке приложений для Azure. Для более сложных сценариев ChainedTokenCredential связывает несколько экземпляров учетных данных для последовательной проверки подлинности. Он будет пробовать все связанные учетные данные по очереди, пока один из них не предоставит маркер или не сможет пройти проверку подлинности из-за ошибки.
В следующем примере показано создание учетных данных, которые сначала будут пытаться пройти проверку подлинности с помощью управляемого удостоверения. Если управляемое удостоверение недоступно, учетные данные будут возвращены к проверке подлинности с помощью Azure CLI. В этом примере используется EventHubProducerClient из клиентской библиотеки azure-eventhub .
from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential
managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)
client = EventHubProducerClient(namespace, eventhub_name, credential_chain)
Асинхронные учетные данные
Эта библиотека содержит набор асинхронных API. Чтобы использовать асинхронные учетные данные в azure.identity.aio, необходимо сначала установить асинхронный транспорт, например aiohttp. Дополнительные сведения см. в документации по azure-core.
Асинхронные учетные данные следует закрывать, если они больше не нужны. Каждая асинхронная учетные данные является асинхронным диспетчером контекста и определяет асинхронный close метод. Пример:
from azure.identity.aio import DefaultAzureCredential
# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()
# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
...
В этом примере демонстрируется проверка подлинности асинхронного SecretClient из azure-keyvault-secrets с помощью асинхронных учетных данных.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)
Поддержка управляемых удостоверений
Проверка подлинности управляемого удостоверения поддерживается через DefaultAzureCredential или напрямую ManagedIdentityCredential для следующих служб Azure:
- Служба приложений Azure и Функции Azure
- Azure Arc
- Azure Cloud Shell;
- Служба Azure Kubernetes
- Azure Service Fabric
- Виртуальные машины Azure
- Масштабируемые наборы azure Виртуальные машины
Примеры
Проверка подлинности с помощью управляемого удостоверения, назначаемого пользователем
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)
Проверка подлинности с помощью управляемого удостоверения, назначаемого системой
from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient
credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)
Конфигурация облака
Учетные данные по умолчанию — проверка подлинности в конечной точке Azure AD для общедоступного облака Azure. Чтобы получить доступ к ресурсам в других облаках, таких как Azure для государственных организаций или частное облако, настройте учетные данные с помощью аргумента authority . AzureAuthorityHosts определяет центры сертификации для известных облаков:
from azure.identity import AzureAuthorityHosts
DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)
Если центр для облака отсутствует в AzureAuthorityHostsсписке , можно явно указать его URL-адрес:
DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")
Вместо указания аргумента authority можно также задать для переменной AZURE_AUTHORITY_HOST среды URL-адрес центра облака. Этот подход полезен при настройке нескольких учетных данных для проверки подлинности в одном облаке:
AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn
Не все учетные данные требуют такой конфигурации. Учетные данные, которые проходят проверку подлинности с помощью средства разработки, например AzureCliCredential, используют конфигурацию этого средства. Аналогичным образом принимает authority аргумент , VisualStudioCodeCredential но по умолчанию используется центр, соответствующий параметру VS Code "Azure: Облако".
Классы учетных данных
Проверка подлинности приложений, размещенных в Azure
| Учетные данные | Использование |
|---|---|
DefaultAzureCredential |
Предоставляет упрощенный интерфейс проверки подлинности для быстрого начала разработки приложений, работающих в Azure. |
ChainedTokenCredential |
Позволяет пользователям определять пользовательские потоки проверки подлинности, состоящие из нескольких учетных данных. |
EnvironmentCredential |
Проверяет подлинность субъекта-службы или пользователя с помощью информации об учетных данных, указанной в переменных среды. |
ManagedIdentityCredential |
Проверяет подлинность управляемого удостоверения ресурса Azure. |
WorkloadIdentityCredential |
Поддерживает Azure AD удостоверения рабочей нагрузки в Kubernetes. |
Проверка подлинности субъектов-служб
| Учетные данные | Использование | Ссылка |
|---|---|---|
CertificateCredential |
Проверяет подлинность субъекта-службы с помощью сертификата. | Проверка подлинности субъекта-службы |
ClientAssertionCredential |
Выполняет проверку подлинности субъекта-службы с помощью подписанного утверждения клиента. | |
ClientSecretCredential |
Проверяет подлинность субъекта-службы с помощью секрета. | Проверка подлинности субъекта-службы |
Аутентификация пользователей
| Учетные данные | Использование | Ссылка |
|---|---|---|
AuthorizationCodeCredential |
Выполняет проверку подлинности пользователя с помощью ранее полученного кода авторизации. | Код проверки подлинности OAuth2 |
DeviceCodeCredential |
Интерактивно проверяет подлинность пользователя на устройстве с помощью ограниченного пользовательского интерфейса. | аутентификация с помощью кода устройства; |
InteractiveBrowserCredential |
Интерактивно проверяет подлинность пользователя с помощью системного браузера по умолчанию. | Код проверки подлинности OAuth2 |
OnBehalfOfCredential |
Распространяет делегированное удостоверение пользователя и разрешения через цепочку запросов. | Проверка подлинности от имени |
UsernamePasswordCredential |
Выполняет проверку подлинности пользователя с помощью имени пользователя и пароля (не поддерживает многофакторную проверку подлинности). | Проверка подлинности по имени пользователя и паролю |
Проверка подлинности с помощью средств разработки
| Учетные данные | Использование | Ссылка |
|---|---|---|
AzureCliCredential |
Выполняет проверку подлинности в среде разработки с помощью Azure CLI. | Проверка подлинности Azure CLI |
AzureDeveloperCliCredential |
Выполняет проверку подлинности в среде разработки с помощью Azure Developer CLI. | Справочник по Azure Developer CLI |
AzurePowerShellCredential |
Выполняет проверку подлинности в среде разработки с помощью Azure PowerShell. | проверка подлинности Azure PowerShell |
VisualStudioCodeCredential |
Выполняет проверку подлинности как пользователь, вошедшего в расширение учетной записи Azure Visual Studio Code. | расширение VS Code для учетной записи Azure. |
Переменные среды
DefaultAzureCredential и EnvironmentCredential можно настроить с помощью переменных среды. Для каждого типа проверки подлинности требуются значения конкретных переменных:
Субъект-служба с секретом
| Имя переменной | Значение |
|---|---|
AZURE_CLIENT_ID |
Идентификатор приложения Azure AD |
AZURE_TENANT_ID |
Идентификатор клиента Azure AD приложения |
AZURE_CLIENT_SECRET |
Один из секретов клиента приложения |
Субъект-служба с сертификатом
| Имя переменной | Значение |
|---|---|
AZURE_CLIENT_ID |
Идентификатор приложения Azure AD |
AZURE_TENANT_ID |
Идентификатор клиента Azure AD приложения |
AZURE_CLIENT_CERTIFICATE_PATH |
путь к файлу сертификата PEM или PKCS12, включая закрытый ключ |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
пароль файла сертификата, если он есть |
Имя пользователя и пароль
| Имя переменной | Значение |
|---|---|
AZURE_CLIENT_ID |
Идентификатор приложения Azure AD |
AZURE_USERNAME |
Имя пользователя (обычно это адрес электронной почты) |
AZURE_PASSWORD |
Пароль пользователя |
Настройка выполняется в указанном порядке. Например, если заданы значения секрета клиента и сертификата, будет использоваться секрет клиента.
Кэширование маркеров
Кэширование маркеров — это функция, предоставляемая библиотекой удостоверений Azure, которая позволяет приложениям:
- Кэшировать маркеры в памяти (по умолчанию) или на диске (согласие).
- Повышение устойчивости и производительности.
- Сократите количество запросов, выполняемых Azure AD для получения маркеров доступа.
Библиотека удостоверений Azure предлагает кэширование как в памяти, так и постоянное кэширование дисков. Дополнительные сведения см. в документации по кэшированию маркеров.
Устранение неполадок
Дополнительные сведения о диагностике различных сценариев сбоя см. в руководстве по устранению неполадок .
Обработка ошибок
Учетные данные возникают CredentialUnavailableError , если не удается выполнить проверку подлинности из-за отсутствия необходимых данных или состояния. Например, EnvironmentCredential вызовет это исключение, если является неполной.
Учетные данные генерируют azure.core.exceptions.ClientAuthenticationError, если им не удается выполнить проверку подлинности. ClientAuthenticationErrormessage имеет атрибут , который описывает причину сбоя проверки подлинности. При вызове DefaultAzureCredential или ChainedTokenCredentialсообщение собирает сообщения об ошибках из всех учетных данных в цепочке.
Дополнительные сведения об обработке конкретных ошибок Azure AD см. в документации по коду ошибки Azure AD.
Ведение журнала
Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Учетные данные регистрируют основные сведения, включая сеансы HTTP (URL-адреса, заголовки и т. д.) на уровне INFO. Эти записи журнала не содержат секреты проверки подлинности.
Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и значения заголовков, по умолчанию не включено. Его можно включить с помощью аргумента logging_enable . Пример:
credential = DefaultAzureCredential(logging_enable=True)
ВНИМАНИЕ! Журналы уровня ОТЛАДКИ из учетных данных содержат конфиденциальную информацию. Эти журналы должны быть защищены, чтобы избежать угрозы безопасности учетной записи.
Дальнейшие действия
Поддержка клиентских библиотек
Клиентские библиотеки и библиотеки управления, перечисленные на странице выпуска azure SDK, которые поддерживают проверку подлинности Azure AD принимают учетные данные из этой библиотеки. Дополнительные сведения об использовании этих библиотек см. в документации, связанной со страницей выпуска.
Известные проблемы
Эта библиотека не поддерживает Azure AD B2C.
Сведения о других открытых проблемах см. в репозитории библиотеки GitHub.
Предоставление отзыва
Если вы столкнулись с ошибками или у вас есть предложения, откройте проблему.
Участие
На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Для получения подробных сведений посетите веб-страницу https://cla.microsoft.com.
При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Это необходимо сделать только один раз во всех репозиториях с помощью нашего CLA.
В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения: Вопросы и ответы по правилам поведения. С любыми другими вопросами или комментариями обращайтесь по адресу opencode@microsoft.com.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по