Leitfaden zur Migration von ADAL zu MSAL für Python

In diesem Artikel werden änderungen erläutert, die Sie zum Migrieren einer App vornehmen müssen, die die Azure Active Directory Authentication Library (ADAL) verwendet, um die Microsoft Authentication Library (MSAL) (MSAL) zu verwenden.

Erfahren Sie mehr über MSAL und beginnen Sie mit einem Überblick über die Microsoft Authentication Library für Python.

Hervorhebungen von Unterschieden

ADAL funktioniert mit dem Azure Active Directory (Azure AD) v1.0-Endpunkt. Die Microsoft Authentication Library (MSAL) (MSAL) arbeitet mit der Microsoft Identity Platform – ehemals bekannt als Azure Active Directory v2.0-Endpunkt. Die Microsoft Identity Platform unterscheidet sich von Azure AD v1.0 darin:

Unterstützt:

• Geschäfts- und Schulkonten (Microsoft Entra ID bereitgestellte Konten)

• Persönliche Konten (z. B. Outlook.com oder Hotmail.com)

• Ihre Kunden, die ihre eigene E-Mail oder soziale Identität (z. B. LinkedIn, Facebook, Google) über das Azure AD B2C-Angebot mitbringen

• Ist Standards kompatibel mit:

  • OAuth v2.0
  • OpenID Connect (OIDC)

Weitere Informationen zu MSAL finden Sie in der MSAL-Übersicht.

Bereiche, keine Ressourcen

ADAL Python fordert Token für Ressourcen an, aber MSAL Python fordert Token für Berechtigungsbereiche an. Die API-Oberfläche in MSAL Python verfügt nicht mehr über einen Ressourcenparameter. Sie müssen Bereiche als Liste von Zeichenfolgen bereitstellen, die die gewünschten Berechtigungen und Ressourcen deklarieren, die angefordert werden. Einige Beispiele für Berechtigungsbereiche finden Sie unter den Berechtigungsbereichen von Microsoft Graph.

Sie können das Bereichsuffix /.default der Ressource hinzufügen, um Ihre Apps vom v1.0-Endpunkt (ADAL) zum Microsoft Identity Platform (MSAL) zu migrieren. Beispielsweise ist für den Ressourcenwert https://graph.microsoft.com der entsprechende Bereichswert https://graph.microsoft.com/.default. Wenn die Ressource nicht als URL vorliegt, sondern als Ressourcen-ID der Form XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, können Sie den Bereichswert dennoch als XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default verwenden.

Weitere Informationen zu den verschiedenen Arten von Bereichen finden Sie in den Artikeln "Berechtigungen" und "Zustimmung" im Microsoft Identity Platform und den Bereichen für eine Web-API, die v1.0-Token-Artikel akzeptiert.

Fehlerbehandlung

ADAL für Python verwendet die AusnahmeAdalError, um anzugeben, dass ein Problem aufgetreten ist. MSAL für Python verwendet stattdessen in der Regel Fehlercodes. Weitere Informationen finden Sie unter MSAL für Python Fehlerbehandlung.

API-Änderungen

In der folgenden Tabelle sind eine API in ADAL für Python sowie die API aufgeführt, die stattdessen in MSAL für Python verwendet werden sollte:

Vorhandene Aktualisierungstoken für MSAL Python migrieren

MSAL abstrahiert das Konzept von Aktualisierungstoken. MSAL Python stellt standardmäßig einen Cache für In-Memory-Token bereit, sodass Sie keine Aktualisierungstoken speichern, suchen oder aktualisieren müssen. Benutzern werden auch weniger Anmeldeaufforderungen angezeigt, da Aktualisierungstoken normalerweise ohne Benutzereingriff aktualisiert werden können. Weitere Informationen zum Tokencache finden Sie unter Serialisierung des benutzerdefinierten Tokencaches in MSAL für Python.

Der folgende Code hilft Ihnen dabei, Ihre von einer anderen OAuth2-Bibliothek verwalteten Refresh Tokens (einschließlich, aber nicht beschränkt auf ADAL Python) so zu migrieren, dass sie von MSAL für Python verwaltet werden. Ein Grund für die Migration dieser Aktualisierungstoken besteht darin, zu verhindern, dass sich vorhandene Benutzer erneut anmelden müssen, wenn Sie Ihre App für Python zu MSAL migrieren.

Die Methode zum Migrieren eines Aktualisierungstokens besteht darin, MSAL für Python zum Abrufen eines neuen Zugriffstokens mithilfe des vorherigen Aktualisierungstokens zu verwenden. Wenn das neue Aktualisierungstoken zurückgegeben wird, speichert MSAL für Python es im Cache. Seit MSAL Python 1.3.0 stellen wir hierfür eine API innerhalb von MSAL bereit. Bitte lesen Sie den folgenden Codeausschnitt, zitiert aus einem abgeschlossenen Beispiel für die Migration von Aktualisierungstoken mit 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")