Azure Identity-Clientbibliothek für JavaScript – Version 4.5.0

Die Azure Identity-Bibliothek stellt Microsoft Entra ID( vormals Azure Active Directory) Tokenauthentifizierung über eine Reihe praktischer TokenCredential Implementierungen bereit.

Beispiele für verschiedene Anmeldeinformationen finden Sie auf der Seite Azure Identity-Beispiele.

Wichtige Links:

• Quellcode
• Package (npm)
• API-Referenzdokumentation
• Microsoft Entra Ausweisdokumente
• Beispiele

Erste Schritte

Derzeit unterstützte Umgebungen

• LTS-Versionen von Node.js
• Neueste Versionen von Safari, Chrome, Edge und Firefox.
  • Hinweis: Unter den verschiedenen Anmeldeinformationen, die in dieser Bibliothek exportiert wurden, ist InteractiveBrowserCredential die einzige, die im Browser unterstützt wird.

Weitere Informationen finden Sie in unserer Supportrichtlinie.

Installieren des Pakets

Installieren von Azure Identity mit npm:

npm install --save @azure/identity

Voraussetzungen

• Ein Azure-Abonnement.
• Optional: Die Azure CLI und/oder Azure PowerShell- kann auch für die Authentifizierung in einer Entwicklungsumgebung und zum Verwalten von Kontorollen nützlich sein.

Empfohlene Verwendung von @azure/identity

Die von @azure/identity verfügbar gemachten Anmeldeinformationsklassen konzentrieren sich auf die Bereitstellung der einfachsten Möglichkeit, die Azure SDK-Clients lokal, in Ihren Entwicklungsumgebungen und in der Produktion zu authentifizieren. Wir streben die Einfachheit und angemessene Unterstützung der Authentifizierungsprotokolle an, um die meisten in Azure möglichen Authentifizierungsszenarien abzudecken. Wir erweitern uns aktiv, um weitere Szenarien abzudecken. Eine vollständige Liste der angebotenen Anmeldeinformationen finden Sie im Abschnitt Anmeldeinformationsklassen.

Alle von @azure/identity bereitgestellten Anmeldeinformationstypen werden in Node.jsunterstützt. Bei Browsern ist InteractiveBrowserCredential der Anmeldeinformationstyp, der für Standardauthentifizierungsszenarien verwendet werden soll.

Die meisten anmeldeinformationstypen, die von @azure/identity angeboten werden, verwenden die Microsoft Authentication Library for JavaScript (MSAL.js). Insbesondere verwenden wir die v2-MSAL.js-Bibliotheken, die OAuth 2.0-Autorisierungscodefluss mit PKCE- verwenden und OpenID-kompatiblen. Während @azure/identity sich auf die Einfachheit konzentriert, sind die MSAL.js Bibliotheken wie @azure/msal-common, @azure/msal-nodeund @azure/msal-browserdarauf ausgelegt, stabile Unterstützung für die von Azure unterstützten Authentifizierungsprotokolle bereitzustellen.

Wann sollte etwas anderes verwendet werden?

Die @azure/identity Anmeldeinformationstypen sind Implementierungen @azure/core-authTokenCredential Klasse. Grundsätzlich funktioniert jedes Objekt mit einer getToken Methode, die getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken | null> entspricht, als TokenCredential. Dies bedeutet, dass Entwickler eigene Anmeldeinformationstypen schreiben können, um Authentifizierungsfälle zu unterstützen, die nicht von @azure/identityabgedeckt werden. Weitere Informationen finden Sie unter benutzerdefinierte Anmeldeinformationen.

Obwohl unsere Anmeldeinformationstypen viele erweiterte Szenarien unterstützen, sollten Entwickler stattdessen Microsoft-Authentifizierungsbibliothek für JavaScript (MSAL.js) verwenden. Erwägen Sie die Verwendung von MSAL.js in den folgenden Szenarien:

• Entwickler, die die vollständige Kontrolle über das Authentifizierungsprotokoll und seine Konfiguration wünschen.
• Unsere Anmeldeinformationstypen sind für die Verwendung mit Azure SDK-Clients mit intelligenter Zwischenspeicherung und Token-Aktualisierung auf der zentralen HTTP-Ebene konzipiert. Wenn Sie feststellen, dass Sie getToken direkt verwenden müssen, können Sie von der Verwendung von MSAL.js profitieren, um mehr Kontrolle über den Authentifizierungsfluss und die Tokenzwischenspeicherung zu erhalten.

Weitere Informationen finden Sie unter den folgenden Links:

