Biblioteka klienta tożsamości platformy Azure dla języka JavaScript — wersja 4.4.0

Biblioteka tożsamości platformy Azure udostępnia uwierzytelnianie tokenów Microsoft Entra ID (wcześniej usługi Azure Active Directory) za pomocą zestawu wygodnych implementacji TokenCredential.

Przykłady różnych poświadczeń można znaleźć na stronie przykładów Azure Identity.

Kluczowe linki:

• kod źródłowy
• pakiet (npm)
• Dokumentacja referencyjna interfejsu API
• dokumentacja identyfikatora entra firmy Microsoft
• przykładów

Wprowadzenie

Obecnie obsługiwane środowiska

• wersje Node.js LTS
  • Uwaga: Jeśli aplikacja działa w wersji Node.js w wersji 8 lub starszej i nie można uaktualnić wersji Node.js do najnowszej stabilnej wersji, przypnij zależność @azure/identity do wersji 1.1.0.
• Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.
  • Uwaga: wśród różnych poświadczeń wyeksportowanych w tej bibliotece InteractiveBrowserCredential jest jedyną obsługiwaną w przeglądarce.

Aby uzyskać więcej informacji, zobacz nasze zasad pomocy technicznej.

Instalowanie pakietu

Zainstaluj usługę Azure Identity przy użyciu npm:

npm install --save @azure/identity

Warunki wstępne

• Subskrypcja platformy Azure .
• Opcjonalnie: interfejs wiersza polecenia platformy Azure i/lub programu Azure PowerShell może być również przydatny do uwierzytelniania w środowisku projektowym i zarządzania rolami kont.

Kiedy należy używać @azure/identity

Klasy poświadczeń udostępniane przez @azure/identity koncentrują się na zapewnieniu najprostszego sposobu uwierzytelniania klientów zestawu Azure SDK lokalnie, w środowiskach deweloperskich i w środowisku produkcyjnym. Dążymy do uproszczenia i rozsądnego wsparcia protokołów uwierzytelniania, aby uwzględnić większość scenariuszy uwierzytelniania możliwych na platformie Azure. Aktywnie rozwijamy się, aby uwzględnić więcej scenariuszy. Aby uzyskać pełną listę oferowanych poświadczeń, zobacz sekcję Credential Classes (Klasy poświadczeń ).

Wszystkie typy poświadczeń udostępniane przez @azure/identity są obsługiwane w Node.js. W przypadku przeglądarek InteractiveBrowserCredential jest typem poświadczeń używanym w przypadku podstawowych scenariuszy uwierzytelniania.

Większość typów poświadczeń oferowanych przez usługę @azure/identity używa biblioteki microsoft Authentication Library for JavaScript (MSAL.js). W szczególności używamy bibliotek MSAL.js w wersji 2, które używają przepływu kodu autoryzacji OAuth 2.0 OAuth 2.0 z PKCE i są zgodne z protokołem OpenID. Chociaż @azure/identity koncentruje się na prostotzie, biblioteki MSAL.js, takie jak @azure/msal-common, @azure/msal-nodei @azure/msal-browser, są zaprojektowane tak, aby zapewnić niezawodną obsługę protokołów uwierzytelniania, które obsługuje platforma Azure.

Kiedy należy użyć czegoś innego

Typy poświadczeń @azure/identity to implementacje @azure/core-authklasy TokenCredential. W zasadzie każdy obiekt z metodą getToken, która spełnia getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null>, będzie działać jako TokenCredential. Oznacza to, że deweloperzy mogą pisać własne typy poświadczeń, aby obsługiwać przypadki uwierzytelniania, które nie są objęte @azure/identity. Aby dowiedzieć się więcej, zobacz poświadczenia niestandardowe.

Chociaż nasze typy poświadczeń obsługują wiele zaawansowanych przypadków, deweloperzy mogą chcieć mieć pełną kontrolę nad protokołem uwierzytelniania. W tym przypadku użycia zalecamy bezpośrednie użycie biblioteki Microsoft Authentication Library for JavaScript (MSAL.js). Więcej informacji można uzyskać za pośrednictwem następujących linków:

• Przedstawiamy niektóre zaawansowane przypadki użycia @azure/identity na stronie Przykłady tożsamości platformy Azure.
  • W tym miejscu znajduje się sekcja Advanced Examples (Zaawansowane przykłady).
  • Mamy również sekcję przedstawiającą sposób uwierzytelnianie przy użyciu biblioteki MSAL bezpośrednio.

