Azure Identity Plugin für brokered authentication

Dieses Paket stellt ein Plugin für die Azure Identity-Bibliothek für JavaScript (@azure/identity) bereit, das die Nutzung 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-Authentifizierung-Broker Web Account Manager (WAM) unterstützt.

Quellcode | Samples | API-Referenzdokumentation | Microsoft Entra ID Dokumentation

Erste Schritte

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

useIdentityPlugin(nativeBrokerPlugin);

Voraussetzungen

• Ein Azure Abonnement.

Hinweis: Für die lokale Entwicklung mit @azure/identity-brokermüssen Sie möglicherweise zusätzliche Tools installieren. node-gyp wird verwendet, um Addons für den Zugriff auf System-APIs zu kompilieren. Die Installationsanforderungen sind in der README node-gyp aufgeführt.

Unter Linux wird die Bibliothek verwendet libsecret , sodass Sie sie möglicherweise installieren müssen. Abhängig von Ihrer Verteilung müssen Sie den folgenden Befehl ausführen:

• Debian/Ubuntu: sudo apt-get install libsecret-1-dev
• Red Hat-basiert: sudo yum install libsecret-devel
• Arch Linux: sudo pacman -S libsecret

Installieren des Pakets

Dieses Paket ist dafür konzipiert, mit Azure Identity für JavaScript verwendet zu werden. 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-Plugins für JavaScript unterstützen stabile (gerade) Versionen von Node.js ab v20. 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 zum ersten Mal @azure/identity oder Microsoft Entra ID verwenden, empfehlen wir, zuerst Using @azure/identity with Microsoft Entra ID zu lesen. Dieses Dokument vermittelt Ihnen ein tieferes Verständnis der Plattform und wie Sie Ihr Azure-Konto korrekt konfigurieren.

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 dieser Handle ein ganzzahliger Wert, der als Referenz auf ein bestimmtes Fenster dient.

Microsoft-Konto (MSA) Passthrough

Microsoft-Konten (MSA) sind persönliche Konten, die von Nutzern erstellt werden, um auf Microsoft Services zuzugreifen. 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 verlassen sich auf Weiterleitungs-URIs, um zu bestimmen, wohin die Authentifizierungsantwort nach dem Anmelden des Benutzers gesendet werden soll. 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 plugins

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.

Notes: Seit @azure/identity Version 4.11.0-beta.1 bietet DefaultAzureCredential Unterstützung für die Anmeldung über den Windows Web Account Manager. Aktivieren Sie den nativen Broker in Ihrem Programm wie folgt:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

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 Fensterhandles finden Sie unter dieses 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

Siehe den Azure Identity Fehlerbehebungsleitfaden für Details zur Diagnose verschiedener Fehlerszenarien.

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 du auf Bugs stößt oder Vorschläge hast, öffne ein Problem.

Beitragend

Wenn Sie zu dieser Bibliothek beitragen möchten, sehen Sie sich den beitragenden Leitfaden an, um mehr darüber zu erfahren, wie man den Code erstellt und testet.