• Wir stellen einige erweiterte Anwendungsfälle von @azure/identity auf der Seite Azure Identity Examples dar.
  • Dort haben wir speziell einen abschnitt Advanced Examples.
  • Darüber hinaus gibt es einen Abschnitt, in dem gezeigt wird, wie Sie die Authentifizierung mit MSAL direkt.

Für erweiterte Authentifizierungsworkflows im Browser haben wir einen Abschnitt, in dem wir zeigen, wie Sie die @azure/msal-browser Bibliothek direkt zur Authentifizierung von Azure SDK-Clients verwenden.

Authentifizieren des Clients in der Entwicklungsumgebung

Während wir die Verwendung der verwalteten Identität in Ihrer von Azure gehosteten Anwendung empfehlen, ist es typisch, dass ein Entwickler sein eigenes Konto für die Authentifizierung von Aufrufen an Azure-Dienste verwendet, wenn Code lokal debuggen und ausgeführt wird. Es gibt mehrere Entwicklertools, mit denen diese Authentifizierung in Ihrer Entwicklungsumgebung ausgeführt werden kann.

Authentifizieren über die Azure Developer CLI

Entwickler, die außerhalb einer IDE codieren, können auch die Azure Developer CLI- verwenden, um sich zu authentifizieren. Anwendungen, die den DefaultAzureCredential oder die AzureDeveloperCliCredential verwenden, können dann dieses Konto verwenden, um Anrufe in ihrer Anwendung zu authentifizieren, wenn sie lokal ausgeführt werden.

Um sich bei der Azure Developer CLIzu authentifizieren, können Benutzer den Befehl azd auth loginausführen. Für Benutzer, die auf einem System mit einem Standardwebbrowser ausgeführt werden, startet die Azure Developer CLI den Browser, um den Benutzer zu authentifizieren.

Für Systeme ohne Standardwebbrowser verwendet der befehl azd auth login --use-device-code den Authentifizierungsfluss von Gerätecode.

Authentifizieren über die Azure CLI

Anwendungen, die die AzureCliCredentialverwenden , ob direkt oder über die DefaultAzureCredential, können das Azure CLI-Konto verwenden, um Anrufe in der Anwendung zu authentifizieren, wenn sie lokal ausgeführt werden.

Um sich bei der Azure CLIzu authentifizieren, führen Sie den Befehl az loginaus. Für Benutzer, die auf einem System mit einem Standardwebbrowser ausgeführt werden, startet die Azure CLI den Browser, um den Benutzer zu authentifizieren.

Für Systeme ohne Standardwebbrowser verwendet der befehl az login den Authentifizierungsfluss von Gerätecode. Der Benutzer kann auch erzwingen, dass die Azure CLI den Gerätecodefluss verwendet, anstatt einen Browser zu starten, indem er das argument --use-device-code angibt.

Authentifizieren über Azure PowerShell

Anwendungen, die die AzurePowerShellCredentialverwenden , ob direkt oder über die DefaultAzureCredential, können das mit Azure PowerShell verbundene Konto verwenden, um Anrufe in der Anwendung zu authentifizieren, wenn sie lokal ausgeführt werden.

Um sich mit Azure PowerShell-zu authentifizieren, führen Sie das cmdlet Connect-AzAccount aus. Standardmäßig startet Connect-AzAccount wie die Azure CLI den Standardwebbrowser, um ein Benutzerkonto zu authentifizieren.

Wenn die interaktive Authentifizierung in der Sitzung nicht unterstützt werden kann, erzwingt das argument -UseDeviceAuthentication das Cmdlet stattdessen die Verwendung eines Gerätecodeauthentifizierungsflusses, ähnlich der entsprechenden Option in den Azure CLI-Anmeldeinformationen.

Authentifizieren über Visual Studio Code

Entwickler, die Visual Studio Code verwenden, können die Azure-Kontoerweiterung verwenden, um sich über den Editor zu authentifizieren. Apps, die VisualStudioCodeCredential verwenden, können dann dieses Konto verwenden, um Anrufe in ihrer App zu authentifizieren, wenn sie lokal ausgeführt werden.

Um sich in Visual Studio Code zu authentifizieren, stellen Sie sicher, dass die Azure-Kontoerweiterung installiert ist. Öffnen Sie nach der Installation die Befehlspalette, und führen Sie den Befehl Azure: Anmelden aus.

Verwenden Sie außerdem das @azure/identity-vscode Plug-In-Paket. Dieses Paket stellt die Abhängigkeiten von VisualStudioCodeCredential bereit und ermöglicht es. Siehe Plugins.

