Uso del nodo MSAL con el agente de token nativo (Windows)

Biblioteca de autenticación de Microsoft (MSAL) para Node admite obtener tokens desde el broker de tokens nativo. Al usar el agente nativo, los tokens de actualización quedan vinculados al dispositivo en el que se adquieren y no son accesibles para msal-node ni para la aplicación. Esto proporciona un mayor nivel de seguridad que no se puede lograr por msal-node sí solo.

En este artículo se explica cómo configurar el agente de Windows, configurar la prueba de posesión y comprender el comportamiento específico del agente.

La compatibilidad con broker está disponible en las siguientes plataformas:

¿Qué es un agente?

Un agente de autenticación es un componente que se ejecuta en la máquina de un usuario y administra los protocolos de enlace de autenticación y el ciclo de vida de los tokens para las cuentas conectadas. En Windows, el administrador de cuentas web (WAM) realiza este rol. Entre las ventajas clave se incluyen las siguientes:

• Seguridad mejorada. Las mejoras de seguridad se entregan a través de actualizaciones del sistema operativo o agente sin necesidad de cambios en el código de la aplicación. Los tokens de actualización están enlazados al dispositivo y están protegidos contra la filtración.
• Compatibilidad de funciones. Acceso a amplias capacidades del sistema operativo, como Windows Hello, directivas de acceso condicional de Microsoft Entra y claves de seguridad de Fast Identity Online (FIDO) sin código auxiliar adicional.
• Integración del sistema. Las aplicaciones se conectan al selector de cuentas integrada, lo que permite a los usuarios seleccionar rápidamente una cuenta existente en lugar de volver a escribir las credenciales.
• Protección de tokens. El intermediario garantiza que los tokens de actualización estén vinculados al dispositivo y permite que las aplicaciones adquieran tokens de acceso con prueba de posesión.

Arquitecturas compatibles

• Windows: x64, x86, ARM64

Prerequisites

• Node.js 18 o posterior
• Instala @azure/msal-node-extensions como dependencia
• Registre el URI de redirección del broker en el registro de su aplicación. Para ver el valor necesario, consulte URI de redirección.

URI de redirección

Registre el siguiente URI de redirección en la plataforma Aplicaciones móviles y de escritorio en el portal de Azure:

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

Reemplace por <your-client-id> el identificador de cliente de la aplicación.

Habilitar la característica

La habilitación del agente de tokens requiere solo un parámetro de configuración. Pase una instancia de NativeBrokerPlugin en la configuración del 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);

Puede encontrar un ejemplo de trabajo en la muestra auth-code-cli-brokered-app.

Jerarquía de ventanas

Para que las solicitudes de autenticación se muestren a través de la aplicación que realiza la llamada y bloqueen la interacción adicional, proporcione el identificador de ventana de la aplicación a la acquireTokenInteractive API.

En el caso de las aplicaciones de línea de comandos (CLI), se hace internamente un intento por encontrar el identificador de la ventana, pero no es fiable.

Si usa Electron, use la getNativeWindowHandle API y pase el resultado a acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Prueba de posesión

La prueba de posesión (PoP) del token de acceso se admite al adquirir tokens a través del agente nativo. Para solicitar un token de poP, agregue las siguientes propiedades al objeto de solicitud proporcionado a acquireTokenInteractive o acquireTokenSilent:

Parámetros de solicitud de AT PoP

Ejemplo de uso

En este ejemplo se solicita un token de prueba de posesión estableciendo el esquema de autenticación y las propiedades de solicitud HTTP firmadas:

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

Diferencias al usar el agente de Windows

Hay algunas cosas que pueden comportarse de forma diferente al adquirir tokens a través del agente nativo:

• No se admite el parámetro forceRefresh para las llamadas a acquireTokenSilent. Puede recibir un token en caché del intermediario independientemente del valor que tenga este indicador.
• Si el intermediario necesita solicitar la interacción del usuario, se abre una solicitud del sistema. Esto cambia la experiencia del usuario (UX) porque la autenticación no se produce en una ventana del explorador.
• La prueba de posesión del token de acceso es compatible con el agente, pero no es compatible con el flujo sin agente.