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:

2. 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
   

3. 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"
   

4. 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.

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.

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.

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.

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

sudo dnf install python3 python3-pip libubsan webkitgtk4-devel -y

sudo dnf install -y "https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm"
sudo dnf update
sudo dnf install -y openssl3-devel openssl3-libs

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"]))