Usando o MSAL Node com o Linux Broker

O Nó da Biblioteca de Autenticação da Microsoft (MSAL) pode usar o Logon Único da Microsoft para agente do Linux para fornecer logon único (SSO) e aquisição segura de tokens em distribuições do Linux com suporte. O agente gerencia os handshakes de autenticação e o ciclo de vida dos tokens, permitindo que os usuários se beneficiem da integração com contas já conhecidas pelo sistema.

Este artigo explica o que é o agente do Linux, as distribuições que ele dá suporte e como habilitar a aquisição de tokens agenciados em um aplicativo Node.js.

Para obter uma visão geral do suporte do broker em todas as plataformas, consulte Usando o MSAL Node com o Broker de Token Nativo.

O que é o broker no Linux

O logon único da Microsoft para Linux é um intermediário de autenticação distribuído independentemente da distribuição Linux. Instale-o com um gerenciador de pacotes (sudo apt install microsoft-identity-broker ou sudo dnf install microsoft-identity-broker). Ele também é agrupado como uma dependência de aplicativos Microsoft, como Portal da Empresa.

Os principais benefícios incluem:

  • Logon único. Simplifica como os usuários se autenticam com Microsoft Entra ID e protege os tokens de atualização contra exfiltração e uso indevido.
  • Segurança aprimorada. Melhorias de segurança são fornecidas por meio de atualizações do broker, sem exigir alterações no código do aplicativo.
  • Proteção de token. O agente garante que os tokens de atualização sejam associados ao dispositivo.
  • Integração do sistema. Os aplicativos se conectam ao seletor de conta interno, permitindo que os usuários selecionem rapidamente uma conta existente.

Distribuições com suporte

  • Ubuntu 22.04 / 24.04 (x64)
  • Red Hat Enterprise Linux (RHEL) 8/9 /10 (x64)

Pré-requisitos

  • Node.js 18 ou posterior
  • Instalar @azure/msal-node-extensions como uma dependência
  • microsoft-identity-broker deve ser instalado no dispositivo
  • Registre o URI de redirecionamento do broker no registro do seu aplicativo (consulte URI de redirecionamento abaixo)
  • Instalar as dependências do sistema necessárias (consulte as dependências do sistema abaixo)

URI de redirecionamento

Para fluxos de agentes do Linux, registre o seguinte URI de redirecionamento na plataforma Aplicativos móveis e de área de trabalho no portal do Azure:

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

Dependências do sistema

Ubuntu 22.04/24.04

sudo apt install libsecret-1-0 libdbus-1-3
  • libsecret — armazena e recupera com segurança tokens de autenticação por meio do chaveiro do sistema (chaveiro GNOME ou carteira KDE).
  • dbus — Comunicação entre processos com o agente de autenticação. Um barramento de sessão D-Bus deve estar em execução (padrão em ambientes de área de trabalho; servidores sem interface gráfica podem precisar de dbus-run-session ou equivalente).
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0
  • WebKitGTK — Fornece o navegador embutido para a interface interativa de login.
  • GTK — O kit de ferramentas de interface do usuário subjacente exigido pelo WebKitGTK.

habilitar o recurso

A ativação do broker no Linux usa a mesma configuração usada no Windows e no macOS. Passe uma instância de NativeBrokerPlugin na configuração do broker:

import { PublicClientApplication, Configuration } from "@azure/msal-node";
import { NativeBrokerPlugin } from "@azure/msal-node-extensions";

const msalConfig: Configuration = {
    auth: {
        clientId: "your-client-id",
    },
    broker: {
        nativeBrokerPlugin: new NativeBrokerPlugin(),
    },
};

const pca = new PublicClientApplication(msalConfig);

Note

msal-node não recorre a um fluxo via navegador se o broker não estiver disponível. Habilite apenas a autenticação agenciada em dispositivos Linux com suporte para evitar falhas inesperadas.

Aquisição de tokens

Aquisição interativa de token

Use acquireTokenInteractive para solicitar um token por meio do agente do Linux:

const tokenRequest = {
    scopes: ["User.Read"],
};

const result = await pca.acquireTokenInteractive(tokenRequest);
console.log("Access token:", result.accessToken);

Aquisição silenciosa de token

Após uma entrada interativa inicial, as solicitações de token subsequentes podem ser feitas silenciosamente:

const accounts = await pca.getAllAccounts();

if (accounts.length > 0) {
    const silentRequest = {
        scopes: ["User.Read"],
        account: accounts[0],
    };

    const result = await pca.acquireTokenSilent(silentRequest);
    console.log("Access token (silent):", result.accessToken);
}

Armazenamento de token em cache

O intermediário de autenticação gerencia o cache dos tokens de atualização e de acesso. Os tokens adquiridos por meio do agente são gerenciados pelo próprio agente e são associados ao dispositivo. Você não precisa configurar o cache personalizado ao usar o broker.

Diferenças ao usar o broker do Linux

  • Quando o broker precisar solicitar a interação do usuário, uma caixa de diálogo nativa de login (baseada em WebKitGTK) será exibida. Isso altera a experiência do usuário (UX) em comparação com a autenticação baseada em navegador.
  • O parâmetro forceRefresh para acquireTokenSilent não tem suporte. Você pode receber um token armazenado em cache do broker, independentemente dessa sinalização.
  • Um barramento de sessão D-Bus deve estar em execução para que a comunicação com o agente funcione.

Limitations

  • As autoridades do Azure AD B2C e do Serviços de Federação do Active Directory (AD FS) não têm suporte por meio do agente do Linux.
  • Não há suporte para IDPs (provedores de identidade de terceiros).
  • microsoft-identity-broker deve ser instalado no dispositivo para que o broker funcione.
  • msal-node não retornará a um navegador se o agente não estiver disponível. Habilite o broker apenas em ambientes que o suportem.
  • Atualmente, não há suporte para prova de posse (PoP) do token de acesso por meio do agente do Linux.
  • Last updated on