Es ist ein bekanntes Problem, das VisualStudioCodeCredential nicht mit Azure-Kontoerweiterung Neueren Versionen als 0.9.11funktioniert. Eine langfristige Lösung für dieses Problem ist in Bearbeitung. In der Zwischenzeit sollten Sie Authentifizierung über die Azure CLIin Betracht ziehen.

Authentifizieren des Clients in Browsern

Um Azure SDK-Clients in Webbrowsern zu authentifizieren, bieten wir die InteractiveBrowserCredentialan, die für die Verwendung von Umleitungen oder Popups zum Abschließen des Authentifizierungsflusses festgelegt werden können. Es ist erforderlich, zuerst eine Azure App-Registrierung im Azure-Portal für Ihre Webanwendung zu erstellen.

Schlüsselkonzepte

Wenn Sie @azure/identity- oder Microsoft Entra-ID zum ersten Mal verwenden, lesen Sie Verwenden von @azure/identity mit Microsoft Entra ID. Dieses Dokument bietet ein tieferes Verständnis der Plattform und das richtige Konfigurieren Ihres Azure-Kontos.

Beglaubigungsschreiben

Bei den Anmeldeinformationen handelt es sich um eine Klasse, die die Daten enthält oder abrufen kann, die für einen Dienstclient zum Authentifizieren von Anforderungen erforderlich sind. Dienstclients im azure SDK akzeptieren Anmeldeinformationen, wenn sie erstellt werden. Dienstclients verwenden diese Anmeldeinformationen zum Authentifizieren von Anforderungen an den Dienst.

Die Azure Identity-Bibliothek konzentriert sich auf die OAuth-Authentifizierung mit Microsoft Entra ID und bietet verschiedene Anmeldeinformationsklassen, die ein Microsoft Entra-Token zum Authentifizieren von Dienstanforderungen abrufen können. Alle Anmeldeinformationsklassen in dieser Bibliothek sind Implementierungen der TokenCredential abstrakte Klasse, und jede dieser Klassen kann verwendet werden, um Dienstclients zu erstellen, die mit einem TokenCredentialauthentifizieren können.

Siehe Anmeldeinformationsklassen.

DefaultAzureCredential

DefaultAzureCredential vereinfacht die Authentifizierung bei der Entwicklung von Apps, die in Azure bereitgestellt werden, indem Anmeldeinformationen in Azure-Hostingumgebungen mit anmeldeinformationen kombiniert werden, die in der lokalen Entwicklung verwendet werden. Weitere Informationen finden Sie unter DefaultAzureCredential (Übersicht).

Fortsetzungsrichtlinie

Ab Version 3.3.0 versucht DefaultAzureCredential, sich mit allen Entwickleranmeldeinformationen zu authentifizieren, bis eine erfolgreich ist, unabhängig von Fehlern, die vorherige Entwickleranmeldeinformationen aufgetreten sind. Beispielsweise kann ein Entwickleranmeldeinformation versuchen, ein Token abzurufen und fehlschlagen, sodass DefaultAzureCredential weiterhin die nächsten Anmeldeinformationen im Fluss aufrufen. Bereitgestellte Dienstanmeldeinformationen beenden den Ablauf mit einer ausgelösten Ausnahme, wenn sie versuchen können, token abzurufen, aber keine empfangen.

Auf diese Weise können Sie alle Entwickleranmeldeinformationen auf Ihrem Computer ausprobieren, während sie vorhersagbares Bereitstellungsverhalten haben.

Hinweis zu VisualStudioCodeCredential

Aufgrund eines bekannten Problemswurde VisualStudioCodeCredential aus der DefaultAzureCredential Tokenkette entfernt. Wenn das Problem in einer zukünftigen Version behoben wird, wird diese Änderung wiederhergestellt.

Plug-Ins

Azure Identity for JavaScript bietet eine Plug-In-API, mit der wir bestimmte Funktionen über separate Plug-In-Paketebereitstellen können. Das @azure/identity-Paket exportiert eine Funktion der obersten Ebene (useIdentityPlugin), die zum Aktivieren eines Plug-Ins verwendet werden kann. Wir stellen zwei Plug-In-Pakete bereit:

• @azure/identity-broker, das brokerierte Authentifizierungsunterstützung über einen nativen Broker bereitstellt, z. B. Web Account Manager.
• @azure/identity-cache-persistence, das die zwischenspeicherung persistente Token in Node.js mithilfe eines systemeigenen sicheren Speichersystems bereitstellt, das vom Betriebssystem bereitgestellt wird. Mit diesem Plug-In können zwischengespeicherte access_token Werte über Sitzungen hinweg beibehalten werden, was bedeutet, dass ein interaktiver Anmeldefluss nicht wiederholt werden muss, solange ein zwischengespeichertes Token verfügbar ist.

