Anmeldeinformationsketten in der Azure Identity-Bibliothek für JavaScript

Die Azure Identity-Bibliothek stellt Anmeldeinformationen bereit – öffentliche Klassen, die die TokenCredential-Schnittstelle der Azure Core-Bibliothek implementieren. Anmeldeinformationen stellen einen eindeutigen Authentifizierungsfluss zum Abrufen eines Zugriffstokens aus der Microsoft Entra-ID dar. Diese Anmeldedaten können miteinander verkettet werden, um eine geordnete Abfolge von Authentifizierungsmechanismen zu bilden, die versucht werden sollen.

Funktionsweise von verketteten Anmeldeinformationen

Zur Laufzeit versucht eine Anmeldeinformationskette, sich mit den ersten Anmeldeinformationen der Sequenz zu authentifizieren. Wenn diese Anmeldeinformationen kein Zugriffstoken abrufen, werden die nächsten Anmeldeinformationen in der Sequenz ausprobiert usw., bis erfolgreich ein Zugriffstoken abgerufen wurde. Das folgende Sequenzdiagramm veranschaulicht dieses Verhalten:

Gründe für die Verwendung von Berechtigungsketten

Verkettete Anmeldeinformationen können die folgenden Vorteile bieten:

• Umweltbewusstsein: Wählt automatisch die passendsten Zugangsdaten basierend auf der Umgebung aus, in der die App läuft. Ohne sie müssten Sie Code wie diesen schreiben:

  import { 
      ManagedIdentityCredential, 
      AzureCliCredential 
  } from "@azure/identity";
  
  let credential;
  if (process.env.NODE_ENV === "production") {
      credential = new ManagedIdentityCredential();
  } else {
      credential = new AzureCliCredential();
  }
  

• Nahtlose Übergänge: Ihre App kann von der lokalen Entwicklung zur Staging- oder Produktionsumgebung wechseln, ohne den Authentifizierungscode zu ändern.

• Verbesserte Resilienz: Enthält einen Fallbackmechanismus, der zu den nächsten Anmeldeinformationen wechselt, wenn der vorherige Fehler beim Abrufen eines Zugriffstokens auftritt.

So wählen Sie ein verkettetes Kredential

Es gibt zwei verschiedene Ansätze für die Verkettung von Anmeldeinformationen:

• „Zerreißen“ einer Kette: Beginnen Sie mit einer vorkonfigurierten Kette, und schließen Sie aus, was Sie nicht benötigen. Informationen zu diesem Ansatz finden Sie im Abschnitt DefaultAzureCredential-Übersicht.
• „Erstellen“ einer Kette: Beginnen Sie mit einer leeren Kette und schließen Sie nur das ein, was Sie benötigen. Informationen zu diesem Ansatz finden Sie im Abschnitt ChainedTokenCredential-Übersicht.

Übersicht über DefaultAzureCredential

DefaultAzureCredential ist eine vorkonfigurierte Kette von Anmeldeinformationen. Es wurde entwickelt, um viele Umgebungen zusammen mit den am häufigsten verwendeten Authentifizierungsflüssen und Entwicklertools zu unterstützen. In grafischer Form sieht die zugrunde liegende Kette wie folgt aus:

Die Reihenfolge, in der DefaultAzureCredential, versucht, Anmeldeinformationen zu erhalten, folgt.

Auftrag	Berechtigung	Beschreibung	Standardmäßig aktiviert?
1	Umgebung.	Liest eine Sammlung von Umgebungsvariablen, um zu bestimmen, ob ein Anwendungsdienstprinzipal (Anwendungsbenutzer) für die App konfiguriert ist. Wenn ja, verwendet DefaultAzureCredential diese Werte, um die App bei Azure zu authentifizieren. Diese Methode wird am häufigsten in Serverumgebungen verwendet, kann aber auch bei der lokalen Entwicklung verwendet werden.	Yes
2	Workloadidentität	Wenn die App auf einem Azure-Host mit aktivierter Workload-Identität bereitgestellt wird, authentifizieren Sie dieses Konto.	Yes
3	Verwaltete Identität	Wenn die App auf einem Azure-Host mit aktivierter verwalteter Identität bereitgestellt wird, authentifizieren Sie die App mit dieser verwalteten Identität bei Azure.	Yes
4	Visual Studio Code	Wenn der Entwickler über die Azure Resources-Erweiterung von Visual Studio Code authentifiziert und das @azure/Identity-vscode-Paket installiert ist, authentifizieren Sie dieses Konto.	Yes
5	Azure-Befehlszeilenschnittstelle	Wenn sich der Entwickler bei Azure mithilfe des befehls az login der Azure CLI authentifiziert hat, authentifizieren Sie die App mit demselben Konto bei Azure.	Yes
6	Azure PowerShell	Wenn sich der Entwickler mit dem Connect-AzAccount-Cmdlet von Azure PowerShell bei Azure authentifiziert hat, authentifizieren Sie die App mit demselben Konto bei Azure.	Yes
7	Azure Developer CLI	Wenn sich der Entwickler mit dem azd auth login-Befehl der Azure Developer CLI bei Azure authentifiziert hat, authentifizieren Sie sich mit diesem Konto.	Yes
8	Broker-	Authentifiziert sich mithilfe des Standardkontos, das über einen Broker beim Betriebssystem angemeldet ist. Erfordert, dass das @azure/Identity-Broker-Paket installiert ist.	Yes

