Modul plug-in Azure Identity pro zprostředkované ověřování

Tento balíček poskytuje modul plug-in do knihovny identit Azure pro JavaScript (@azure/identity), který umožňuje používat zprostředkovatele ověřování, jako je WAM.

Zprostředkovatel ověřování je aplikace, která běží na počítači uživatele, která spravuje ověřování metodou handshake a údržbu tokenů pro připojené účty. V současné době je podporován pouze zprostředkovatel ověřování Systému Windows, Správce webových účtů (WAM).

Zdrojový kód | Vzorky | Referenční dokumentace k rozhraní API | [Microsoft Entra ID documentation] (https://learn.microsoft.com/entra/identity/)

Začínáme

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

useIdentityPlugin(nativeBrokerPlugin);

Požadavky

• Předplatné Azure

Instalace balíčku

Tento balíček je navržený pro použití se službou Azure Identity for JavaScript. Nainstalujte oba a @azure/identity tento balíček pomocí npm:

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

Podporovaná prostředí

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

Klíčové koncepty

Pokud používáte @azure/identity poprvé nebo Microsoft Entra ID, doporučujeme, abyste si napřed přečetli téma Používání @azure/identity s Id Microsoft Entra . Tento dokument vám poskytne hlubší znalosti o platformě a o tom, jak správně nakonfigurovat účet Azure.

Popisovače nadřazených oken

Při ověřování u zprostředkovatele přes InteractiveBrowserCredentialje potřeba popisovač nadřazeného okna, aby se zajistilo, že se dialogové okno ověřování správně zobrazí 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 tento popisovač celočíselnou hodnotou, která slouží jako odkaz na konkrétní okno.

Předávání účtu Microsoft (MSA)

Účty Microsoft (MSA) jsou osobní účty vytvořené uživateli pro přístup ke službám Microsoftu. 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 k dispozici pouze pro aplikace první strany. Uživatelé, kteří se ověřují pomocí aplikace, která je nakonfigurovaná tak, aby používala předávání MSA, můžou nastavit legacyEnableMsaPassthrough uvnitř trueInteractiveBrowserCredentialNodeOptions.brokerOptions , aby tyto osobní účty mohly být uvedené ve WAM.

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

Aplikace Microsoft Entra se spoléhají na identifikátory URI přesměrování, aby určily, kam mají odeslat ověřovací odpověď po přihlášení uživatele. Pokud chcete povolit zprostředkované ověřování prostřednictvím WAM, měl by být v aplikaci zaregistrovaný identifikátor URI přesměrování odpovídající následujícímu vzoru:

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

Moduly plug-in Azure Identity

@azure/identity Od verze 2.0.0 obsahuje 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 nejvyšší úrovně useIdentityPlugin z @azure/identity balíčku. Nativního zprostředkovatele povolte ve svém programu následujícím způsobem:

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

useIdentityPlugin(nativeBrokerPlugin);

const credential = new InteractiveBrowserCredential({
  brokerOptions: {
    enabled: true,
  },
});

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

Příklady

Po registraci modulu plug-in můžete povolit ověřování zprostředkovatele WAM předáním brokerOptionsenabled vlastnosti nastavené na true konstruktor přihlašovacích údajů. V následujícím příkladu použijeme InteractiveBrowserCredential.

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

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

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

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Úplný příklad použití aplikace Electron k načtení popisovače okna najdete v této ukázce.

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

useDefaultBrokerAccount Pokud je možnost 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 { nativeBrokerPlugin } from "@azure/identity-broker";
import { useIdentityPlugin, InteractiveBrowserCredential } from "@azure/identity";

useIdentityPlugin(nativeBrokerPlugin);

async function main() {
  const credential = new InteractiveBrowserCredential({
    brokerOptions: {
      enabled: true,
      useDefaultBrokerAccount: true,
      parentWindowHandle: <insert_current_window_handle>
    },
  });

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

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

Poradce při potížích

Podrobnosti o tom, jak diagnostikovat různé scénáře selhání, najdete v tématu Azure Identity [průvodce odstraňováním potíží].https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.0.1/sdk/identity/identity/TROUBLESHOOTING.md

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné 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ávrhy, otevřete problém.

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si průvodce přispívání , kde se dozvíte další informace o tom, jak sestavit a otestovat kód.