Migreringsguide för ADAL till MSAL för Python

Den här artikeln belyser ändringar som du behöver göra för att migrera en app som använder ADAL (Azure Active Directory Authentication Library) för att använda Microsofts autentiseringsbibliotek (MSAL).

Du kan lära dig mer om MSAL och komma igång med en översikt över Microsoft-autentiseringsbibliotek för Python.

Skillnadshöjdpunkter

ADAL fungerar med slutpunkten Azure Active Directory (Azure AD) v1.0. Microsofts autentiseringsbibliotek (MSAL) fungerar med Microsofts identitetsplattform som tidigare kallades Azure Active Directory v2.0-slutpunkt. Microsofts identitetsplattform skiljer sig från Azure AD v1.0 genom att den:

Stöder:

• Arbets- och skolkonton (Microsoft Entra ID etablerade konton)

• Personliga konton (till exempel Outlook.com eller Hotmail.com)

• Dina kunder som tar med sig sin egen e-post eller sociala identitet (till exempel LinkedIn, Facebook, Google) via Azure AD B2C-erbjudandet

• Är standarder kompatibla med:

  • OAuth v2.0
  • OpenID Connect (OIDC)

Mer information om MSAL finns i MSAL-översikt.

Omfång, inte resurser

ADAL Python hämtar token för resurser, men MSAL Python hämtar token för omfång. API-ytan i MSAL Python har inte resursparameter längre. Du skulle behöva ange omfång som en lista över strängar som deklarerar önskade behörigheter och resurser som begärs. Om du vill se några exempel på behörighetsomfång, se Microsoft Graphs behörighetsomfång.

Du kan lägga till omfångssuffixet /.default i resursen för att migrera dina appar från V1.0-slutpunkten (ADAL) till Microsofts identitetsplattform (MSAL). För resursvärdet https://graph.microsoft.comför är till exempel motsvarande omfångsvärde https://graph.microsoft.com/.default. Om resursen inte finns i URL-formuläret, men ett resurs-ID i formuläret XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, kan du fortfarande använda omfångsvärdet som XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Mer information om de olika typerna av omfång finns i artiklarna Behörigheter och medgivande på Microsofts identitetsplattform och Omfång för ett webb-API som accepterar v1.0-token.

Felhantering

ADAL för Python använder undantaget AdalError för att indikera att det har uppstått ett problem. MSAL för Python använder vanligtvis felkoder i stället. Mer information finns i MSAL för Python felhantering.

API-ändringar

I följande tabell visas ett API i ADAL för Python och det som ska användas i msal för Python:

Migrera befintliga uppdateringstokenar för MSAL Python

MSAL abstraherar begreppet uppdateringstoken. MSAL-Python tillhandahåller en minnesintern tokencache som standard så att du inte behöver lagra, söka efter eller uppdatera uppdateringstoken. Användarna ser också färre inloggningsprompter eftersom uppdateringstoken vanligtvis kan uppdateras utan användarintervention. Mer information om tokencachen finns i Custom token cache serialization in MSAL for Python (Anpassad tokencache-serialisering i MSAL för Python.

Följande kod hjälper dig att migrera dina uppdateringstoken som hanteras av ett annat OAuth2-bibliotek (inklusive men inte begränsat till ADAL-Python) som ska hanteras av MSAL för Python. En anledning till att migrera dessa uppdateringstoken är att förhindra att befintliga användare behöver logga in igen när du migrerar appen till MSAL för Python.

Metoden för att migrera en uppdateringstoken är att använda MSAL för Python för att hämta en ny åtkomsttoken med hjälp av den tidigare uppdateringstoken. När den nya uppdateringstoken returneras lagrar MSAL för Python den i cacheminnet. Eftersom MSAL Python 1.3.0 tillhandahåller vi ett API i MSAL för detta ändamål. Se följande kodfragment, som citeras från ett slutfört exempel på migrering av uppdateringstoken med 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://dotnet.territoriali.olinfo.it/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://dotnet.territoriali.olinfo.it/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")