W przypadku zaawansowanych przepływów pracy uwierzytelniania w przeglądarce mamy sekcję, w której pokazano, jak używać biblioteki @azure/msal-browser bezpośrednio do uwierzytelniania klientów zestawu Azure SDK.

Uwierzytelnianie klienta w środowisku projektowym

Chociaż zalecamy używanie tożsamości zarządzanej w aplikacji hostowanej na platformie Azure, zwykle deweloper używa własnego konta do uwierzytelniania wywołań usług platformy Azure podczas debugowania i wykonywania kodu lokalnie. Istnieje kilka narzędzi programistycznych, których można użyć do przeprowadzenia tego uwierzytelniania w środowisku deweloperów.

Uwierzytelnianie za pomocą interfejsu wiersza polecenia dla deweloperów platformy Azure

Deweloperzy kodujący poza środowiskiem IDE mogą również używać interfejsu wiersza polecenia dla deweloperów platformy Azure do uwierzytelniania. Aplikacje korzystające z DefaultAzureCredential lub AzureDeveloperCliCredential mogą następnie używać tego konta do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby uwierzytelnić się za pomocą interfejsu wiersza polecenia dewelopera platformy Azure , użytkownicy mogą uruchomić polecenie azd auth login. W przypadku użytkowników działających w systemie z domyślną przeglądarką internetową interfejs wiersza polecenia dewelopera platformy Azure uruchomi przeglądarkę w celu uwierzytelnienia użytkownika.

W przypadku systemów bez domyślnej przeglądarki internetowej polecenie azd auth login --use-device-code użyje przepływu uwierzytelniania kodu urządzenia.

Uwierzytelnianie za pośrednictwem interfejsu wiersza polecenia platformy Azure

Aplikacje korzystające z AzureCliCredential, niezależnie od tego, czy bezpośrednio, czy za pośrednictwem DefaultAzureCredential, mogą używać konta interfejsu wiersza polecenia platformy Azure do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby uwierzytelnić się za pomocą interfejsu wiersza polecenia platformy Azure użytkownicy mogą uruchomić polecenie az login. W przypadku użytkowników działających w systemie z domyślną przeglądarką internetową interfejs wiersza polecenia platformy Azure uruchomi przeglądarkę w celu uwierzytelnienia użytkownika.

logowanie

W przypadku systemów bez domyślnej przeglądarki internetowej polecenie az login użyje przepływu uwierzytelniania kodu urządzenia. Użytkownik może również wymusić użycie przepływu kodu urządzenia przez interfejs wiersza polecenia platformy Azure, a nie uruchomienie przeglądarki, określając argument --use-device-code.

logowania do konta interfejsu wiersza polecenia platformy Azure

Uwierzytelnianie za pomocą programu Azure PowerShell

Aplikacje korzystające z AzurePowerShellCredential, niezależnie od tego, czy bezpośrednio, czy za pośrednictwem DefaultAzureCredential, mogą używać konta połączonego z programem Azure PowerShell do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby uwierzytelnić się przy użyciu programu Azure PowerShell, użytkownicy mogą uruchomić polecenie cmdlet Connect-AzAccount. Domyślnie, podobnie jak w przypadku interfejsu wiersza polecenia platformy Azure, Connect-AzAccount uruchomi domyślną przeglądarkę internetową w celu uwierzytelnienia konta użytkownika.

logowanie

Jeśli uwierzytelnianie interakcyjne nie może być obsługiwane w sesji, argument -UseDeviceAuthentication wymusi użycie przepływu uwierzytelniania kodu urządzenia zamiast tego, podobnie jak odpowiednia opcja w poświadczeniu interfejsu wiersza polecenia platformy Azure.

Uwierzytelnianie za pomocą programu Visual Studio Code

Deweloperzy korzystający z programu Visual Studio Code mogą używać rozszerzenia konta platformy Azure do uwierzytelniania za pośrednictwem edytora. Aplikacje korzystające z VisualStudioCodeCredential mogą następnie używać tego konta do uwierzytelniania wywołań w aplikacji podczas uruchamiania lokalnego.

Aby uwierzytelnić się w programie Visual Studio Code, upewnij się, że rozszerzenie konta platformy Azure jest zainstalowane. Po zainstalowaniu otwórz paletę poleceń i uruchom polecenie Azure: Zaloguj się.

Ponadto użyj pakietu wtyczki @azure/identity-vscode. Ten pakiet zapewnia zależności VisualStudioCodeCredential i włącza go. Zobacz Plugins.

