Azure Identity plugin for brokered authentication

Tento balíček poskytuje plugin ke knihovně Azure Identity pro JavaScript (@azure/identity), který umožňuje používat autentizační broker, jako je WAM.

Zprostředkovatel ověřování je aplikace, která běží na počítači uživatele, který spravuje ověřování handshakes a údržbu tokenů pro připojené účty. V současnosti je podporován pouze Windows authentication broker, Web Account Manager (WAM).

Zdrojový kód | Samples | API referenční dokumentace | Microsoft Entra ID dokumentace

Začínáme

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

useIdentityPlugin(nativeBrokerPlugin);

Požadavky

Poznámka: Pro místní vývoj pomocí @azure/identity-brokerprogramu může být nutné nainstalovat další nástroje. node-gyp se používá ke kompilaci doplňků pro přístup k systémovým API. Požadavky na instalaci jsou uvedeny v souboru README node-gyp.

V systému Linux knihovna používá libsecret , takže ji možná budete muset nainstalovat. V závislosti na vaší distribuci budete muset spustit následující příkaz:

  • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
  • Na bázi Red Hatu: sudo yum install libsecret-devel
  • Arch Linux: sudo pacman -S libsecret

Poznámka:

Zprostředkované ověřování je v současnosti podporováno pouze na Windows a Linuxu. Systém macOS zatím není podporován.

Instalace balíčku

Tento balíček je navržen pro použití s Azure Identity pro JavaScript. Nainstalujte @azure/identity i tento balíček pomocí npm:

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

Podporovaná prostředí

Azure Identity pluginy pro JavaScript podporují stabilní (sudé číslované) verze Node.js od v20. Moduly plug-in sice můžou běžet v jiných verzích Node.js, ale není zaručena žádná podpora. @azure/identity-broker nepodporuje prostředí prohlížeče.

Klíčové koncepty

Pokud používáte @azure/identity nebo Microsoft Entra ID poprvé, doporučujeme nejprve si přečíst Using @azure/identity s Microsoft Entra ID nejdříve. Tento dokument vám poskytne hlubší pochopení platformy a toho, jak správně nastavit svůj Azure účet.

Nadřazené úchyty oken

Při ověřování pomocí zprostředkovatele prostřednictvím InteractiveBrowserCredentialse vyžaduje popisovač nadřazeného okna, aby se zajistilo, že se ověřovací dialogové okno zobrazí správně v okně žádosti. V kontextu grafických uživatelských rozhraní na zařízeních je popisovač okna jedinečný identifikátor, který operační systém přiřadí každému oknu. Pro operační systém Windows je tato rukojeť celočíselná hodnota, která slouží jako odkaz na konkrétní okno.

Přenos účet Microsoft (MSA)

Microsoft účty (MSA) jsou osobní účty vytvořené uživateli pro přístup ke služby Microsoft. Předávání MSA je starší konfigurace, která uživatelům umožňuje získat tokeny k prostředkům, které obvykle nepřijímají přihlášení MSA. Tato funkce je dostupná jenom pro aplikace první strany. Uživatelé ověřující aplikaci, která je nakonfigurovaná tak, aby používala předávání MSA, můžou nastavit legacyEnableMsaPassthrough tak, aby true uvnitř InteractiveBrowserCredentialNodeOptions.brokerOptions, aby tyto osobní účty mohly být uvedené wam.

Identifikátory URI pro přesměrování

Aplikace Microsoft Entra spoléhají na přesměrovací URI, aby určily, kam poslat autentizační odpověď po přihlášení uživatele. Pokud chcete povolit zprostředkované ověřování prostřednictvím WAM, musí být do aplikace zaregistrovaný identifikátor URI přesměrování odpovídající následujícímu vzoru:

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

Azure Identity plugins

Od @azure/identity verze 2.0.0 zahrnuje klientská knihovna identit pro JavaScript rozhraní API modulu plug-in. Tento balíček (@azure/identity-broker) exportuje objekt modulu plug-in, který musíte předat jako argument funkci useIdentityPlugin nejvyšší úrovně z balíčku @azure/identity. V programu povolte nativního zprostředkovatele následujícím způsobem:

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

Po volání useIdentityPluginse nativní zprostředkovatelský modul plug-in zaregistruje do balíčku @azure/identity a bude k dispozici v InteractiveBrowserCredential, který podporuje ověřování zprostředkovatele WAM. Tyto přihlašovací údaje mají brokerOptions v možnostech konstruktoru.

Notes: Od verze @azure/identity 4.11.0-beta.1 poskytuje DefaultAzureCredential podporu přihlášení přes správce webových účtů Windows. V programu povolte nativního zprostředkovatele následujícím způsobem:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new DefaultAzureCredential();

Příklady

Po registraci modulu plug-in můžete povolit ověřování zprostředkovatele WAM předáním brokerOptions s vlastností enabled nastavenou na true konstruktoru přihlašovacích údajů. V následujícím příkladu používáme 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), "...");

Pro kompletní příklad použití aplikace Electron pro získání rukojeti okna viz tento vzorek.

Použití výchozího účtu pro přihlášení

Pokud je možnost useDefaultBrokerAccount nastavená na true, přihlašovací údaje se pokusí bezobslužně použít výchozí účet zprostředkovatele. Pokud se použití výchozího účtu nezdaří, přihlašovací údaje se vrátí k interaktivnímu ověřování.

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

Řešení problémů

Podrobnosti o diagnostice různých scénářů selhání najdete v Azure Identity troubleshooting guide kde najdete podrobnosti.

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info. Případně můžete protokolování povolit za běhu voláním setLogLevel v @azure/logger:

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

setLogLevel("info");

Další kroky

Poskytnutí zpětné vazby

Pokud narazíte na chyby nebo máte nějaké návrhy, prosím, otevřete číslo.

Přispívající

Pokud byste chtěli přispět do této knihovny, podívejte se na contributing guide kde se dozvíte více o tom, jak kód sestavit a testovat.

  • Last updated on