Beispiele

Weitere Beispiele für die Verwendung verschiedener Anmeldeinformationen finden Sie auf Azure Identity Examples Page

Authentifizieren mit DefaultAzureCredential

In diesem Beispiel wird die Authentifizierung der KeyClient aus den @azure/keyvault-keys Clientbibliothek mithilfe von DefaultAzureCredentialveranschaulicht.

import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure vault URL
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
// Create authenticated client
const client = new KeyClient(vaultUrl, credential);

Angeben einer vom Benutzer zugewiesenen verwalteten Identität mit DefaultAzureCredential

Ein relativ häufiges Szenario umfasst die Authentifizierung mithilfe einer vom Benutzer zugewiesenen verwalteten Identität für eine Azure-Ressource. Erkunden Sie das Beispiel zum Authentifizieren einer vom Benutzer zugewiesenen verwalteten Identität mit DefaultAzureCredential, um zu sehen, wie dies zu einer relativ einfachen Aufgabe gemacht wird, die mithilfe von Umgebungsvariablen oder im Code konfiguriert werden kann.

Definieren eines benutzerdefinierten Authentifizierungsflusses mit ChainedTokenCredential

Während DefaultAzureCredential im Allgemeinen die schnellste Möglichkeit ist, mit der Entwicklung von Anwendungen für Azure zu beginnen, möchten erweiterte Benutzer möglicherweise die Anmeldeinformationen anpassen, die bei der Authentifizierung berücksichtigt werden. Mit dem ChainedTokenCredential können Benutzer mehrere Anmeldeinformationsinstanzen kombinieren, um eine benutzerdefinierte Kette von Anmeldeinformationen zu definieren. In diesem Beispiel wird das Erstellen einer ChainedTokenCredential veranschaulicht, die versucht, sich mit zwei unterschiedlich konfigurierten Instanzen von ClientSecretCredentialzu authentifizieren, um dann die KeyClient aus den @azure/keyvault-keyszu authentifizieren:

import { ClientSecretCredential, ChainedTokenCredential } from "@azure/identity";
import { KeyClient } from "@azure/keyvault-keys";

// Configure variables
const vaultUrl = "https://<your-unique-keyvault-name>.vault.azure.net";
const tenantId = "<tenant-id>";
const clientId = "<client-id>";
const clientSecret = "<client-secret>";
const anotherClientId = "<another-client-id>";
const anotherSecret = "<another-client-secret>";
// 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
const client = new KeyClient(vaultUrl, credentialChain);

Unterstützung für verwaltete Identitäten

Die verwaltete Identitätsauthentifizierung wird entweder über die DefaultAzureCredential oder die ManagedIdentityCredential Anmeldeinformationsklassen direkt für die folgenden Azure-Dienste unterstützt:

• Azure App Service und Azure Functions
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service-
• Azure Service Fabric
• Dokumentation zu virtuellen Computern
• Skalierungssätze für virtuelle Azure-Computer

Beispiele für die Verwendung der verwalteten Identität für die Authentifizierung finden Sie in den Beispielen.

Cloudkonfiguration

Anmeldeinformationen werden standardmäßig für den Microsoft Entra-Endpunkt für Azure Public Cloud authentifiziert. Um auf Ressourcen in anderen Clouds zuzugreifen, z. B. Azure Government oder eine private Cloud, konfigurieren Sie Anmeldeinformationen mit dem Argument authorityHost im Konstruktor. Die AzureAuthorityHosts Enumeration definiert Behörden für bekannte Clouds. Für die US Government-Cloud könnten Sie auf diese Weise eine Anmeldeinformation instanziieren:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: AzureAuthorityHosts.AzureGovernment,
  },
);

Alternativ zum Angeben des arguments authorityHost können Sie auch die AZURE_AUTHORITY_HOST Umgebungsvariable auf die URL der Autorität Ihrer Cloud festlegen. Dieser Ansatz ist nützlich, wenn sie mehrere Anmeldeinformationen für die Authentifizierung in derselben Cloud konfigurieren oder wenn die bereitgestellte Umgebung die Zielcloud definieren muss:

AZURE_AUTHORITY_HOST=https://login.partner.microsoftonline.cn

Die AzureAuthorityHosts Enumeration definiert Behörden für bekannte Clouds für Ihren Komfort; Wenn die Autorität für Ihre Cloud jedoch nicht in AzureAuthorityHostsaufgeführt ist, können Sie eine gültige Autoritäts-URL als Zeichenfolgenargument übergeben. Zum Beispiel:

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

