Migratiehandleiding voor ADAL naar MSAL voor Python

In dit artikel worden de wijzigingen beschreven die u moet aanbrengen om een app te migreren die gebruikmaakt van de Azure Active Directory Authentication Library (ADAL) om de Microsoft Authentication Library (MSAL) te gebruiken.

U kunt meer informatie over MSAL vinden en aan de slag gaan met een overzicht van de Microsoft Authentication Library voor Python.

Gemarkeerde verschillen

ADAL werkt met het eindpunt Azure Active Directory (Azure AD) v1.0. De Microsoft Authentication Library (MSAL) werkt met het Microsoft identity platform-voorheen bekend als het Azure Active Directory v2.0-eindpunt. Het Microsoft identity platform verschilt van Azure AD v1.0 op de volgende punten:

Ondersteunt:

  • Werk- en schoolaccounts (accounts die zijn ingericht in Microsoft Entra ID)

  • Persoonlijke accounts (zoals Outlook.com of Hotmail.com)

  • Uw klanten die hun eigen e-mail of sociale identiteit (zoals LinkedIn, Facebook, Google) meenemen via de Azure AD B2C-aanbieding

  • Is standaarden compatibel met:

    • OAuth v2.0
    • OpenID Connect (OIDC)

Zie MSAL-overzicht voor meer informatie over MSAL.

Machtigingen, geen bronnen

ADAL Python verkrijgt tokens voor resources, maar MSAL Python verkrijgt tokens voor scopes. Het API-oppervlak in MSAL Python heeft geen resourceparameter meer. U moet scopes opgeven als een lijst met strings die de gewenste machtigingen en resources specificeren waarvoor toegang wordt aangevraagd. Zie de scopes van Microsoft Graph voor enkele voorbeelden van scopes.

U kunt het /.default scope-achtervoegsel toevoegen aan de resource om uw apps te helpen migreren van het v1.0-eindpunt (ADAL) naar het Microsoft identity platform (MSAL). Bijvoorbeeld, voor de resourcewaarde van https://graph.microsoft.com is de equivalente scopewaarde https://graph.microsoft.com/.default. Als de resource niet de URL-indeling heeft, maar een resource-id in de vorm van XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, kunt u de scopewaarde nog steeds gebruiken als XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Raadpleeg Machtigingen en toestemming in het Microsoft-identiteitsplatform en het artikel Scopes voor een web-API die v1.0-tokens accepteert voor meer informatie over de verschillende typen scopes.

Foutafhandeling

ADAL voor Python gebruikt de uitzondering AdalError om aan te geven dat er een probleem is opgetreden. MSAL voor Python gebruikt doorgaans foutcodes. Zie MSAL voor Python foutafhandeling voor meer informatie.

API-wijzigingen

De volgende tabel bevat een API in ADAL voor Python en de API die moet worden gebruikt in MSAL voor Python:

ADAL voor Python-API MSAL voor Python-API
AuthenticationContext PublicClientApplication of 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() Deze twee helpers zijn alleen bedoeld om te worden gebruikt tijdens de migratie : acquire_token_by_refresh_token
acquire_user_code() initiate_device_flow
acquire_token_with_device_code() en 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() en acquire_token_with_client_certificate() acquire_token_for_client
N/A acquire_token_on_behalf_of
TokenCache() SerializableTokenCache
N/A Cache met persistentie, beschikbaar via MSAL-extensies

Bestaande refresh-tokens migreren voor MSAL Python

MSAL abstraheert het concept van vernieuwingstokens. MSAL Python biedt standaard een in-memory tokencache, zodat u geen vernieuwingstokens hoeft op te slaan, op te zoeken of bij te werken. Gebruikers zien ook minder aanmeldingsprompts omdat vernieuwingstokens meestal kunnen worden bijgewerkt zonder tussenkomst van de gebruiker. Zie Aangepaste tokencacheserialisatie in MSAL voor Python voor meer informatie over de tokencache.

De volgende code helpt u bij het migreren van uw vernieuwingstokens die worden beheerd door een andere OAuth2-bibliotheek (inclusief maar niet beperkt tot ADAL-Python) die worden beheerd door MSAL voor Python. Een van de redenen voor het migreren van deze vernieuwingstokens is om te voorkomen dat bestaande gebruikers zich opnieuw moeten aanmelden wanneer u uw app migreert naar MSAL voor Python.

De methode voor het migreren van een vernieuwingstoken is het gebruik van MSAL voor Python om een nieuw toegangstoken te verkrijgen met behulp van het vorige vernieuwingstoken. Wanneer het nieuwe vernieuwingstoken wordt geretourneerd, slaat MSAL voor Python het in de cache op. Sinds MSAL Python 1.3.0, bieden we hiervoor een API in MSAL. Raadpleeg het volgende codefragment, geciteerd uit een volledig uitgewerkt voorbeeld van het migreren van refresh-tokens met 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