Utilizar o MSAL Node com o mediador do Linux

A Biblioteca de Autenticação da Microsoft (MSAL) para Node pode utilizar o mediador Microsoft Single Sign-on para Linux para proporcionar início de sessão único (SSO) e obtenção segura de tokens nas distribuições Linux suportadas. O corretor gere os handshakes de autenticação e o ciclo de vida dos tokens, permitindo que os utilizadores beneficiem da integração com contas conhecidas pelo sistema.

Este artigo explica o que é o broker Linux, as distribuições que suporta e como permitir a aquisição de tokens intermediados numa aplicação Node.js.

Para uma visão geral do suporte a corretores em todas as plataformas, consulte Usar o Nó MSAL com o Broker Nativo de Tokens.

O que é o broker Linux

O Microsoft Single Sign-on para Linux é um broker de autenticação fornecido de forma independente da distribuição Linux. Instale-o com um gestor de pacotes (sudo apt install microsoft-identity-broker ou sudo dnf install microsoft-identity-broker). Também é incluído como uma dependência de aplicações da Microsoft, como o Portal da Empresa.

Os principais benefícios incluem:

  • Sessão única. Simplifica a autenticação dos utilizadores com o Microsoft Entra ID e protege os tokens de atualização contra exfiltração e uso indevido.
  • Segurança reforçada. As melhorias de segurança são implementadas através de atualizações do corretor sem necessidade de alterações no código da aplicação.
  • Proteção de tokens. O corretor garante que os tokens de atualização estão ligados ao dispositivo.
  • Integração com sistemas. As aplicações ligam-se ao seletor de contas incorporado, permitindo aos utilizadores selecionar rapidamente uma conta existente.

Distribuições suportadas

  • 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
  • Registe o URI de redirecionamento do corretor no registo da tua aplicação (ver URI de redirecionamento abaixo)
  • Instalar as dependências do sistema necessárias (ver Dependências do sistema abaixo)

Redirecionar URL

Para os fluxos do mediador no Linux, registe o seguinte URI de redirecionamento na plataforma Aplicações móveis e de ambiente 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 tokens de autenticação de forma segura através do keyring do sistema (GNOME Keyring ou KDE Wallet).
  • dbus — Comunicação entre processos com o intermediário de autenticação. É necessário que esteja em execução um barramento de sessão D-Bus (habitual em ambientes de trabalho; os 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 incorporado para a interface interativa de início de sessão.
  • GTK — O conjunto de ferramentas de interface subjacente exigido pelo WebKitGTK.

Ativar a funcionalidade

A ativação do broker do Linux usa a mesma configuração do Windows e do 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 baseado no navegador se o corretor não estiver disponível. Ative a autenticação intermediária apenas em dispositivos Linux suportados para evitar falhas inesperadas.

Obter tokens

Aquisição interativa de tokens

Use acquireTokenInteractive para pedir um token através do broker 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 um início de sessão interativo inicial, os pedidos subsequentes de tokens podem ser efetuados de forma silenciosa:

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 em cache de tokens

O intermediário de autenticação gere o armazenamento em cache de tokens de atualização e de acesso. Os tokens adquiridos através do corretor são geridos pelo próprio corretor e estão ligados ao dispositivo. Não precisa de configurar cache personalizado ao usar o corretor.

Diferenças ao usar o broker Linux

  • Quando o corretor precisa de pedir interação, aparece um diálogo nativo de início de sessão (baseado no WebKitGTK). Isto altera a experiência do utilizador (UX) em comparação com a autenticação baseada no navegador.
  • O forceRefresh parâmetro para acquireTokenSilent não é suportado. Pode receber um token em cache do corretor independentemente desta bandeira.
  • Um bus de sessão D-Bus deve estar a funcionar para que a comunicação entre corretores funcione.

Limitações

  • As autoridades Azure AD B2C e Serviços de Federação do Active Directory (AD FS) (AD FS) não são suportadas através do broker Linux.
  • Os fornecedores de identidade de terceiros (IDPs) não são suportados.
  • microsoft-identity-broker Deve ser instalado no dispositivo para que o corretor funcione.
  • msal-node não recorre a um navegador se o corretor não estiver disponível. Só ative o corretor em ambientes que o suportem.
  • A prova de posse (PoP) do token de acesso não é atualmente suportada através do broker do Linux.
  • Last updated on