In der einfachsten Form können Sie die parameterlose Version von DefaultAzureCredential wie folgt verwenden:

import { DefaultAzureCredential } from "@azure/identity";
import { BlobServiceClient } from "@azure/storage-blob";

// Acquire a credential object
const credential = new DefaultAzureCredential();

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

So passen Sie DefaultAzureCredential an

In den folgenden Abschnitten werden Strategien zum Steuern beschrieben, welche Anmeldeinformationen in der Kette enthalten sind.

Ausschließen einer Kategorie des Anmeldeinformationstyps

Um alle Developer tool oder Deployed service Anmeldeinformationen auszuschließen, setzen Sie die Umgebungsvariable AZURE_TOKEN_CREDENTIALS auf prod bzw. dev. Wenn ein Wert prod verwendet wird, sieht die zugrunde liegende Anmeldeinformationskette wie folgt aus:

Wenn ein Wert dev verwendet wird, sieht die Kette wie folgt aus:

Um sicherzustellen, dass die Umgebungsvariable definiert und auf eine unterstützte Zeichenfolge festgelegt wird, legen Sie die requiredEnvVars-Eigenschaft auf AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Verwenden einer bestimmten Anmeldeinformation

Um alle Anmeldeinformationen außer einem auszuschließen, legen Sie die Umgebungsvariable AZURE_TOKEN_CREDENTIALS auf den Anmeldeinformationsnamen fest. Sie können beispielsweise die DefaultAzureCredential Kette AzureCliCredential reduzieren, indem Sie auf ".AZURE_TOKEN_CREDENTIALSAzureCliCredential Der Zeichenfolgenvergleich wird ohne Groß-/Kleinschreibung durchgeführt. Gültige Zeichenfolgenwerte für die Umgebungsvariable sind:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• EnvironmentCredential
• ManagedIdentityCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Von Bedeutung

Die AZURE_TOKEN_CREDENTIALS Umgebungsvariable unterstützt einzelne Anmeldeinformationsnamen in @azure/identity Paketversionen 4.11.0 und höher.

Um sicherzustellen, dass die Umgebungsvariable definiert und auf eine unterstützte Zeichenfolge festgelegt wird, legen Sie die Eigenschaft requiredEnvVars auf AZURE_TOKEN_CREDENTIALS:

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});

Übersicht über ChainedTokenCredential

ChainedTokenCredential ist eine leere Kette, der Sie den Anforderungen Ihrer App entsprechende Anmeldeinformationen hinzufügen. Beispiel:

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

const credential = new ChainedTokenCredential(
    new AzureCliCredential(),
    new VisualStudioCodeCredential()
);

const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

Im vorherigen Codebeispiel wird eine maßgeschneiderte Anmeldeinformationskette erstellt, die aus zwei Anmeldeinformationen zur Entwicklungszeit besteht. AzureCliCredential wird zuerst versucht, gegebenenfalls gefolgt von VisualStudioCodeCredential. In grafischer Form sieht die Kette wie folgt aus:

Tipp

Um die Leistung zu verbessern, optimieren Sie die Sortierung von Anmeldeinformationen in ChainedTokenCredential von den meisten bis zu den am wenigsten verwendeten Anmeldeinformationen.

Verwendungsleitfaden für DefaultAzureCredential

DefaultAzureCredential ist zweifellos die einfachste Möglichkeit, mit der Azure Identity-Bibliothek zu beginnen, aber mit diesem Komfort kommt es zu Kompromissen. Nachdem Sie Ihre App in Azure bereitgestellt haben, sollten Sie die Authentifizierungsanforderungen der App verstehen. Ersetzen Sie aus diesem Grund DefaultAzureCredential durch eine bestimmte TokenCredential Implementierung, z. B. ManagedIdentityCredential.

Dies ist der Grund:

