Freigeben über

Azure Identity-Plug-In für die brokerierte Authentifizierung

  • Artikel

Dieses Paket stellt ein Plug-In zur Azure Identity-Bibliothek für JavaScript (@azure/identity) bereit, das die Verwendung eines Authentifizierungsbrokers wie WAM-ermöglicht.

Ein Authentifizierungsbroker ist eine Anwendung, die auf dem Computer eines Benutzers ausgeführt wird, der die Authentifizierungs-Handshakes und die Tokenwartung für verbundene Konten verwaltet. Derzeit wird nur der Windows-Authentifizierungsbroker Web Account Manager (WAM) unterstützt.

Quellcode | Beispiele | API-Referenzdokumentation | [Dokumentation zur Microsoft Entra-ID] (https://learn.microsoft.com/entra/identity/)

Erste Schritte

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

useIdentityPlugin(nativeBrokerPlugin);

Voraussetzungen

Installieren des Pakets

Dieses Paket wurde für die Verwendung mit Azure Identity for JavaScript entwickelt. Installieren Sie sowohl @azure/identity als auch dieses Paket mit npm:

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

Unterstützte Umgebungen

Azure Identity-Plug-Ins für JavaScript unterstützen stabile (gerade nummerierte) Versionen von Node.js ab v18. Während die Plug-Ins in anderen Node.js Versionen ausgeführt werden können, ist keine Unterstützung gewährleistet. @azure/identity-broker unterstützt keine Browserumgebungen.

Schlüsselkonzepte

Wenn Sie @azure/identity- oder Microsoft Entra-ID zum ersten Mal verwenden, sollten Sie zuerst Verwenden von @azure/identity mit Microsoft Entra ID lesen. Dieses Dokument vermittelt Ihnen ein tieferes Verständnis der Plattform und die richtige Konfiguration Ihres Azure-Kontos.

Ziehpunkte für übergeordnete Fenster

Beim Authentifizieren mit dem Broker über InteractiveBrowserCredentialist ein übergeordnetes Fensterhandle erforderlich, um sicherzustellen, dass das Authentifizierungsdialogfeld über das anfordernde Fenster korrekt angezeigt wird. Im Kontext grafischer Benutzeroberflächen auf Geräten ist ein Fensterhandle ein eindeutiger Bezeichner, den das Betriebssystem jedem Fenster zuweist. Für das Windows-Betriebssystem ist dieses Handle ein ganzzahliger Wert, der als Verweis auf ein bestimmtes Fenster dient.

Microsoft-Konto (MSA) Passthrough

Microsoft-Konten (MSA) sind persönliche Konten, die von Benutzern für den Zugriff auf Microsoft-Dienste erstellt werden. MSA-Passthrough ist eine Legacykonfiguration, mit der Benutzer Token für Ressourcen abrufen können, die normalerweise keine MSA-Anmeldungen akzeptieren. Dieses Feature ist nur für Erstanbieteranwendungen verfügbar. Benutzer, die für die Verwendung von MSA-Passthrough konfiguriert sind, können legacyEnableMsaPassthrough auf true innerhalb InteractiveBrowserCredentialNodeOptions.brokerOptions festlegen, damit diese persönlichen Konten von WAM aufgelistet werden können.

Umleitungs-URIs

Microsoft Entra-Anwendungen basieren auf Umleitungs-URIs, um zu bestimmen, wo die Authentifizierungsantwort gesendet werden soll, nachdem sich ein Benutzer angemeldet hat. Um die vermittelte Authentifizierung über WAM zu aktivieren, sollte ein Umleitungs-URI mit dem folgenden Muster für die Anwendung registriert werden:

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

Azure Identity-Plug-Ins

Ab @azure/identity Version 2.0.0 enthält die Identitätsclientbibliothek für JavaScript eine Plug-In-API. Dieses Paket (@azure/identity-broker) exportiert ein Plug-In-Objekt, das Sie als Argument an die Funktion der obersten Ebene useIdentityPlugin aus dem @azure/identity-Paket übergeben müssen. Aktivieren Sie den nativen Broker in Ihrem Programm wie folgt:

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

Nach dem Aufrufen von useIdentityPluginwird das native Broker-Plug-In für das @azure/identity-Paket registriert und ist auf dem InteractiveBrowserCredential verfügbar, der die WAM-Brokerauthentifizierung unterstützt. Diese Anmeldeinformationen haben brokerOptions in den Konstruktoroptionen.

Beispiele

Nachdem das Plug-In registriert wurde, können Sie die WAM-Brokerauthentifizierung aktivieren, indem Sie brokerOptions mit einer enabled-Eigenschaft übergeben, die auf true an einen Anmeldeinformationskonstruktor festgelegt ist. Im folgenden Beispiel wird die InteractiveBrowserCredentialverwendet.

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), "...");

Ein vollständiges Beispiel für die Verwendung einer Electron-App zum Abrufen eines Fensterziehpunkts finden Sie in diesem Beispiel.

Verwenden des Standardkontos für die Anmeldung

Wenn die option useDefaultBrokerAccount auf truefestgelegt ist, versucht die Anmeldeinformationen, das Standardbrokerkonto automatisch zu verwenden. Wenn die Verwendung des Standardkontos fehlschlägt, fallen die Anmeldeinformationen auf die interaktive Authentifizierung zurück.

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), "...");

Fehlerbehebung

Weitere Informationen zum Diagnostizieren verschiedener Fehlerszenarien finden Sie im Azure Identity [Problembehandlungshandbuch][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md]

Protokollierung

Das Aktivieren der Protokollierung kann hilfreiche Informationen zu Fehlern aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die AZURE_LOG_LEVEL Umgebungsvariable auf infofest. Alternativ kann die Protokollierung zur Laufzeit durch Aufrufen von setLogLevel im @azure/loggeraktiviert werden:

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

setLogLevel("info");

Nächste Schritte

Feedback geben

Wenn Fehler auftreten oder Vorschläge vorliegen, öffnen Sie ein Problemöffnen.

Beitragend

Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie den leitfaden mitwirkenden, um mehr über das Erstellen und Testen des Codes zu erfahren.

Aufrufe