Guia de migração da ADAL para MSAL para Python

Este artigo destaca as alterações que você precisa fazer para migrar um aplicativo que usa a Biblioteca de Autenticação Azure Active Directory (ADAL) para usar o Biblioteca do Microsoft Authenticator (MSAL).

Você pode saber mais sobre a MSAL e começar a ter uma visão geral do Biblioteca de Autenticação da Microsoft para Python.

Destaques das diferenças

O ADAL funciona com o ponto de extremidade v1.0 do Azure Active Directory (Azure AD). A Biblioteca do Microsoft Authenticator (MSAL) funciona com a plataforma de identidade da Microsoft -- anteriormente conhecida como o ponto de extremidade do Azure Active Directory v2.0. O plataforma de identidade da Microsoft é diferente de Azure AD v1.0 no seguinte:

Suporta:

• Contas corporativas e escolares (contas provisionadas no Microsoft Entra ID)

• Contas pessoais (como Outlook.com ou Hotmail.com)

• Seus clientes que trazem seus próprios emails ou identidade social (como LinkedIn, Facebook, Google) por meio da oferta Azure AD B2C

• Os padrões são compatíveis com:

  • OAuth v2.0
  • OIDC (OpenID Connect)

Para obter mais informações sobre a MSAL, consulte a visão geral da MSAL.

Escopos não são recursos

A ADAL Python adquire tokens para recursos, mas a MSAL Python adquire tokens para escopos. A interface da API no MSAL Python não tem mais o parâmetro "resource". Você precisaria fornecer escopos como uma lista de cadeias de caracteres que declaram as permissões e recursos desejados solicitados. Para ver alguns exemplos de escopos, consulte os escopos do Microsoft Graph.

Você pode adicionar o sufixo de escopo /.default ao recurso para ajudar na migração dos seus aplicativos do endpoint v1.0 (ADAL) para a plataforma de identidade da Microsoft (MSAL). Por exemplo, para o valor do recurso https://graph.microsoft.com, o valor de escopo equivalente é https://graph.microsoft.com/.default. Se o recurso não estiver no formulário de URL, mas uma ID de recurso do formulário XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, você ainda poderá usar o valor de escopo como XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Para obter mais detalhes sobre os diferentes tipos de escopos, consulte Permissões e consentimento na plataforma de identidade da Microsoft e os artigos Escopos para uma API Web que aceita tokens v1.0.

Tratamento de erros

A ADAL para Python usa a exceção AdalError para indicar que houve um problema. MSAL for Python normalmente usa códigos de erro, em vez disso. Para obter mais informações, consulte MSAL para Python: tratamento de erros.

Alterações de API

A tabela a seguir lista uma API na ADAL para Python e a que será usada em seu lugar na MSAL para Python:

Migrar os tokens de atualização existentes para o MSAL Python

A MSAL abstrai o conceito de tokens de atualização. A MSAL Python fornece, por padrão, um cache de tokens em memória para que você não precise armazenar, localizar ou atualizar tokens de atualização. Os usuários também verão menos solicitações para iniciar sessão, porque os tokens de atualização geralmente podem ser atualizados sem a intervenção do usuário. Para obter mais informações sobre o cache de token, consulte Serialização de cache de token personalizado na MSAL para Python.

O código a seguir ajudará você a migrar seus tokens de atualização gerenciados por outra biblioteca OAuth2 (incluindo, mas não limitada a Python da ADAL) a ser gerenciada pela MSAL para Python. Um motivo para migrar esses tokens de atualização é impedir que os usuários existentes precisem entrar novamente quando você migrar seu aplicativo para a MSAL para Python.

O método para migrar um token de atualização é usar a MSAL para Python adquirir um novo token de acesso usando o token de atualização anterior. Quando o novo token de atualização for retornado, a MSAL para Python o armazenará no cache. Desde a versão 1.3.0 do MSAL Python, fornecemos uma API na MSAL para essa finalidade. Consulte o trecho de código a seguir, extraído de um exemplo completo de migração de tokens de atualização com o 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")