Jest to znany problem, który VisualStudioCodeCredential nie działa z rozszerzenia konta platformy Azure nowsze wersje niż 0.9.11. Długoterminowe rozwiązanie tego problemu jest w toku. W międzyczasie rozważ uwierzytelnienie za pośrednictwem interfejsu wiersza polecenia platformy Azure.

Uwierzytelnianie klienta w przeglądarkach

Aby uwierzytelnić klientów zestawu Azure SDK w przeglądarkach internetowych, oferujemy InteractiveBrowserCredential, które można ustawić tak, aby używać przekierowania lub wyskakujących okienek w celu ukończenia przepływu uwierzytelniania. Najpierw należy utworzyć rejestracji aplikacji platformy Azure w witrynie Azure Portal dla aplikacji internetowej.

Kluczowe pojęcia

Jeśli używasz @azure/identity lub microsoft Entra ID po raz pierwszy, przeczytaj Using @azure/identity with Microsoft Entra ID first (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.

Poświadczenia

Poświadczenie to klasa, która zawiera lub może uzyskać dane potrzebne klientowi usługi do uwierzytelniania żądań. Klienci usług w zestawie Azure SDK akceptują poświadczenia podczas ich konstruowania. Klienci usług używają tych poświadczeń do uwierzytelniania żądań w usłudze.

Biblioteka tożsamości platformy Azure koncentruje się na uwierzytelnianiu OAuth za pomocą identyfikatora Entra firmy Microsoft i oferuje różne klasy poświadczeń umożliwiające uzyskanie tokenu entra firmy Microsoft w celu uwierzytelniania żądań obsługi. Wszystkie klasy poświadczeń w tej bibliotece to implementacje TokenCredential klasy abstrakcyjnej, a dowolny z nich może służyć do konstruowania klientów usługi, którzy mogą uwierzytelniać się za pomocą tokenuCredential.

Zobacz Credential Classes.

Wartość domyślnaAzureCredential

DefaultAzureCredential jest odpowiednia dla większości scenariuszy, w których aplikacja ma zostać ostatecznie uruchomiona na platformie Azure. Jest to spowodowane tym, że DefaultAzureCredential łączy poświadczenia często używane do uwierzytelniania podczas wdrażania przy użyciu poświadczeń używanych do uwierzytelniania w środowisku projektowym.

Uwaga: DefaultAzureCredential ma na celu uproszczenie rozpoczynania pracy z zestawem SDK przez obsługę typowych scenariuszy z rozsądnymi zachowaniami domyślnymi. Deweloperzy, którzy chcą mieć większą kontrolę lub którego scenariusz nie jest obsługiwany przez ustawienia domyślne, powinni używać innych typów poświadczeń.

Jeśli jest używany z Node.js, DefaultAzureCredential podejmie próbę uwierzytelnienia za pomocą następujących mechanizmów w następującej kolejności:

1. Environment — DefaultAzureCredential odczytuje informacje o koncie określone za pośrednictwem zmiennych środowiskowych i używa ich do uwierzytelniania.
2. tożsamość obciążenia — jeśli aplikacja zostanie wdrożona w usłudze Azure Kubernetes Service z włączoną tożsamością zarządzaną, DefaultAzureCredential będzie ją uwierzytelniać.
3. tożsamości zarządzanej — jeśli aplikacja zostanie wdrożona na hoście platformy Azure z włączoną tożsamością zarządzaną, DefaultAzureCredential zostanie uwierzytelniony przy użyciu tego konta.
4. interfejsu wiersza polecenia platformy Azure — jeśli deweloper uwierzytelnił konto za pomocą polecenia interfejsu wiersza polecenia platformy Azure az login, DefaultAzureCredential zostanie uwierzytelniony przy użyciu tego konta.
5. programu Azure PowerShell — jeśli deweloper uwierzytelnił się przy użyciu polecenia Connect-AzAccount modułu Azure PowerShell, DefaultAzureCredential zostanie uwierzytelniony przy użyciu tego konta.
6. interfejsu wiersza polecenia dewelopera platformy Azure — jeśli deweloper uwierzytelnił konto za pomocą polecenia interfejsu wiersza polecenia dewelopera platformy Azure azd auth login, DefaultAzureCredential zostanie uwierzytelniony przy użyciu tego konta.

Zasady kontynuacji

Począwszy od wersji 3.3.0, DefaultAzureCredential spróbuje uwierzytelnić się przy użyciu wszystkich poświadczeń dewelopera, dopóki nie powiedzie się, niezależnie od błędów, które wystąpiły podczas poprzednich poświadczeń dewelopera. Na przykład poświadczenie dewelopera może próbować uzyskać token i zakończyć się niepowodzeniem, dlatego DefaultAzureCredential będzie nadal przechodzić do następnego poświadczenia w przepływie. Wdrożone poświadczenia usługi zatrzymają przepływ z zgłoszonym wyjątkiem, jeśli będą mogły podjąć próbę pobrania tokenu, ale nie otrzymają tego.

Umożliwia to wypróbowanie wszystkich poświadczeń dewelopera na maszynie przy jednoczesnym przewidywalnym wdrożeniu.

Uwaga dotycząca VisualStudioCodeCredential

Ze względu na znany problem VisualStudioCodeCredential został usunięty z łańcucha tokenów DefaultAzureCredential. Po rozwiązaniu problemu w przyszłej wersji ta zmiana zostanie przywrócona.

Wtyczki

Usługa Azure Identity dla języka JavaScript udostępnia interfejs API wtyczki, który umożliwia udostępnianie pewnych funkcji za pośrednictwem oddzielnych pakietów wtyczek . Pakiet @azure/identity eksportuje funkcję najwyższego poziomu (useIdentityPlugin), która może służyć do włączenia wtyczki. Udostępniamy dwa pakiety wtyczek:

• @azure/identity-broker, która zapewnia obsługę uwierzytelniania obsługiwanego przez brokera natywnego, takiego jak Menedżer kont sieci Web.
• @azure/identity-cache-persistence, która zapewnia trwałe buforowanie tokenów w Node.js przy użyciu natywnego bezpiecznego systemu magazynu dostarczonego przez system operacyjny. Ta wtyczka umożliwia utrwalanie buforowanych wartości access_token między sesjami, co oznacza, że interakcyjny przepływ logowania nie musi być powtarzany, o ile jest dostępny buforowany token.

Przykłady

Więcej przykładów użycia różnych poświadczeń można znaleźć na stronie przykładów tożsamości platformy Azure

Uwierzytelnianie przy użyciu DefaultAzureCredential

W tym przykładzie pokazano uwierzytelnianie KeyClient z @azure/keyvault-keys biblioteki klienta przy użyciu DefaultAzureCredential.

// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.

// Azure Key Vault service to use
import { KeyClient } from "@azure/keyvault-keys";

// Azure authentication library to access Azure Key Vault
import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Określanie tożsamości zarządzanej przypisanej przez użytkownika przy użyciu DefaultAzureCredential

Stosunkowo typowy scenariusz obejmuje uwierzytelnianie przy użyciu tożsamości zarządzanej przypisanej przez użytkownika dla zasobu platformy Azure. Zapoznaj się z przykładem na temat uwierzytelniania tożsamości zarządzanej przypisanej przez użytkownika przy użyciu DefaultAzureCredential, aby zobaczyć, w jaki sposób jest to stosunkowo proste zadanie, które można skonfigurować przy użyciu zmiennych środowiskowych lub w kodzie.

Definiowanie niestandardowego przepływu uwierzytelniania przy użyciu ChainedTokenCredential

Chociaż DefaultAzureCredential jest na ogół najszybszym sposobem rozpoczęcia tworzenia aplikacji dla platformy Azure, bardziej zaawansowani użytkownicy mogą chcieć dostosować poświadczenia brane pod uwagę podczas uwierzytelniania. ChainedTokenCredential umożliwia użytkownikom łączenie wielu wystąpień poświadczeń w celu zdefiniowania dostosowanego łańcucha poświadczeń. W tym przykładzie pokazano tworzenie ChainedTokenCredential, które spróbuje przeprowadzić uwierzytelnianie przy użyciu dwóch inaczej skonfigurowanych wystąpień ClientSecretCredential, aby następnie uwierzytelnić KeyClient z @azure/keyvault-keys:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";

// When an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
const firstCredential = new ClientSecretCredential(tenantId, clientId, clientSecret);
const secondCredential = new ClientSecretCredential(tenantId, anotherClientId, anotherSecret);
const credentialChain = new ChainedTokenCredential(firstCredential, secondCredential);

// The chain can be used anywhere a credential is required
import { KeyClient } from "@azure/keyvault-keys";
const client = new KeyClient(vaultUrl, credentialChain);

Obsługa tożsamości zarządzanej

Uwierzytelnianie tożsamości zarządzanej jest obsługiwane za pośrednictwem lub klas poświadczeń bezpośrednio dla następujących usług platformy Azure:

• usług Azure App Service i Azure Functions
• azure arc
• usługi Azure Cloud Shell
• Azure Kubernetes Service
• usługi Azure Service Fabric
• usługi Azure Virtual Machines
• zestawów skalowania usługi Azure Virtual Machines

Aby zapoznać się z przykładami używania tożsamości zarządzanej do uwierzytelniania, zobacz przykłady.

Konfiguracja chmury

Poświadczenia są domyślnie uwierzytelniane w punkcie końcowym usługi Microsoft Entra dla chmury publicznej platformy Azure. Aby uzyskać dostęp do zasobów w innych chmurach, takich jak Azure Government lub chmura prywatna, skonfiguruj poświadczenia za pomocą argumentu authorityHost w konstruktorze. Interfejs AzureAuthorityHosts definiuje urzędy dla dobrze znanych chmur. W przypadku chmury dla instytucji rządowych USA można utworzyć wystąpienie poświadczeń w następujący sposób:

import { AzureAuthorityHosts, ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  }
);

