Guida alla migrazione da ADAL a MSAL per Python

In questo articolo vengono evidenziate le modifiche necessarie per eseguire la migrazione di un'app che usa Azure Active Directory Authentication Library (ADAL) per usare il Libreria di Autenticazione Microsoft (MSAL).

Puoi saperne di più su MSAL e iniziare con una panoramica della libreria di autenticazione Microsoft per Python.

Evidenziazioni delle differenze

ADAL funziona con l'endpoint Azure Active Directory (Azure AD) v1.0. La Libreria di Autenticazione Microsoft (MSAL) funziona con la piattaforma di identità Microsoft, precedentemente nota come endpoint di Azure Active Directory v2.0. Il Microsoft Identity Platform differisce da Azure AD v1.0 in quanto:

Supporta:

• Account aziendali o dell'istituto di istruzione (account di cui è stato effettuato il provisioning in Microsoft Entra ID)

• Account personali (ad esempio Outlook.com o Hotmail.com)

• I tuoi clienti che usano il proprio indirizzo e-mail o un'identità social (ad esempio LinkedIn, Facebook, Google) con Azure AD B2C

• Gli standard sono compatibili con:

  • OAuth v2.0
  • OpenID Connect (OIDC)

Per altre informazioni su MSAL, vedere Panoramica di MSAL.

Ambiti non risorse

ADAL Python acquisisce i token per le risorse, ma MSAL Python acquisisce i token per gli ambiti. L’interfaccia API di MSAL Python non include più il parametro resource. È necessario specificare gli ambiti come elenco di stringhe che dichiarano le autorizzazioni e le risorse desiderate richieste. Per alcuni esempi di ambiti, vedere ambiti di Microsoft Graph.

È possibile aggiungere il /.default suffisso di ambito alla risorsa per facilitare la migrazione delle app dall'endpoint v1.0 (ADAL) al Microsoft Identity Platform (MSAL). Ad esempio, per il valore della risorsa https://graph.microsoft.com, il valore di ambito equivalente è https://graph.microsoft.com/.default. Se la risorsa non è nel formato URL, ma un ID risorsa del modulo XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, è comunque possibile usare il valore di ambito come XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Per altre informazioni sui diversi tipi di ambiti, vedere Autorizzazioni e consenso negli articoli Microsoft Identity Platform e Ambiti per un'API Web che accetta i token v1.0.

Gestione degli errori

ADAL per Python usa l'eccezione AdalError per indicare che si è verificato un problema. MSAL per Python usa in genere codici di errore. Per altre informazioni, vedere MSAL per Python gestione degli errori.

Modifiche api

La tabella seguente elenca un'API in ADAL per Python e quella da usare al suo posto in MSAL per Python:

Eseguire la migrazione dei token di aggiornamento esistenti per MSAL Python

MSAL fa astrazione del concetto di token di aggiornamento. MSAL Python fornisce una cache dei token in memoria per impostazione predefinita, in modo che non sia necessario archiviare, cercare o aggiornare i token di aggiornamento. Gli utenti visualizzeranno anche un minor numero di richieste di accesso perché i token di aggiornamento possono in genere essere aggiornati senza l'intervento dell'utente. Per altre informazioni sulla cache dei token, vedere Serializzazione della cache dei token personalizzata in MSAL per Python.

Il codice seguente ti aiuterà a migrare i token di aggiornamento gestiti da un'altra libreria OAuth2 (incluse, a titolo esemplificativo ma non esaustivo, ADAL Python) in modo che siano gestiti da MSAL per Python. Uno dei motivi per eseguire la migrazione di tali token di aggiornamento consiste nel impedire agli utenti esistenti di eseguire di nuovo l'accesso quando si esegue la migrazione dell'app a MSAL per Python.

Il metodo per la migrazione di un token di aggiornamento consiste nell'usare MSAL per Python per acquisire un nuovo token di accesso usando il token di aggiornamento precedente. Quando viene restituito il nuovo token di aggiornamento, MSAL per Python lo archivierà nella cache. A partire da MSAL Python 1.3.0, forniamo un'API all'interno di MSAL a questo scopo. Fare riferimento al frammento di codice seguente, tratto da un esempio completo di migrazione dei token di aggiornamento con 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")