Руководство по миграции ADAL в MSAL для Python

В этой статье рассматриваются изменения, необходимые для переноса приложения, использующего библиотеку проверки подлинности Azure Active Directory (ADAL) для использования Microsoft Authentication Library (MSAL).

Вы можете узнать больше о MSAL и начать работу, ознакомившись с обзором Microsoft Authentication Library для Python.

Основные моменты различий

ADAL работает с конечной точкой Azure Active Directory (Azure AD) версии 1.0. Библиотека Microsoft Authentication Library (MSAL) работает с платформой платформа удостоверений Майкрософт — ранее известной как конечная точка Azure Active Directory v2.0. платформа удостоверений Майкрософт отличается от Azure AD версии 1.0 в этом:

Поддерживает:

  • Рабочие или учебные учётные записи (учётные записи, подготовленные в Microsoft Entra ID)

  • Личные учетные записи (например, Outlook.com или Hotmail.com)

  • Ваши клиенты, которые используют собственный адрес электронной почты или учетную запись в социальной сети (например, LinkedIn, Facebook, Google) через Azure AD B2C

  • Совместимы ли стандарты со следующими стандартами:

    • OAuth версии 2.0
    • OpenID Connect (OIDC)

Дополнительные сведения о MSAL см. в обзоре MSAL.

Области, а не ресурсы

ADAL Python получает маркеры для ресурсов, но MSAL Python получает маркеры для областей. Область API в MSAL Python больше не имеет параметра ресурса. Необходимо указать области в виде списка строк, которые объявляют требуемые разрешения и ресурсы. Чтобы просмотреть некоторые примеры областей, ознакомьтесь с областями Microsoft Graph.

Вы можете добавить к ресурсу суффикс области /.default, чтобы упростить миграцию ваших приложений с конечной точки v1.0 (ADAL) на платформу удостоверений Майкрософт (MSAL). Например, значению ресурса https://graph.microsoft.com соответствует эквивалентное значение области https://graph.microsoft.com/.default. Если ресурс представлен не в форме URL, а в виде идентификатора ресурса формата XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, вы всё равно можете использовать значение scope в виде XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Дополнительные сведения о различных типах областей см. в статьях «Разрешения и согласие на платформе идентификации Microsoft» и «Области для веб-API, принимающего токены v1.0».

Обработка ошибок

ADAL для Python использует исключениеAdalError, указывающее, что возникла проблема. MSAL для Python обычно использует коды ошибок. Дополнительные сведения см. в MSAL для обработки ошибок Python.

Изменения API

В следующей таблице перечислены API в ADAL для Python и тот, который будет использоваться в MSAL для Python:

ADAL для API Python MSAL для API Python
AuthenticationContext PublicClientApplication или ConfidentialClientApplication
N/A acquire_token_interactive
N/A get_authorization_request_url
N/A initiate_auth_code_flow
acquire_token_with_authorization_code() acquire_token_by_auth_code_flow
acquire_token() acquire_token_silent
acquire_token_with_refresh_token() Эти два вспомогательных средства предназначены только для использования во время миграции : acquire_token_by_refresh_token
acquire_user_code() initiate_device_flow
acquire_token_with_device_code() и cancel_request_to_get_token_with_device_code() acquire_token_by_device_flow
acquire_token_with_username_password() acquire_token_by_username_password
acquire_token_with_client_credentials() и acquire_token_with_client_certificate() acquire_token_for_client
N/A acquire_token_on_behalf_of
TokenCache() SerializableTokenCache
N/A Кэш с постоянным хранением, доступный в MSAL Extensions

Перенос существующих токенов обновления для MSAL Python

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

Приведённый ниже код поможет вам перенести токены обновления, которые в настоящее время обрабатываются другой библиотекой OAuth2 (включая, помимо прочего, ADAL Python), под управление MSAL for Python. Одной из причин переноса этих маркеров обновления является предотвращение повторного входа существующих пользователей при переносе приложения в MSAL для Python.

Способ переноса маркера обновления заключается в использовании MSAL для Python, чтобы получить новый маркер доступа с помощью предыдущего маркера обновления. Когда возвращается новый маркер обновления, MSAL для Python сохраняет его в кэше. Начиная с версии 1.3.0 библиотеки MSAL Python, мы предоставляем API в MSAL для этой цели. См. следующий фрагмент кода, процитированный из готового примера миграции токенов обновления с помощью MSAL Python

import msal
def get_preexisting_rt_and_their_scopes_from_elsewhere():
    # Maybe you have an ADAL-powered app like this
    #   https://github.com/AzureAD/azure-activedirectory-library-for-python/blob/1.2.3/sample/device_code_sample.py#L72
    # which uses a resource rather than a scope,
    # you need to convert your v1 resource into v2 scopes
    # See https://learn.microsoft.com/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources
    # You may be able to append "/.default" to your v1 resource to form a scope
    # See https://learn.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#the-default-scope

    # Or maybe you have an app already talking to the Microsoft identity platform,
    # powered by some 3rd-party auth library, and persist its tokens somehow.

    # Either way, you need to extract RTs from there, and return them like this.
    return [
        ("old_rt_1", ["scope1", "scope2"]),
        ("old_rt_2", ["scope3", "scope4"]),
        ]


# We will migrate all the old RTs into a new app powered by MSAL
app = msal.PublicClientApplication(
    "client_id", authority="...",
    # token_cache=...  # Default cache is in memory only.
                       # You can learn how to use SerializableTokenCache from
                       # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache
    )

# We choose a migration strategy of migrating all RTs in one loop
for old_rt, scopes in get_preexisting_rt_and_their_scopes_from_elsewhere():
    result = app.acquire_token_by_refresh_token(old_rt, scopes)
    if "error" in result:
        print("Discarding unsuccessful RT. Error: ", json.dumps(result, indent=2))

print("Migration completed")
  • Last updated on