const credential = new ClientSecretCredential(
  "<YOUR_TENANT_ID>",
  "<YOUR_CLIENT_ID>",
  "<YOUR_CLIENT_SECRET>",
  {
    authorityHost: "https://login.partner.microsoftonline.cn",
  },
);

Nicht alle Anmeldeinformationen erfordern diese Konfiguration. Anmeldeinformationen, die sich über ein Entwicklungstool authentifizieren, z. B. AzureCliCredential, verwenden die Konfiguration dieses Tools. Ebenso akzeptiert VisualStudioCodeCredential ein authorityHost-Argument, standardmäßig wird jedoch die authorityHost einstellung von Visual Studio Code Azure: Cloud zugeordnet.

Anmeldeinformationsklassen

Anmeldeinformationsketten

Authentifizieren von von Azure gehosteten Anwendungen

Authentifizieren von Dienstprinzipalen

Authentifizieren von Benutzern

Authentifizieren über Entwicklungstools

Umgebungsvariablen

DefaultAzureCredential und EnvironmentCredential können mit Umgebungsvariablen konfiguriert werden. Jeder Authentifizierungstyp erfordert Werte für bestimmte Variablen.

Dienstprinzipal mit geheimen Schlüsseln

Dienstprinzipal mit Zertifikat

Benutzername und Kennwort

Die Konfiguration wird in der vorherigen Reihenfolge versucht. Wenn zum Beispiel sowohl Werte für ein Clientgeheimnis als auch für ein Zertifikat vorhanden sind, wird das Clientgeheimnis verwendet.

Kontinuierliche Zugriffsauswertung

Ab Version 3.3.0 ist der Zugriff auf Ressourcen, die durch Kontinuierliche Zugriffsauswertung (Continuous Access Evaluation, CAE) geschützt sind, auf Anforderungsbasis möglich. Dies kann mithilfe der GetTokenOptions.enableCae(boolean)-API-aktiviert werden. Die Zertifizierungsstelle wird für Entwickleranmeldeinformationen nicht unterstützt.

Zwischenspeichern von Token

Die Tokenzwischenspeicherung ist ein Feature, das von der Azure Identity-Bibliothek bereitgestellt wird und Apps Folgendes ermöglicht:

• Cachetoken im Arbeitsspeicher (Standard) und auf dem Datenträger (Opt-In).
• Verbessern Sie Resilienz und Leistung.
• Verringern Sie die Anzahl der Anforderungen, die an die Microsoft Entra-ID gesendet wurden, um Zugriffstoken abzurufen.

Die Azure Identity-Bibliothek bietet sowohl speicherinterne als auch persistente Datenträgerzwischenspeicherung. Weitere Informationen finden Sie in der Dokumentation zum Zwischenspeichern von Token.

Brokerierte Authentifizierung

Ein Authentifizierungsbroker ist eine Anwendung, die auf dem Computer eines Benutzers ausgeführt wird und die Authentifizierungs-Handshakes und die Tokenwartung für verbundene Konten verwaltet. Derzeit wird nur der Windows Web Account Manager (WAM) unterstützt. Verwenden Sie zum Aktivieren der Unterstützung das @azure/identity-broker-Paket. Ausführliche Informationen zur Authentifizierung mithilfe von WAM finden Sie in der Dokumentation zum Broker-Plug-In.

Fehlerbehebung

Hilfe zur Problembehandlung finden Sie im Handbuch zur Problembehandlung.

Nächste Schritte

Lesen der Dokumentation

API-Dokumentation für diese Bibliothek finden Sie auf unserer Dokumentationswebsite.

Clientbibliotheksunterstützung

Client- und Verwaltungsbibliotheken, die auf der Seite Azure SDK-Versionen aufgeführt sind,, die die Microsoft Entra-Authentifizierung unterstützen, akzeptieren Anmeldeinformationen aus dieser Bibliothek. Erfahren Sie mehr über die Verwendung dieser Bibliotheken in ihrer Dokumentation, die von der Veröffentlichungsseite aus verknüpft ist.

Bekannte Probleme

Azure AD B2C-Unterstützung

Diese Bibliothek unterstützt den Azure AD B2C--Dienst nicht.

Weitere offene Probleme finden Sie im GitHub-Repositoryder Bibliothek.

Feedback geben

Wenn Fehler auftreten oder Vorschläge vorliegen, ein Problemöffnen.

Beitragend

Wenn Sie zu dieser Bibliothek beitragen möchten, lesen Sie den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.