Python 從 ADAL 遷移到 MSAL 的指南

本文重點說明，將使用 Azure Active Directory 認證庫（ADAL）的應用程式遷移至 Microsoft 驗證資源庫（MSAL）時，你需要做的變更。

你可以進一步了解 MSAL，並從 適用於 Python 的 Microsoft 驗證程式庫 的概述開始。

差異亮點

ADAL 可與 Azure Active Directory （Azure AD） v1.0 端點運作。 Microsoft 驗證資源庫（MSAL）可與 Microsoft 身分識別平台搭配運作；該平台先前稱為 Azure Active Directory v2.0 端點。 Microsoft 身分識別平台 與 Azure AD v1.0 的不同之處在於：

支援：

  • 工作與學校帳號（Microsoft Entra ID 配置帳號）

  • 個人帳號（例如 Outlook.com 或 Hotmail.com）

  • 那些透過 Azure AD B2C 服務帶來電子郵件或社交身份（例如 LinkedIn、Facebook、Google）的客戶

  • 標準是否相容於：

    • OAuth v2.0
    • OpenID Connect（OIDC）

欲了解更多MSAL資訊，請參閱 MSAL總覽。

範圍而非資源

ADAL Python 會取得資源的標記，但 MSAL Python 則是取得範圍的標記。 MSAL Python 的 API 表面已經沒有資源參數了。 你需要以字串列表的形式提供範圍，用來宣告所需的權限和請求的資源。 想看一些範圍的範例，請參考 Microsoft Graph 的範圍。

你可以在資源中加上/.default範圍後綴，幫助將應用程式從 v1.0 端點（ADAL）遷移到 Microsoft 身分識別平台（MSAL）。 例如，對於資源 https://graph.microsoft.com值，等效的範圍值為 https://graph.microsoft.com/.default。 如果資源不在 URL 表單中，而是表單 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX的資源 ID，你仍然可以使用範圍值為 XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default。

關於不同類型範圍的更多細節，請參閱 Microsoft 身分識別平台 中的權限與同意，以及 Scopes for a Web API accepting v1.0 tokens 文章。

錯誤處理

Python 的 ADAL 會用例外AdalError來表示有問題。 Python 的 MSAL 通常會改用錯誤碼。 欲了解更多資訊，請參閱 MSAL 中的 Python 錯誤處理。

API 變更

下表列出 Python ADAL 中的 API，以及 MSAL for Python 中應使用的 API：

ADAL for Python API MSAL for Python API
認證上下文 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 擴充套件取得

遷移現有的刷新權杖以支援 MSAL Python

MSAL 抽象化了刷新代幣的概念。 MSAL Python 預設提供記憶體內的 token 快取，讓你不需要儲存、查找或更新刷新 token。 使用者也會看到較少的登入提示，因為刷新令牌通常可以在無需使用者介入的情況下更新。 欲了解更多關於令牌快取的資訊，請參閱 Python MSAL 中的自訂令牌快取序列化。

以下程式碼將協助你將由另一個 OAuth2 函式庫（包括但不限於 ADAL Python）管理的刷新令牌遷移到由 MSAL for Python 管理。 遷移這些刷新權杖的一個原因是避免現有用戶在你將應用程式遷移到 Python MSAL 時再次登入。

遷移刷新權杖的方法是使用 MSAL for Python，利用先前的刷新權杖取得新的存取權杖。 當新的刷新令牌回傳時，Python 的 MSAL 會將其儲存在快取中。 自 MSAL Python 1.3.0 起，我們在 MSAL 內部提供了 API 以達成此目的。 請參考以下程式碼片段，摘自一份完成的 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