Nie wszystkie poświadczenia wymagają tej konfiguracji. Poświadczenia uwierzytelniające się za pomocą narzędzia programistycznego, takiego jak AzureCliCredential, używają konfiguracji tego narzędzia. Podobnie VisualStudioCodeCredential akceptuje argument authorityHost, ale domyślnie jest to ustawienie authorityHost zgodne z Azure: Cloud programu Visual Studio Code.

Klasy poświadczeń

Uwierzytelnianie aplikacji hostowanych na platformie Azure

Uwierzytelnianie jednostek usługi

Uwierzytelnianie użytkowników

Uwierzytelnianie za pomocą narzędzi programistycznych

Zmienne środowiskowe

DefaultAzureCredential i EnvironmentCredential można skonfigurować za pomocą zmiennych środowiskowych. Każdy typ uwierzytelniania wymaga wartości dla określonych zmiennych.

Jednostka usługi z wpisem tajnym

Jednostka usługi z certyfikatem

Nazwa użytkownika i hasło

Próba konfiguracji jest podejmowana w powyższej kolejności. Jeśli na przykład wartości dla klucza tajnego klienta i certyfikatu są obecne, zostanie użyty klucz tajny klienta.

Ciągła ocena dostępu

Od wersji 3.3.0 dostęp do zasobów chronionych przez oceny ciągłego dostępu (CAE) jest możliwy dla poszczególnych żądań. Można to włączyć przy użyciu interfejsu API GetTokenOptions.enableCae(boolean). Funkcja CAE nie jest obsługiwana w przypadku poświadczeń dewelopera.

