Microsoft Authentication Library (MSAL) для Python

Библиотека Microsoft Authentication Library (MSAL) для Python позволяет пользователям и приложениям входить с использованием удостоверений Майкрософт (Microsoft Entra ID, Microsoft Accounts и учетных записей Microsoft Entra ID). С помощью MSAL Python вы можете получить маркеры из Microsoft Entra ID для вызова защищенных веб-API, таких как Microsoft Graph, другие Microsoft API или собственные API.

Необходимые условия

• Учетная запись Azure с активной подпиской. Создайте бесплатную учетную запись.
• Python 3.6 и выше.

Установите пакет

Установите MSAL для пакета Python. Вы можете найти MSAL Python на PyPI.

pip install msal

Понятия идентичности

MSAL Python является частью экосистемы платформа удостоверений Майкрософт. Ознакомьтесь со следующими понятиями, чтобы эффективно использовать MSAL Python для защиты приложений и API:

• Управление удостоверениями и доступом
• Проверка подлинности и авторизация
• OAuth 2.0 и OpenID Connect (OIDC) на платформе идентификации Майкрософт
• Конфиденциальные и общедоступные учетные записи клиентов в платформа удостоверений Майкрософт
• Маркеры безопасности

Сценарии использования

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

Приложения могут использовать MSAL Python для получения маркеров для доступа к защищенным API. Различные типы приложений получают маркеры с помощью различных потоков проверки подлинности. Поддерживаемые типы приложений включают классические приложения, веб-приложения, веб-API и приложения, работающие на устройствах без браузера (например, устройства Интернета вещей).

В MSAL Python приложения классифицируются следующим образом:

• Общедоступные клиентские приложения (классические и мобильные приложения). Эти типы приложений не могут безопасно хранить секреты приложений.
• Конфиденциальные клиентские приложения (веб-приложения, веб-API и приложения управляющей программы). Эти типы приложений безопасно хранят секрет, зарегистрированный в Microsoft Entra ID.

Дополнительные сведения см. в документации по общедоступным клиентским и конфиденциальным клиентским приложениям и различным типам приложений и их потокам проверки подлинности в платформа удостоверений Майкрософт.

Определив, является ли ваше приложение общедоступным или конфиденциальным клиентским приложением, можно использовать MSAL Python для получения маркеров для различных сценариев.

Основное использование

Получение токенов с помощью MSAL Python выполняется по трехэтапной схеме. Существуют некоторые варианты для разных потоков. Если вы хотите увидеть их в действии, скачайте наши примеры.

1. MSAL использует чистое разделение между общедоступным клиентом и конфиденциальными клиентскими приложениями. Поэтому создайте экземпляр PublicClientApplication или ConfidentialClientApplication и повторно используйте его на протяжении жизненного цикла приложения. Например, для общедоступного клиентского приложения код инициализации может выглядеть следующим образом:

   from msal import PublicClientApplication
   
   app = PublicClientApplication(
       "your_client_id",
       authority="https://login.microsoftonline.com/common")
   

   Значение параметра authority зависит от типа учетных записей, с помощью которых вы входите в систему, и от типа арендатора, в котором зарегистрировано ваше приложение. Например, для входа в рабочие и личные учетные записи Microsoft, подготовленные в арендаторах Workforce (Microsoft Entra ID), следует использовать https://login.microsoftonline.com/common. Для учетных записей клиентов, созданных в клиентских арендаторах, ваш орган будет иметь вид https://<subdomain>.ciamlogin.com. Дополнительные сведения см. в документации издателя токенов.

2. Сначала попробуйте получить маркеры из кэша. Модель API в MSAL предоставляет вам непосредственный контроль над тем, как использовать кэш токенов. Хотя часть кэширования технически необязательна, мы настоятельно рекомендуем использовать ее в приложении. Используя кэш, вы можете убедиться, что вы не выполняете никаких дополнительных вызовов API и автоматически обрабатываете обновление маркера.

   # initialize result variable to hole the token response
   result = None 
   
   # We now check the cache to see
   # whether we already have some accounts that the end user already used to sign in before.
   accounts = app.get_accounts()
   if accounts:
       # If so, you could then somehow display these accounts and let end user choose
       print("Pick the account you want to use to proceed:")
       for a in accounts:
           print(a["username"])
       # Assuming the end user chose this one
       chosen = accounts[0]
       # Now let's try to find a token in cache for this account
       result = app.acquire_token_silent(["User.Read"], account=chosen)
   

3. Если в кэше нет подходящего маркера или вы решили пропустить предыдущий шаг, отправьте запрос на Microsoft Entra ID, чтобы получить маркер. Существуют различные методы, основанные на типе клиента и сценарии, но в целях примера мы показываем, как использовать acquire_token_interactive, что предложит пользователю предоставить свои учетные данные.

   if not result:
       # So no suitable token exists in cache. Let's get a new one from Azure AD.
       result = app.acquire_token_interactive(scopes=["User.Read"])
   if "access_token" in result:
       print(result["access_token"])  # Yay!
   else:
       print(result.get("error"))
       print(result.get("error_description"))
       print(result.get("correlation_id"))  # You may need this when reporting a bug
   

4. Сохраните код в файл Python локально, например msaltest.py.

5. Запустите код, выполнив python .\msalpytest.py. На следующем изображении показан процесс входа для этого примера.

   

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

Рекомендации по созданию надежного корпоративного готового приложения

Маркер для защищенного веб-API можно получить с помощью MSAL Python. Вам также не нужно самостоятельно заниматься обновлением токенов. Однако для создания надежных корпоративных готовых приложений потребуется немного больше. Например, вам потребуется:

• Обрабатывайте исключения как при получении токена, так и при вызове защищённого веб-API. В частности, если приложение выполняется в клиенте Microsoft Entra, где администраторы клиента установили политики условного доступа для применения многофакторной проверки подлинности (MFA), вам потребуется выполнить задачу утверждения.

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

Samples

Существует несколько примеров, которые можно использовать для начала работы с MSAL Python.

• Примеры из репозитория библиотеки. В этих примерах показаны различные конфигурации и потоки проверки подлинности, которые вы реализуете с помощью MSAL Python.
• Один репозиторий с примерами, используемыми в нашей документации. К этим примерам прилагается сопроводительная документация, которая поможет вам создать и воспроизвести их с нуля.

References

• Репозиторий библиотеки MSAL Python на GitHub
• Выпуски MSAL Python на GitHub.

См. также

• Создание экземпляра приложения с помощью MSAL Python
• Получение токенов с помощью MSAL Python