Habilitar o SSO no Linux nativo com o MSAL Python

Biblioteca do Microsoft Authenticator (MSAL) é um kit de desenvolvimento de software (SDK) que permite que os aplicativos chamem o agente de Logon Único da Microsoft para Linux, um componente do Linux fornecido separadamente da distribuição Linux; no entanto, ele é instalado usando um gerenciador de pacotes com sudo apt install microsoft-identity-broker ou sudo dnf install microsoft-identity-broker.

Esse componente atua como um agente de autenticação permitindo que os usuários do seu aplicativo se beneficiem da integração com contas reconhecidas pelo Linux, como a conta com a qual você iniciou suas sessões no Linux, para aplicativos que consomem o agente.

O broker também é incluído como dependência de aplicativos desenvolvidos pela Microsoft (como Portal da Empresa)). Um exemplo de instalação do broker é quando um computador Linux é inscrito na frota de dispositivos de uma empresa por meio de uma solução de gerenciamento de endpoints, como Microsoft Intune.

O que é um agente

Um agente de autenticação é um aplicativo executado no computador de um usuário que gerencia os handshakes de autenticação e a manutenção de token para contas conectadas. O sistema operacional Linux usa o logon único da Microsoft para Linux como seu agente de autenticação. Ele tem muitos benefícios para desenvolvedores e clientes, incluindo:

  • Habilita o Logon Único: permite que os aplicativos simplifiquem como os usuários se autenticam com Microsoft Entra ID e protege Microsoft Entra ID tokens de atualização contra exfiltração e uso indevido
  • Segurança aprimorada. Muitos aprimoramentos de segurança são disponibilizados com o broker, sem necessidade de atualizar a lógica do aplicativo.
  • Suporte a funcionalidades. Com a ajuda do broker, os desenvolvedores podem acessar recursos avançados do sistema operacional e dos serviços.
  • Integração do sistema. Aplicativos que usam o agente plug-and-play com o seletor de contas integrado, permitindo que o usuário selecione rapidamente uma conta existente em vez de reinserir as mesmas credenciais várias vezes.
  • Proteção de Token. O logon único da Microsoft para Linux garante que os tokens de atualização sejam vinculados ao dispositivo.

Como aderir ao uso do broker?

  1. Na biblioteca MSAL para Python, introduzimos o sinalizador enable_broker_on_linux, que habilita o broker tanto no WSL quanto no Linux autônomo.
    • Se o seu objetivo for habilitar o suporte a broker somente no WSL para o CLI do Azure, você pode considerar modificar o código do aplicativo do CLI do Azure para ativar o sinalizador enable_broker_on_wsl exclusivamente no WSL.
    • Se você estiver escrevendo um aplicativo multiplataforma, também precisará usarenable_broker_on_windows, conforme descrito no artigo Usando o Python msal com o Gerenciador de Contas Web.
    • Você pode definir qualquer combinação dos seguintes parâmetros de aceitação como true:
Sinalizador de aceitação Se o aplicativo for executado em O aplicativo registrou isso como um URI de redirecionamento da plataforma desktop no portal do Azure
enable_broker_on_windows Windows 10+ ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id
enable_broker_on_wsl WSL ms-appx-web://Microsoft. AAD. BrokerPlugin/your_client_id
enable_broker_on_mac Mac com Portal da Empresa instalado msauth.com.msauth.unsignedapp://auth
enable_broker_on_linux Linux com o Intune instalado https://login.microsoftonline.com/common/oauth2/nativeclient (DEVE ser habilitado)

  1. Seu aplicativo precisa oferecer suporte a URIs de redirecionamento específicas do broker. Especificamente para Linux, a URL de redirecionamento deve ser:

    https://login.microsoftonline.com/common/oauth2/nativeclient

  2. Para usar o broker, você precisará instalar os pacotes relacionados ao broker, além do pacote principal do MSAL disponível no PyPI:

    pip install "msal[broker]>=1.33.0b1,<2"

  3. Depois de configurado, você pode chamar acquire_token_interactive para adquirir um token.

    result = app.acquire_token_interactive(["User.ReadBasic.All"],
                    parent_window_handle=app.CONSOLE_WINDOW_HANDLE)

Parâmetros para suporte ao agente

Os parâmetros a seguir estão disponíveis para configurar o suporte a broker no MSAL Python. Esses parâmetros podem ser passados para o PublicClientApplication construtor ou para o acquire_token_interactive método.

Parâmetros: Tipo Description
enable_broker_on_windows boolean Essa configuração só será eficaz se o aplicativo estiver em execução no Windows 10+. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

New in MSAL Python 1.25.0.
enable_broker_on_wsl boolean Essa configuração só será eficaz se o aplicativo estiver em execução no WSL. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

New in MSAL Python 1.25.0.
enable_broker_on_mac boolean Essa configuração só será eficaz se o aplicativo estiver em execução no Mac com Portal da Empresa instalado. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

New in MSAL Python 1.31.0.
enable_broker_on_linux boolean Essa configuração só será efetiva se o aplicativo estiver em execução no Linux com o Intune instalado. Esse parâmetro usa como padrão None, o que significa que a MSAL não utilizará um agente.

New in MSAL Python 1.33.0.
parent_window_handle int OPCIONAL

Anotações sobre parent_window_handle

O parent_window_handle parâmetro é necessário mesmo que no Linux ele não seja usado. Para aplicativos gui, o local do prompt de logon será determinado ad-hoc e atualmente não pode ser associado a uma janela específica. Em uma atualização futura, esse parâmetro será usado para determinar a janela pai real.