Buforowanie tokenów

Buforowanie tokenów to funkcja udostępniana przez bibliotekę tożsamości platformy Azure, która umożliwia aplikacjom:

• Tokeny pamięci podręcznej w pamięci (ustawienie domyślne) i na dysku (zgoda).
• Zwiększ odporność i wydajność.
• Zmniejsz liczbę żądań wysyłanych do identyfikatora Entra firmy Microsoft w celu uzyskania tokenów dostępu.

Biblioteka tożsamości platformy Azure oferuje buforowanie zarówno w pamięci, jak i na dysku trwałym. Aby uzyskać więcej informacji, zobacz dokumentację buforowania tokenów .

Uwierzytelnianie obsługiwane przez brokera

Broker uwierzytelniania to aplikacja uruchamiana na komputerze użytkownika i zarządza uzgadniania uwierzytelniania i konserwacją tokenu dla połączonych kont. Obecnie obsługiwany jest tylko Menedżer kont sieci Web systemu Windows (WAM). Aby włączyć obsługę, użyj pakietu @azure/identity-broker. Aby uzyskać szczegółowe informacje na temat uwierzytelniania przy użyciu wam, zobacz dokumentację wtyczki brokera .

Rozwiązywanie problemów

Aby uzyskać pomoc dotyczącą rozwiązywania problemów, zobacz przewodnik rozwiązywania problemów z .

Następne kroki

Przeczytaj dokumentację

Dokumentację interfejsu API dla tej biblioteki można znaleźć w witrynie dokumentacji .

Obsługa biblioteki klienta

Biblioteki klienta i zarządzania wymienione na stronie wydania zestawu Azure SDK, które obsługują uwierzytelnianie firmy Microsoft Entra akceptują poświadczenia z tej biblioteki. Dowiedz się więcej o korzystaniu z tych bibliotek w dokumentacji, która jest połączona ze stroną wydań.

Znane problemy

Obsługa usługi Azure AD B2C

Ta biblioteka nie obsługuje usługi Azure AD B2C.

W przypadku innych otwartych problemów zobacz repozytorium GitHub biblioteki.

Prześlij opinię

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

Przyczyniając się

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