• Debugging-Herausforderungen: Wenn die Authentifizierung fehlschlägt, kann es schwierig sein, die fehlerhaften Anmeldeinformationen zu debuggen und zu identifizieren. Sie müssen die Protokollierung aktivieren, um den Fortschritt von einer Anmeldeinformation zum nächsten sowie den Status „Erfolg/Fehler“ der einzelnen Anmeldeinformationen anzuzeigen. Weitere Informationen finden Sie unter Debuggen von Anmeldeinformationen.
• Leistungsaufwand: Der Prozess des sequenziellen Ausprobierens mehrerer Anmeldeinformationen kann Leistungseinbußen verursachen. Wenn sie beispielsweise auf einem lokalen Entwicklungscomputer ausgeführt wird, ist die verwaltete Identität nicht verfügbar. Folglich schlägt ManagedIdentityCredential in der lokalen Entwicklungsumgebung immer fehl.
• Unvorhersehbares Verhalten: DefaultAzureCredential sucht nach dem Vorhandensein bestimmter Umgebungsvariablen. Es ist möglich, dass jemand diese Umgebungsvariablen auf der Systemebene auf dem Hostcomputer hinzufügen oder ändern kann. Diese Änderungen gelten global und ändern daher das Verhalten von DefaultAzureCredential zur Laufzeit in jeder App, die auf diesem Computer ausgeführt wird.

Anmeldeinformationen debuggen

Um ein unerwartetes Problem zu diagnostizieren oder zu verstehen, was eine Berechtigung tut, aktivieren Sie die Protokollierung in Ihrer App. Beispiel:

import { setLogLevel, AzureLogger } from "@azure/logger";
import { BlobServiceClient } from "@azure/storage-blob";
import { DefaultAzureCredential } from "@azure/identity";

// Constant for the Azure Identity log prefix
const AZURE_IDENTITY_LOG_PREFIX = "azure:identity";

// override logging to output to console.log (default location is stderr)
// only log messages that start with the Azure Identity log prefix
setLogLevel("verbose");
AzureLogger.log = (...args) => {
  const message = args[0];
  if (typeof message === 'string' && message.startsWith(AZURE_IDENTITY_LOG_PREFIX)) {
    console.log(...args);
  }
};

// Get storage account name from environment variable
const storageAccountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;

if (!storageAccountName) {
    throw new Error("AZURE_STORAGE_ACCOUNT_NAME environment variable is required");
}

const credential = new DefaultAzureCredential({ 
    requiredEnvVars: [ "AZURE_TOKEN_CREDENTIALS" ]
});


const blobServiceClient = new BlobServiceClient(
    `https://${storageAccountName}.blob.core.windows.net`,
    credential
);

azure:identity:info EnvironmentCredential => Found the following environment variables: 
azure:identity:verbose EnvironmentCredential => AZURE_CLIENT_SEND_CERTIFICATE_CHAIN: undefined; sendCertificateChain: false
azure:identity:info WorkloadIdentityCredential => Found the following environment variables:
azure:identity:warning DefaultAzureCredential => Skipped createDefaultWorkloadIdentityCredential because of an error creating the credential: CredentialUnavailableError: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => Using DefaultToImds managed identity.
azure:identity:warning DefaultAzureCredential => Skipped createDefaultBrokerCredential because of an error creating the credential: Error: Broker for WAM was requested, but no plugin was configured or no authentication record was found. You must install the @azure/identity-broker plugin package (npm install --save @azure/identity-broker) and enable it by importing `useIdentityPlugin` from `@azure/identity` and calling useIdentityPlugin(nativeBrokerPlugin) before using enableBroker.
azure:identity:info DefaultAzureCredential => getToken() => Skipping createDefaultWorkloadIdentityCredential, reason: WorkloadIdentityCredential: is unavailable. clientId is a required parameter. In DefaultAzureCredential and ManagedIdentityCredential, this can be provided as an environment variable - "AZURE_CLIENT_ID".
        See the troubleshooting guide for more information: https://aka.ms/azsdk/js/identity/workloadidentitycredential/troubleshoot
azure:identity:info ManagedIdentityCredential => getToken() => Using the MSAL provider for Managed Identity.
azure:identity:info ManagedIdentityCredential - Token Exchange => ManagedIdentityCredential - Token Exchange: Unavailable. The environment variables needed are: AZURE_CLIENT_ID (or the client ID sent through the parameters), AZURE_TENANT_ID and AZURE_FEDERATED_TOKEN_FILE
azure:identity:info ManagedIdentityCredential => getToken() => MSAL Identity source: DefaultToImds
azure:identity:info ManagedIdentityCredential => getToken() => Using the IMDS endpoint to probe for availability.
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Pinging the Azure IMDS endpoint
azure:identity:verbose ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: Caught error RestError: connect ENETUNREACH 169.254.169.254:80
azure:identity:info ManagedIdentityCredential - IMDS => ManagedIdentityCredential - IMDS: The Azure IMDS endpoint is unavailable
azure:identity:error ManagedIdentityCredential => getToken() => ERROR. Scopes: https://storage.azure.com/.default. Error message: Attempted to use the IMDS endpoint, but it is not available..
azure:identity:info AzureCliCredential => getToken() => Using the scope https://storage.azure.com/.default
azure:identity:info AzureCliCredential => getToken() => expires_on is available and is valid, using it
azure:identity:info AzureCliCredential => getToken() => SUCCESS. Scopes: https://storage.azure.com/.default.

Beachten Sie in der vorherigen Ausgabe, dass DefaultAzureCredential ein Token erfolgreich mithilfe von AzureCliCredential.