Condition Description
O aplicativo não deseja utilizar um agente não é necessário especificar um parent_window_handle
O aplicativo opta por usar um agente parent_window_handle é obrigatório
O aplicativo é um aplicativo de GUI em execução no sistema Windows ou Mac necessário para fornecer seu identificador de janela, para que a janela de entrada apareça na parte superior da janela
O aplicativo é um aplicativo de console em execução no sistema Windows ou Mac pode usar um marcador PublicClientApplication.CONSOLE_WINDOW_HANDLE
O aplicativo destina-se a ser um aplicativo multiplataforma O aplicativo precisa usar enable_broker_on_windows, conforme descrito no artigo Usando o MSAL Python com o Gerenciador de Contas da Web.

Os comportamentos alternativos do suporte para agente na MSAL Python

A MSAL retornará um erro ou, silenciosamente, recorrerá a fluxos sem agente.

  1. MSAL ignorará enable_broker_... e ignorará o agente nos fluxos de autenticação que reconhecidamente NÃO têm suporte do agente. Isso inclui ADFS, B2C, etc.. Veja outros cenários de “could-use-broker” abaixo.

  2. A MSAL apresenta erro quando o desenvolvedor do aplicativo opta por usar o agente, mas um pacote de camada intermediária de dependência direta não está instalado. A mensagem de erro orienta o desenvolvedor do aplicativo a declarar a dependência correta msal[broker]. Geramos um erro aqui porque ele permite que os desenvolvedores de aplicativos tomem uma ação corretiva.

  3. A MSAL “desativa” silenciosamente o agente e recorre ao modo sem agente quando essa opção está habilitada e a dependência está instalada, mas falha ao ser inicializada. Prevíamos que isso aconteceria em um dispositivo cujo sistema operacional é muito antigo ou o componente do agente subjacente está de alguma forma indisponível. Não há muito que um desenvolvedor de aplicativos ou o usuário final possa fazer aqui. Eventualmente, a política de acesso condicional forçará o usuário a alternar para um dispositivo diferente.

  4. O MSAL apresenta erro quando o broker está habilitado, instalado e inicializado, mas as solicitações subsequentes de token falham.

Importante

Se os pacotes relacionados ao agente não estiverem instalados e você tentar usar o agente de autenticação, receberá um erro: ImportError: You need to install dependency by: pip install "msal[broker]>=1.xx,<2".

Note

O parent_window_handle parâmetro é necessário mesmo que no Linux ele não seja usado. Para aplicativos gui, o local do prompt de logon será determinado ad-hoc e atualmente não pode ser associado a uma janela específica. Em uma atualização futura, esse parâmetro será usado para determinar a janela pai real.

Armazenamento de token em cache

O intermediário de autenticação gerencia o cache dos tokens de atualização e de acesso. Você não precisa configurar o cache personalizado.

Criando um aplicativo de exemplo

Você pode encontrar um aplicativo de exemplo que demonstra como usar o Python MSAL com o agente de autenticação no Linux no repositório de Python GitHub MSAL. O aplicativo de exemplo está localizado no samples/console_app diretório e inclui exemplos de como usar o agente para autenticação.

Registro de Aplicativo

Atualize o registro do aplicativo no portal do Azure para incluir o URI de redirecionamento específico do broker para Linux:

https://login.microsoftonline.com/common/oauth2/nativeclient

Dependências do Linux

Primeiro, verifique se você tem o Python3 instalado na distribuição do Linux.

python3 --version

Caso contrário, instale-o usando o gerenciador de pacotes para sua distribuição.

Para instalar na distribuição do Linux baseada em Debian/Ubuntu:

sudo add-apt-repository -y universe
sudo apt update
sudo apt install python3 python3-pip libwebkit2gtk-4.1-dev -y

dependências de Python

Para usar o broker, você precisará instalar os pacotes relacionados ao broker, além do pacote principal do MSAL disponível no PyPI:

pip install "msal[broker]>=1.33.0b1,<2"

Criar Projeto

Depois de configurado, você pode chamar acquire_token_interactive para adquirir um token.

import sys  # For simplicity, we'll read config file from 1st CLI param sys.argv[1]
import json
import logging
import requests
import msal

# Optional logging
# logging.basicConfig(level=logging.DEBUG)

var_authority = "https://login.microsoftonline.com/common"
var_client_id = "your-client-id-here"  # Replace with your app's client ID
var_username = "your-username-here"  # Replace with your username, e.g., "
var_scope = ["User.ReadBasic.All"]
# Removed unused variable to avoid confusion


# Create a preferably long-lived app instance which maintains a token cache (Default cache is in memory only).
app = msal.PublicClientApplication(
    var_client_id, 
    authority=var_authority,
    enable_broker_on_windows=True,
    enable_broker_on_wsl=True
    )

# The pattern to acquire a token looks like this.
result = None

# Firstly, check the cache to see if this end user has signed in before
accounts = app.get_accounts(username=var_username)
if accounts:
    logging.info("Account(s) exists in cache, probably with token too. Let's try.")
    result = app.acquire_token_silent(var_scope, account=accounts[0])

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from AAD.")
    
    result = app.acquire_token_interactive(var_scope,parent_window_handle=app.CONSOLE_WINDOW_HANDLE)
    
if "access_token" in result:
    print("Access token is: %s" % result['access_token'])

else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You may need this when reporting a bug
    if 65001 in result.get("error_codes", []):  # Not mean to be coded programatically, but...
        # AAD requires user consent for U/P flow
        print("Visit this to consent:", app.get_authorization_request_url(config["scope"]))
  • Last updated on