Usando o MSAL Node com o Agente nativo de token (Windows)

Biblioteca do Microsoft Authenticator (MSAL) Node dá suporte à obtenção de tokens do intermediador de tokens nativo. Ao usar o agente nativo, os tokens de atualização ficam vinculados ao dispositivo no qual são adquiridos e não ficam acessíveis para msal-node nem para o aplicativo. Isso proporciona um nível mais alto de segurança que não pode ser alcançado apenas com msal-node.

Este artigo explica como configurar o agente de Windows, configurar a prova de posse e entender o comportamento específico do agente.

O suporte ao agente está disponível nas seguintes plataformas:

O que é um agente

Um agente de autenticação é um componente executado no computador de um usuário e gerencia handshakes de autenticação e ciclo de vida de token para contas conectadas. Em Windows, essa função é executada pelo Gerenciador de Contas Web (WAM). Os principais benefícios incluem:

• Segurança aprimorada. Melhorias de segurança são fornecidas por meio de atualizações do sistema operacional ou do agente sem a necessidade de alterações no código do aplicativo. Os tokens de atualização são associados ao dispositivo e protegidos contra exfiltração.
• Suporte a funcionalidades. Acesso a amplos recursos do sistema operacional, como Windows Hello, políticas de Acesso Condicional do Microsoft Entra e chaves de segurança FIDO (Fast Identity Online), sem código de infraestrutura adicional.
• Integração do sistema. Os aplicativos se conectam ao seletor de conta interno, permitindo que os usuários selecionem rapidamente uma conta existente em vez de inserir novamente as credenciais.
• Proteção de token. O intermediário garante que os tokens de atualização sejam vinculados ao dispositivo e permite que os aplicativos obtenham tokens de acesso com prova de posse.

Arquiteturas com suporte

• Windows: x64, x86, ARM64

Pré-requisitos

• Node.js 18 ou posterior
• Instalar @azure/msal-node-extensions como uma dependência
• Registre o URI de redirecionamento do broker no registro do seu aplicativo. Para o valor necessário, consulte URI de Redirecionamento.

URI de redirecionamento

Registre o seguinte URI de redirecionamento na plataforma Aplicativos móveis e de desktop no portal do Azure:

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

Substitua <your-client-id> pela ID do cliente do aplicativo.

habilitar o recurso

Habilitar a intermediação de token 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);

Um exemplo de trabalho pode ser encontrado no exemplo auth-code-cli-brokered-app.

Parentalidade de janela

Para que as solicitações de autenticação sejam exibidas sobre o aplicativo chamador e impeçam interações adicionais, forneça o identificador da janela do aplicativo à API acquireTokenInteractive.

Para aplicativos CLI, é feita internamente uma tentativa de melhor esforço para localizar o identificador da janela; no entanto, esse método é inerentemente pouco confiável.

Se você estiver usando o Electron, use a getNativeWindowHandle API e passe o resultado para acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Prova de posse

Há suporte para prova de posse (PoP) do token de acesso ao adquirir tokens por meio do agente nativo. Para solicitar um token PoP, adicione as seguintes propriedades ao objeto de requisição fornecido a acquireTokenInteractive ou acquireTokenSilent:

Parâmetros da solicitação AT PoP

Exemplo de utilização

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

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);

Diferenças ao usar o agente de Windows

Há algumas coisas que podem se comportar de forma diferente ao adquirir tokens por meio do agente nativo:

• Não há suporte para o parâmetro forceRefresh em chamadas a acquireTokenSilent. Você pode receber um token armazenado em cache do broker, independentemente do valor definido para esse sinalizador.
• Se o corretor precisar solicitar que o usuário interaja, um prompt do sistema é aberto. Isso altera a experiência do usuário (UX) porque a autenticação não ocorre em uma janela do navegador.
• A prova de posse do token de acesso é suportada pelo agente, mas não pelo fluxo sem agente.