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

Este artigo destaca as alterações que precisa de fazer para migrar uma aplicação que utiliza a Azure Active Directory Authentication Library (ADAL) para utilizar a Biblioteca de Autenticação da Microsoft (MSAL).

Pode aprender mais sobre MSAL e começar com uma visão geral da Biblioteca de Autenticação da Microsoft para Python.

Destaques das diferenças

O ADAL funciona com o endpoint Azure Active Directory (Azure AD) v1.0. A biblioteca de autenticação da Microsoft (MSAL) funciona com a plataforma de identidade da Microsoft — anteriormente conhecida como o ponto final v2.0 do Azure Active Directory. A plataforma de identidades da Microsoft difere do Azure AD v1.0 porque:

Suporta:

• Contas de trabalho e escola (contas provisionadas pelo Microsoft Entra ID)

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

• Os seus clientes que trazem o seu próprio email ou identidade social (como LinkedIn, Facebook, Google) através da oferta B2C do Azure AD

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

  • OAuth v2.0
  • OpenID Connect (OIDC)

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

Escopos, não recursos

O ADAL Python adquire tokens para recursos, mas o MSAL Python adquire tokens para escopos. A superfície API no MSAL Python já não tem parâmetro de recurso. Terias de fornecer os escopos como uma lista de strings que declaram as permissões e recursos desejados. Para ver alguns exemplos de telescópios, veja os osciloscópios do Microsoft Graph.

Pode adicionar o /.default sufixo de âmbito ao recurso para ajudar a migrar as suas aplicações do endpoint v1.0 (ADAL) para a plataforma de identidades da Microsoft (MSAL). Por exemplo, para o valor de recurso de https://graph.microsoft.com, o valor equivalente do âmbito é https://graph.microsoft.com/.default. Se o recurso não estiver no formulário URL, mas sim num ID de recurso do formulário XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX, pode ainda usar o valor do âmbito como XXXXXXXX-XXXX-XXXX-XXXXXXXXXXXX/.default.

Para mais detalhes sobre os diferentes tipos de âmbitos, consulte os artigos Permissões e consentimento na plataforma de identidades da Microsoft e Âmbitos para uma API Web que aceita tokens v1.0.

Tratamento de erros

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

Alterações da API

A tabela seguinte lista uma API em ADAL para Python, e aquela a usar em seu lugar no MSAL para Python:

Migrar tokens de atualização existentes para MSAL Python

O MSAL trata de forma abstrata o conceito de tokens de atualização. O MSAL Python fornece, por predefinição, uma cache de tokens na memória, para que não tenha de armazenar, procurar ou atualizar tokens de atualização. Os utilizadores também verão menos pedidos de início de sessão, porque os tokens de atualização geralmente podem ser atualizados sem intervenção do utilizador. Para mais informações sobre a cache de tokens, consulte Serialização personalizada da cache de token em MSAL para Python.

O código seguinte irá ajudá-lo a migrar os seus tokens de atualização geridos por outra biblioteca OAuth2 (incluindo, mas não se limitando a, ADAL Python) para serem geridos pela MSAL para Python. Uma das razões para migrar esses tokens de atualização é evitar que os utilizadores existentes precisem de voltar a iniciar sessão quando migrar a sua aplicação para MSAL para Python.

O método para migrar um token de atualização é usar MSAL para Python para adquirir um novo token de acesso usando o token de atualização anterior. Quando o novo token de atualização é devolvido, o MSAL para Python armazena-o na cache. Desde o MSAL Python 1.3.0, fornecemos uma API dentro do MSAL para este propósito. Consulte o seguinte excerto de código, retirado 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")