Utilisation du nœud MSAL avec le répartiteur de jetons natif (Windows)

Microsoft Authentication Library (MSAL) Node prend en charge l’acquisition de jetons via le courtier de jetons natif. Lorsque vous utilisez le broker natif, les jetons d’actualisation sont liés à l’appareil sur lequel ils ont été obtenus et ne sont accessibles ni à msal-node ni à l’application. Cela offre un niveau de sécurité plus élevé qui ne peut pas être atteint par msal-node seul.

Cet article explique comment configurer le répartiteur Windows, configurer la preuve de possession et comprendre le comportement spécifique au répartiteur.

La prise en charge du répartiteur est disponible sur les plateformes suivantes :

Qu’est-ce qu’un répartiteur ?

Un courtier d’authentification est un composant qui s’exécute sur l’ordinateur d’un utilisateur et gère les échanges d’authentification ainsi que le cycle de vie des jetons pour les comptes connectés. Sur Windows, ce rôle est effectué par le Gestionnaire de comptes web (WAM). Les principaux avantages sont les suivants :

• Sécurité renforcée. Les améliorations de sécurité sont fournies via les mises à jour du système d’exploitation ou du répartiteur sans nécessiter de modifications de code d’application. Les jetons d’actualisation sont liés à l’appareil et protégés contre l’exfiltration.
• Prise en charge des fonctionnalités. Accès à des fonctionnalités avancées du système d’exploitation telles que Windows Hello, les stratégies d’accès conditionnel Microsoft Entra et les clés de sécurité Fast Identity Online (FIDO), sans code d’infrastructure supplémentaire.
• Intégration du système. Les applications se connectent au sélecteur de compte intégré, ce qui permet aux utilisateurs de sélectionner rapidement un compte existant au lieu de réinscrire les informations d’identification.
• Protection des jetons. Le répartiteur garantit que les jetons d’actualisation sont liés à l’appareil et permet aux applications d’obtenir des jetons d’accès avec preuve de possession.

Architectures prises en charge

• Windows : x64, x86, ARM64

Prerequisites

• Node.js 18 ou version ultérieure
• Installer @azure/msal-node-extensions en tant que dépendance
• Enregistrez l’URI de redirection du broker dans l’enregistrement de votre application. Pour obtenir la valeur requise, consultez l’URI de redirection.

URI de redirection

Inscrivez l’URI de redirection suivant sous la plateforme Applications mobiles et de bureau dans le portail Azure :

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

Remplacez <your-client-id> par l’ID client de votre application.

Activer la fonctionnalité

L’activation du répartiteur de jetons nécessite un seul paramètre de configuration. Transmettez une NativeBrokerPlugin instance dans la configuration du répartiteur :

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

Vous trouverez un exemple de travail dans l’exemple d’application auth-code-cli-brokered-app.

Relation parent-enfant entre fenêtres

Pour que les invites d’authentification s’affichent sur l’application appelante et bloquent une interaction supplémentaire, fournissez le handle de fenêtre de l’application à l’API acquireTokenInteractive .

Pour les applications CLI, une tentative optimale de trouver la poignée de fenêtre est effectuée sous le capot, mais elle n’est pas fiable.

Si vous utilisez Electron, utilisez l’API getNativeWindowHandle et passez le résultat dans acquireTokenInteractive:

import { BrowserWindow } from "electron";

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

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

Preuve de possession

La preuve de possession (PoP) du token d'accès est prise en charge lors de l'acquisition de tokens via le broker natif. Pour demander un jeton PoP, ajoutez les propriétés suivantes à l’objet de requête fourni à acquireTokenInteractive ou acquireTokenSilent:

Paramètres de la requête AT PoP

Exemple d’utilisation

Cet exemple demande un jeton de preuve de possession en définissant le schéma d’authentification et les propriétés de requête HTTP signées :

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

Différences lors de l’utilisation du répartiteur Windows

Il existe quelques éléments qui peuvent se comporter différemment lors de l’acquisition de jetons via le répartiteur natif :

• Le paramètre forceRefresh pour les appels acquireTokenSilent n’est pas pris en charge. Vous pouvez recevoir un jeton mis en cache par le répartiteur, quelle que soit la valeur définie pour cet indicateur.
• Si le répartiteur doit inviter l’utilisateur à entrer en interaction, une invite système s’ouvre. Cela modifie l’expérience utilisateur (UX), car l’authentification ne se produit pas dans une fenêtre de navigateur.
• La preuve de possession du jeton d’accès est prise en charge par le répartiteur, mais elle n’est pas prise en charge par le flux non réparti.