Utilizar o MSAL Node com o Native Token Broker (Windows)

A Biblioteca de Autenticação da Microsoft (MSAL) para Node.js suporta a obtenção de tokens a partir do mediador nativo de tokens. Ao usar o broker nativo, os tokens de atualização estão vinculados ao dispositivo em que são obtidos e não são acessíveis nem por msal-node nem pela aplicação. Isto proporciona um nível mais elevado de segurança que não pode ser alcançado apenas com msal-node por si só.

Este artigo explica como configurar o Windows broker, configurar prova de posse e compreender o comportamento específico do broker.

O suporte para corretores está disponível nas seguintes plataformas:

Platform	Broker	Documentação
Windows	Gestor de Conta Web (WAM)	Windows broker (este artigo)
macOS	Plug-in de SSO empresarial da Microsoft (Portal da Empresa)	macOS broker
Linux	Microsoft Single Sign-on para Linux	Broker Linux

O que é um corretor

Um broker de autenticação é um componente que corre na máquina do utilizador e gere handshakes de autenticação e o ciclo de vida dos tokens para contas ligadas. No Windows, esta função é desempenhada pelo Gestor de Contas Web (WAM). Os principais benefícios incluem:

• Segurança reforçada. As melhorias de segurança são implementadas através de atualizações do sistema operativo ou do broker sem necessidade de alterações no código da aplicação. Os tokens de atualização estão ligados ao dispositivo e protegidos contra exfiltração.
• Suporte a funcionalidades. Acesso a capacidades avançadas do sistema operativo, como o Windows Hello, as políticas de Acesso Condicional do Microsoft Entra e as chaves de segurança Fast Identity Online (FIDO), sem código de suporte adicional.
• Integração com sistemas. As aplicações ligam-se ao seletor de contas incorporado, permitindo aos utilizadores selecionar rapidamente uma conta existente em vez de voltarem a introduzir credenciais.
• Proteção de tokens. O intermediário garante que os tokens de atualização estão associados ao dispositivo e permite às aplicações obter tokens de acesso com prova de posse.

Arquiteturas suportadas

• Windows: x64, x86, ARM64

Pré-requisitos

• Node.js 18 ou posterior
• Instalar @azure/msal-node-extensions como uma dependência
• Regista o URI de redirecionamento do corretor no registo da tua aplicação. Para o valor necessário, veja Redirecionar URI.

Redirecionar URL

Registe o seguinte URI de redirecionamento na plataforma de aplicações móveis e desktop no portal Azure:

ms-appx-web://Microsoft.AAD.BrokerPlugin/<your-client-id>

Substitua <your-client-id> pelo ID de cliente da sua aplicação.

Ativar a funcionalidade

Ativar a corretagem de tokens requer apenas um parâmetro de configuração. 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 recorrerá ao fluxo não intermediado em caso de falha. Só ative o fluxo do corretor em ambientes que o suportem para evitar falhas inesperadas.

Pode encontrar um exemplo funcional no sample auth-code-cli-brokered-app.

Parentalidade na janela

Para que os pedidos de autenticação sejam apresentados sobre a aplicação chamadora e impeçam outras interações, forneça o identificador da janela da aplicação à API acquireTokenInteractive.

Para aplicações de linha de comandos (CLI), é feita, nos bastidores, uma tentativa, na medida do possível, de encontrar o identificador da janela, mas não é fiável.

Se estiveres a usar Electron, usa a getNativeWindowHandle API e passa o resultado para acquireTokenInteractive:

import { BrowserWindow } from "electron";

const win = new BrowserWindow();
const pca = new PublicClientApplication(msalConfig);

pca.acquireTokenInteractive({
    windowHandle: win.getNativeWindowHandle(),
});

Prova de propriedade

A prova de posse (PoP) do token de acesso é suportada ao obter tokens através do broker nativo. Para solicitar um token PoP, adicione as seguintes propriedades ao objeto de pedido fornecido a acquireTokenInteractive ou acquireTokenSilent:

Parâmetros da solicitação AT PoP

Nome	Description	Obrigatório
authenticationScheme	Indica se a MSAL deve obter um token Bearer ou PoP. A predefinição é Bearer.	Obrigatório
resourceRequestMethod	O nome em maiúsculas do método HTTP do pedido que irá usar o token assinado (GET, POST, PUT, etc.)	Obrigatório
resourceRequestUri	A URL do recurso protegido para o qual o token de acesso está a ser emitido	Obrigatório
shrNonce	Um carimbo temporal assinado, gerado pelo servidor, codificado em Base64URL como uma string. Este nonce é usado para mitigar ataques de desfasamento do relógio e de manipulação temporal que visam permitir a pré-geração de tokens PoP.	Opcional

Exemplo de utilização

Este exemplo solicita um token de prova de posse definindo o esquema de autenticação e as propriedades do pedido HTTP assinado:

import { PublicClientApplication, Configuration, AuthenticationScheme } 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);

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER",
};

pca.acquireTokenInteractive(popTokenRequest);
pca.acquireTokenSilent(popTokenRequest);

Note

A prova de posse do token de acesso só é suportada através do fluxo nativo do broker e não está disponível no fluxo não intermediado.

Diferenças ao utilizar o intermediário do Windows

Existem algumas coisas que podem comportar-se de forma diferente ao adquirir tokens através do corretor nativo:

• O forceRefresh parâmetro para acquireTokenSilent chamadas não é suportado. Pode receber um token em cache do corretor independentemente do que este flag esteja definido.
• Se o corretor precisar de pedir ao utilizador a interação, abre-se um prompt do sistema. Isto altera a experiência do utilizador (UX) porque a autenticação não ocorre numa janela do navegador.
• A prova de posse do token de acesso é suportada pelo mediador, mas não é suportada pelo fluxo sem mediador.