Partager via

Plug-in Azure Identity pour l’authentification répartie

  • Article

Ce package fournit un plug-in à la bibliothèque Azure Identity pour JavaScript (@azure/identity) qui permet d’utiliser un répartiteur d’authentification tel que WAM.

Un répartiteur d’authentification est une application qui s’exécute sur l’ordinateur d’un utilisateur qui gère les liaisons d’authentification et la maintenance des jetons pour les comptes connectés. Actuellement, seul le répartiteur d’authentification Windows, le Gestionnaire de comptes web (WAM) est pris en charge.

documentation de référence sur le code source | Samples | API | [Documentation microsoft Entra ID] (https://learn.microsoft.com/entra/identity/)

Commencer

import { useIdentityPlugin } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);

Conditions préalables

  • Un abonnement Azure .

Installer le package

Ce package est conçu pour être utilisé avec Azure Identity pour JavaScript. Installez les @azure/identity et ce package à l’aide de npm:

npm install --save @azure/identity
npm install --save @azure/identity-broker

Environnements pris en charge

Les plug-ins Azure Identity pour JavaScript prennent en charge les versions stables (même numérotées) de Node.js à partir de la version 18. Bien que les plug-ins puissent s’exécuter dans d’autres versions Node.js, aucune prise en charge n’est garantie. @azure/identity-broker ne prend pas en charge les environnements de navigateur.

Concepts clés

S’il s’agit de votre première utilisation de @azure/identity ou de l’ID Microsoft Entra, nous vous recommandons de lire à l’aide de @azure/identity avec l’ID Microsoft Entra en premier. Ce document vous donnera une compréhension plus approfondie de la plateforme et de la façon de configurer correctement votre compte Azure.

Handles de fenêtre parent

Lors de l’authentification auprès du répartiteur via InteractiveBrowserCredential, un handle de fenêtre parent est requis pour vous assurer que la boîte de dialogue d’authentification s’affiche correctement sur la fenêtre de demande. Dans le contexte des interfaces utilisateur graphiques sur les appareils, un handle de fenêtre est un identificateur unique que le système d’exploitation affecte à chaque fenêtre. Pour le système d’exploitation Windows, ce handle est une valeur entière qui sert de référence à une fenêtre spécifique.

Passthrough du compte Microsoft (MSA)

Les comptes Microsoft (MSA) sont des comptes personnels créés par les utilisateurs pour accéder aux services Microsoft. Le passage MSA est une configuration héritée qui permet aux utilisateurs d’obtenir des jetons aux ressources qui n’acceptent normalement pas les connexions MSA. Cette fonctionnalité est disponible uniquement pour les applications internes. Les utilisateurs qui s’authentifient avec une application configurée pour utiliser le passage MSA peuvent définir legacyEnableMsaPassthrough sur true à l’intérieur de InteractiveBrowserCredentialNodeOptions.brokerOptions pour permettre à ces comptes personnels d’être répertoriés par WAM.

URI de redirection

Les applications Microsoft Entra s’appuient sur des URI de redirection pour déterminer où envoyer la réponse d’authentification une fois qu’un utilisateur s’est connecté. Pour activer l’authentification répartie via WAM, un URI de redirection correspondant au modèle suivant doit être inscrit à l’application :

ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

Plug-ins Azure Identity

Depuis @azure/identity version 2.0.0, la bibliothèque cliente Identity pour JavaScript inclut une API de plug-in. Ce package (@azure/identity-broker) exporte un objet de plug-in que vous devez passer en tant qu’argument à la fonction de useIdentityPlugin de niveau supérieur à partir du package @azure/identity. Activez le répartiteur natif dans votre programme comme suit :

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});

Après avoir appelé useIdentityPlugin, le plug-in broker natif est inscrit au package @azure/identity et sera disponible sur le InteractiveBrowserCredential qui prend en charge l’authentification du répartiteur WAM. Ces informations d’identification ont brokerOptions dans les options du constructeur.

Exemples

Une fois le plug-in inscrit, vous pouvez activer l’authentification du répartiteur WAM en transmettant brokerOptions avec une propriété enabled définie sur true à un constructeur d’informations d’identification. Dans l’exemple suivant, nous utilisons la InteractiveBrowserCredential.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substring(0, 10), "...");

Pour obtenir un exemple complet d’utilisation d’une application Electron pour récupérer un handle de fenêtre, consultez cet exemple.

Utiliser le compte par défaut pour la connexion

Lorsque l’option useDefaultBrokerAccount est définie sur true, les informations d’identification tentent d’utiliser silencieusement le compte broker par défaut. Si l’utilisation du compte par défaut échoue, les informations d’identification reviennent à l’authentification interactive.

import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";
import { nativeBrokerPlugin } from "@azure/identity-broker";

useIdentityPlugin(nativeBrokerPlugin);
const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
    useDefaultBrokerAccount: true,
    parentWindowHandle: new Uint8Array(0), // This should be a handle to the parent window
  },
});
// We'll use the Microsoft Graph scope as an example
const scope = "https://graph.microsoft.com/.default";
// Print out part of the access token
console.log((await credential.getToken(scope)).token.substr(0, 10), "...");

Dépannage

Consultez le [guide de résolution des problèmes] Azure Identity [https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md] pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Exploitation forestière

L’activation de la journalisation peut vous aider à découvrir des informations utiles sur les échecs. Pour afficher un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans la @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Étapes suivantes

Fournir des commentaires

Si vous rencontrez des bogues ou que vous avez des suggestions, ouvrez un problème.

Contribuant

Si vous souhaitez contribuer à cette bibliothèque, consultez le guide de contribution pour en savoir plus sur la génération et le test du code.

Impressions