Azure Identity-plugin för mäklarautentisering

Detta paket tillhandahåller ett plugin till Azure Identity-biblioteket för JavaScript (@azure/identity) som möjliggör användning av en autentiseringsmäklare som WAM.

En autentiseringskoordinator är ett program som körs på en användares dator som hanterar handskakningar för autentisering och tokenunderhåll för anslutna konton. För närvarande stöds endast Windows authentication-mäklaren, Web Account Manager (WAM).

Källkod | Samples | API referensdokumentation | Microsoft Entra ID dokumentation

Komma igång

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

useIdentityPlugin(nativeBrokerPlugin);

Förutsättningar

• Ett Azure abonnemang.

För lokal utveckling med @azure/identity-brokerkan du behöva installera ytterligare verktyg. node-gyp används för att kompilera tillägg för åtkomst till system-API:er. Installationskraven anges i node-gyp README.

På Linux används libsecret biblioteket så du kan behöva installera det. Beroende på din distribution måste du köra följande kommando:

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

Installera paketet

Detta paket är utformat för att användas med Azure Identity för JavaScript. Installera både @azure/identity och det här paketet med hjälp av npm:

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

Miljöer som stöds

Azure Identity-plugins för JavaScript stöder stabila (jämna) versioner av Node.js från och med v20. Plugin-program kan köras i andra Node.js versioner, men inget stöd garanteras. @azure/identity-broker stöder inte webbläsarmiljöer.

Viktiga begrepp

Om detta är första gången du använder @azure/identity eller Microsoft Entra ID rekommenderar vi att du läser Using @azure/identity med Microsoft Entra ID först. Detta dokument ger dig en djupare förståelse för plattformen och hur du konfigurerar ditt Azure-konto korrekt.

Överordnade fönsterhandtag

När du autentiserar med asynkron meddelandekö via InteractiveBrowserCredentialkrävs ett överordnat fönsterhandtag för att säkerställa att autentiseringsdialogrutan visas korrekt över det begärande fönstret. I samband med grafiska användargränssnitt på enheter är ett fönsterhandtag en unik identifierare som operativsystemet tilldelar varje fönster. För operativsystemet Windows är detta handtag ett heltalsvärde som fungerar som referens till ett specifikt fönster.

Microsoft-konto (MSA) passthrough

Microsoft-konton (MSA) är personliga konton skapade av användare för att få tillgång till Microsoft-tjänster. MSA-genomströmning är en äldre konfiguration som gör det möjligt för användare att hämta token till resurser som normalt inte accepterar MSA-inloggningar. Den här funktionen är endast tillgänglig för program från första part. Användare som autentiserar med ett program som är konfigurerat för att använda MSA-genomströmning kan ställa in legacyEnableMsaPassthrough på true inuti InteractiveBrowserCredentialNodeOptions.brokerOptions så att dessa personliga konton kan visas av WAM.

Omdirigerings-URI:er

Microsoft Entra-applikationer förlitar sig på omdirigerings-URI:er för att avgöra vart autentiseringssvaret ska skickas efter att en användare har loggat in. För att aktivera asynkron autentisering via WAM bör en omdirigerings-URI som matchar följande mönster registreras i programmet:

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

Azure Identity plugins

Från och med @azure/identity version 2.0.0 innehåller identitetsklientbiblioteket för JavaScript ett plugin-API. Det här paketet (@azure/identity-broker) exporterar ett plugin-objekt som du måste skicka som ett argument till den översta useIdentityPlugin-funktionen från @azure/identity-paketet. Aktivera intern asynkron meddelandekö i ditt program på följande sätt:

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

När du har anropat useIdentityPluginregistreras det inbyggda broker-plugin-programmet till @azure/identity-paketet och kommer att vara tillgängligt på InteractiveBrowserCredential som stöder WAM-autentisering med asynkron autentisering. Den här autentiseringsuppgiften har brokerOptions i konstruktoralternativen.

Notes: Från och med @azure/identity version 4.11.0-beta.1 erbjuder DefaultAzureCredential stöd för inloggning via Windows Web Account Manager. Aktivera intern asynkron meddelandekö i ditt program på följande sätt:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Exempel

När plugin-programmet har registrerats kan du aktivera WAM-asynkron autentisering genom att skicka brokerOptions med en enabled egenskap inställd på true till en konstruktor för autentiseringsuppgifter. I följande exempel använder vi 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), "...");

För ett komplett exempel på att använda en Electron-app för att hämta ett fönsterhandtag, se detta exempel.

Använda standardkontot för inloggning

När alternativet useDefaultBrokerAccount är inställt på trueförsöker autentiseringsuppgifterna att tyst använda standardkontot för koordinator. Om det inte går att använda standardkontot återgår autentiseringsuppgifterna till interaktiv autentisering.

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

Felsökning

Se Azure Identity felsökningsguide för detaljer om hur man diagnostiserar olika felscenarier.

Skogsavverkning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Nästa steg

Ge feedback

Om du stöter på buggar eller har förslag, vänligen öppna ett problem.

Bidragande

Om du vill bidra till detta bibliotek, se guiden bidragande för att lära dig mer om hur man bygger och testar koden.