Udostępnij za pośrednictwem

Wtyczka tożsamości platformy Azure na potrzeby uwierzytelniania obsługiwanego przez brokera

  • Artykuł

Ten pakiet udostępnia wtyczkę do biblioteki tożsamości platformy Azure dla języka JavaScript (@azure/identity), która umożliwia korzystanie z brokera uwierzytelniania, takiego jak WAM.

Broker uwierzytelniania to aplikacja uruchamiana na komputerze użytkownika, która zarządza uzgadnianiami uwierzytelniania i konserwacją tokenów dla połączonych kont. Obecnie obsługiwany jest tylko broker uwierzytelniania systemu Windows, Menedżer kont sieci Web (WAM).

Dokumentacja referencyjna interfejsu API kodu źródłowego | przykłady | API | [Dokumentacja identyfikatora Entra firmy Microsoft] (https://learn.microsoft.com/entra/identity/)

Wprowadzenie

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

useIdentityPlugin(nativeBrokerPlugin);

Warunki wstępne

  • Subskrypcja platformy Azure .

Instalowanie pakietu

Ten pakiet jest przeznaczony do użycia z usługą Azure Identity for JavaScript. Zainstaluj zarówno @azure/identity, jak i ten pakiet przy użyciu npm:

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

Obsługiwane środowiska

Wtyczki tożsamości platformy Azure dla języka JavaScript obsługują stabilne (parzysty) wersje Node.js począwszy od wersji 18. Chociaż wtyczki mogą działać w innych wersjach Node.js, nie ma gwarantowanej obsługi. @azure/identity-broker nie obsługuje środowisk przeglądarki.

Kluczowe pojęcia

Jeśli używasz @azure/identity lub identyfikatora Entra firmy Microsoft po raz pierwszy, zalecamy przeczytanie Używanie @azure/identity z identyfikatorem Entra firmy Microsoft. Ten dokument zawiera bardziej szczegółowe informacje na temat platformy i sposobu prawidłowego konfigurowania konta platformy Azure.

Uchwyty okien nadrzędnych

Podczas uwierzytelniania za pomocą brokera za pośrednictwem InteractiveBrowserCredentialwymagane jest dojście okna nadrzędnego, aby upewnić się, że okno dialogowe uwierzytelniania jest wyświetlane poprawnie w oknie żądania. W kontekście graficznych interfejsów użytkownika na urządzeniach uchwyt okna jest unikatowym identyfikatorem przypisywanym przez system operacyjny do każdego okna. W przypadku systemu operacyjnego Windows ta obsługa jest wartością całkowitą, która służy jako odwołanie do określonego okna.

Przekazywanie konta Microsoft (MSA)

Konta Microsoft (MSA) to konta osobiste utworzone przez użytkowników w celu uzyskania dostępu do usług firmy Microsoft. Przekazywanie msA jest starszą konfiguracją, która umożliwia użytkownikom uzyskiwanie tokenów do zasobów, które zwykle nie akceptują logowań MSA. Ta funkcja jest dostępna tylko dla aplikacji innych firm. Użytkownicy uwierzytelnieni za pomocą aplikacji skonfigurowanej do korzystania z przekazywania MSA mogą ustawić legacyEnableMsaPassthrough na true wewnątrz InteractiveBrowserCredentialNodeOptions.brokerOptions, aby zezwolić na wyświetlanie tych kont osobistych przez WAM.

Identyfikatory URI przekierowania

Aplikacje Firmy Microsoft Entra korzystają z identyfikatorów URI przekierowania, aby określić, gdzie wysłać odpowiedź uwierzytelniania po zalogowaniu użytkownika. Aby włączyć uwierzytelnianie obsługiwane przez brokera za pośrednictwem WAM, identyfikator URI przekierowania zgodny z następującym wzorcem powinien zostać zarejestrowany w aplikacji:

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

Wtyczki tożsamości platformy Azure

Od wersji @azure/identity 2.0.0 biblioteka klienta identity dla języka JavaScript zawiera interfejs API wtyczki. Ten pakiet (@azure/identity-broker) eksportuje obiekt wtyczki, który należy przekazać jako argument do funkcji useIdentityPlugin najwyższego poziomu z pakietu @azure/identity. Włącz brokera natywnego w programie w następujący sposób:

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 wywołaniu useIdentityPluginwtyczka brokera natywnego jest zarejestrowana w pakiecie @azure/identity i będzie dostępna w InteractiveBrowserCredential, która obsługuje uwierzytelnianie brokera WAM. To poświadczenie ma brokerOptions w opcjach konstruktora.

Przykłady

Po zarejestrowaniu wtyczki można włączyć uwierzytelnianie brokera WAM, przekazując brokerOptions z właściwością enabled ustawioną na true konstruktora poświadczeń. W poniższym przykładzie użyjemy 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), "...");

Aby zapoznać się z kompletnym przykładem użycia aplikacji Electron do pobierania uchwytu okna, zobacz tym przykładzie.

Użyj domyślnego konta do logowania

Gdy opcja useDefaultBrokerAccount jest ustawiona na true, poświadczenie spróbuje dyskretnie użyć domyślnego konta brokera. Jeśli użycie konta domyślnego zakończy się niepowodzeniem, poświadczenie wróci do uwierzytelniania interakcyjnego.

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

Rozwiązywanie problemów

Aby uzyskać szczegółowe informacje na temat diagnozowania różnych scenariuszy awarii, zobacz Azure Identity [przewodnik rozwiązywania problemów][https://github.com/Azure/azure-sdk-for-js/blob/@azure/identity-broker_1.1.0/sdk/identity/identity/TROUBLESHOOTING.md].

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Następne kroki

Prześlij opinię

Jeśli napotkasz usterki lub masz sugestie, otworzyć problem.

Przyczyniając się

Jeśli chcesz współtworzyć tę bibliotekę, zobacz przewodnik współtworzenia, aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

wrażenia