Biblioteca do Microsoft Authenticator (MSAL) para Python

A biblioteca Biblioteca do Microsoft Authenticator (MSAL) para Python permite que você conecte usuários ou aplicativos com identidades Microsoft (Microsoft Entra ID, contas Microsoft e contas do Microsoft Entra ID). Usando Python MSAL, você pode adquirir tokens de Microsoft Entra ID para chamar APIs Web protegidas, como Microsoft Graph, outras APIs Microsoft ou suas próprias APIs.

Pré-requisitos

Instalar o pacote

Instale o pacote MSAL para Python. Você pode encontrar o MSAL Python no PyPI.

pip install msal

Conceitos de identidade

O Python msal faz parte do ecossistema plataforma de identidade da Microsoft. Familiarize-se com os seguintes conceitos para usar efetivamente a MSAL Python para proteger seus aplicativos e APIs:

Cenários de uso

Para usar o MSAL Python, registre um aplicativo na plataforma de identidade da Microsoft. Você precisará de uma conta Azure com uma assinatura ativa. Crie uma conta gratuita se você não tiver uma. Você pode registrar seu aplicativo em um locatário do cliente ou locatário da força de trabalho.

Os aplicativos podem usar Python msal para adquirir tokens para acessar APIs protegidas. Diferentes tipos de aplicativo adquirem tokens usando fluxos de autenticação diferentes. Os tipos de aplicativo com suporte incluem aplicativos da área de trabalho, aplicativos Web, APIs Web e aplicativos em execução em dispositivos que não têm um navegador (como dispositivos IoT).

No Python MSAL, os aplicativos são categorizados da seguinte maneira:

  • Aplicativos cliente públicos (desktop e móvel). Esses tipos de aplicativos não podem armazenar segredos do aplicativo com segurança.
  • Aplicativos cliente confidenciais (aplicativos Web, APIs Web e aplicativos daemon). Esses tipos de aplicativos armazenam com segurança um segredo registrado com Microsoft Entra ID.

Para obter mais informações, consulte a documentação sobre aplicativos cliente públicos e clientes confidenciais e os diferentes tipos de aplicativo e seus fluxos de autenticação no plataforma de identidade da Microsoft.

Depois de determinar se seu aplicativo é um aplicativo cliente público ou confidencial, você pode usar o Python MSAL para adquirir tokens para cenários diferentes.

Uso Básico

A aquisição de tokens com Python MSAL segue um padrão de três etapas. Haverá algumas variações para fluxos diferentes. Se você quiser vê-los em ação, baixe nossos exemplos.

  1. A MSAL depende de uma separação limpa entre aplicativos cliente públicos e clientes confidenciais. Portanto, crie uma instância PublicClientApplication ou uma instância ConfidentialClientApplication e reutilize-a ao longo do ciclo de vida do aplicativo. Por exemplo, para um aplicativo cliente público, o código de inicialização pode ter esta aparência:

    from msal import PublicClientApplication

app = PublicClientApplication(
    "your_client_id",
    authority="https://login.microsoftonline.com/common")

    O valor da autoridade varia de acordo com o tipo de conta que você usa para entrar e com o tipo de locatário no qual seu aplicativo está registrado. Por exemplo, para fazer login em contas Microsoft corporativas e pessoais provisionadas em locatários de força de trabalho (Microsoft Entra ID), você usaria https://login.microsoftonline.com/common. Para contas de clientes provisionadas em locatários do cliente, sua autoridade terá um formato como https://<subdomain>.ciamlogin.com. Para obter mais informações, consulte a documentação do emissor do token.

  2. Tente obter os tokens do cache primeiro. O modelo de API no MSAL fornece controle explícito sobre como utilizar o cache de token. Embora a parte de cache seja tecnicamente opcional, é altamente recomendável usá-la em seu aplicativo. Usando o cache, você pode garantir que não está fazendo chamadas extras à API e manipular a atualização de token automaticamente.

    # initialize result variable to hole the token response
result = None 

# We now check the cache to see
# whether we already have some accounts that the end user already used to sign in before.
accounts = app.get_accounts()
if accounts:
    # If so, you could then somehow display these accounts and let end user choose
    print("Pick the account you want to use to proceed:")
    for a in accounts:
        print(a["username"])
    # Assuming the end user chose this one
    chosen = accounts[0]
    # Now let's try to find a token in cache for this account
    result = app.acquire_token_silent(["User.Read"], account=chosen)

  3. Se não houver nenhum token adequado no cache ou você optar por ignorar a etapa anterior, envie uma solicitação para Microsoft Entra ID para obter um token. Há métodos diferentes com base no seu tipo de cliente e cenário, mas para fins do exemplo estamos mostrando como usar acquire_token_interactive, o que solicita que o usuário forneça suas credenciais.

    if not result:
    # So no suitable token exists in cache. Let's get a new one from Azure AD.
    result = app.acquire_token_interactive(scopes=["User.Read"])
if "access_token" in result:
    print(result["access_token"])  # Yay!
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You may need this when reporting a bug

  4. Salve o código em um arquivo Python localmente, como msaltest.py.

  5. Execute o código executando python .\msalpytest.py. O visual a seguir mostra a experiência de entrada para este exemplo.

    Exemplo de um aplicativo solicitando que o usuário entre com sua conta

  6. Depois que a autenticação for concluída e você fechar o navegador, você poderá ver o token de acesso impresso no terminal.

Práticas recomendadas para um aplicativo robusto pronto para uso corporativo

Você pode adquirir um token para uma API Web protegida usando Python MSAL. Você também não precisa gerenciar os tokens de atualização por conta própria. No entanto, para criar aplicativos robustos e prontos para a empresa, você precisará fazer um pouco mais. Por exemplo, você desejará:

  • Manipule exceções, tanto quando você adquire um token, mas também quando chama a API Web protegida. Em particular, se o aplicativo for executado em um locatário Microsoft Entra em que os administradores de locatários definiram políticas de Acesso Condicional para impor a MFA (Autenticação De Vários Fatores), você precisará lidar com um desafio de Declaração.

  • Talvez você queira habilitar os Logs para diagnosticar problemas no seu aplicativo e ajudar seus usuários, respeitando a privacidade deles e em conformidade com o GDPR.

Exemplos

Há vários exemplos que você pode usar para começar a usar o Python msal.

  • Exemplos do repositório de bibliotecas. Esses exemplos demonstram as diferentes configurações e fluxos de autenticação que você implementa usando Python MSAL.
  • Um único repositório com exemplos usados em nossa documentação. Esses exemplos têm documentação de apoio para ajudá-lo a criá-los e reproduzi-los do zero.

References

  • Repositório de biblioteca de Python MSAL no GitHub
  • Lançamentos do MSAL Python no GitHub.

Consulte também

  • Last updated on