Anmeldeinformationsketten in der Azure Identity-Bibliothek für .NET

Die Azure Identity-Bibliothek stellt Anmeldeinformationen bereit – öffentliche Klassen, die von der TokenCredential-Klasse der Azure Core-Bibliothek abgeleitet sind. 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 unten stehende Diagramm veranschaulicht dieses Verhalten:

Gründe für die Verwendung von Anmeldeinformationsketten

Verkettete Anmeldeinformationen können die folgenden Vorteile bieten:

• Umgebungsbewusstsein: Wählt automatisch die am besten geeigneten Anmeldeinformationen basierend auf der Umgebung aus, in der die App ausgeführt wird. Ohne sie müssten Sie Code wie diesen schreiben:

  TokenCredential credential;
  
  if (app.Environment.IsProduction() || app.Environment.IsStaging())
  {
      credential = new ManagedIdentityCredential(
          ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId));
  }
  else
  {
      // local development environment
      credential = new VisualStudioCredential();
  }
  

• 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 die vorherigen keinen Zugriffstoken erhalten.

Auswählen der verketteten Anmeldeinformationen

Es gibt zwei unterschiedliche Philosophien 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 Berechtigungsnachweisen. Er 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.

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

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    DefaultAzureCredential credential = new();
    clientBuilder.UseCredential(credential);
});

Anpassen von DefaultAzureCredential

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

Ausschließen einzelner Anmeldeinformationen

Um eine einzelne Anmeldeinformation von DefaultAzureCredential auszuschließen, verwenden Sie die entsprechende Exclude-Eigenschaft in DefaultAzureCredentialOptions. Zum Beispiel:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new DefaultAzureCredential(
        new DefaultAzureCredentialOptions
        {
            ExcludeEnvironmentCredential = true,
            ExcludeManagedIdentityCredential = true,
            ExcludeWorkloadIdentityCredential = true,
        }));
});

Im vorherigen Codebeispiel EnvironmentCredential, , ManagedIdentityCredentialund WorkloadIdentityCredential werden aus der Anmeldeinformationskette entfernt. Daher wird zuerst eine Authentifizierung mit den ersten Anmeldeinformationen versucht, und zwar: VisualStudioCredential. Die geänderte Kette enthält nur Entwicklungszeitanmeldeinformationen und sieht wie folgt aus:

Da mehr Eigenschaften mit Exclude-Präfixen auf true festgelegt sind (Anmeldeinformationsausschlüsse werden konfiguriert), verringern sich die Vorteile der Verwendung vonDefaultAzureCredential. In solchen Fällen ist ChainedTokenCredential eine bessere Wahl und erfordert weniger Code. Zur Veranschaulichung verhalten sich diese beiden Codebeispiele auf die gleiche Weise:

credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ExcludeEnvironmentCredential = true,
        ExcludeWorkloadIdentityCredential = true,
        ExcludeManagedIdentityCredential = true,
        ExcludeVisualStudioCodeCredential = true,
        ExcludeAzurePowerShellCredential = true,
        ExcludeAzureDeveloperCliCredential = true,
        ExcludeBrokerCredential = true,
    });

credential = new ChainedTokenCredential(
    new VisualStudioCredential(),
    new AzureCliCredential());

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:

Eine bestimmte Anmeldeinformation verwenden

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 auf VisualStudioCredential reduzieren, indem Sie AZURE_TOKEN_CREDENTIALS auf VisualStudioCredential setzen. Der Zeichenfolgenvergleich wird unabhängig von der Groß-/Kleinschreibung durchgeführt. Gültige Zeichenfolgenwerte für die Umgebungsvariable sind:

• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePowerShellCredential
• BrokerCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• VisualStudioCredential
• VisualStudioCodeCredential
• WorkloadIdentityCredential

Übersicht über ChainedTokenCredential

ChainedTokenCredential ist eine leere Kette, der Sie Anmeldeinformationen für die Anforderungen Ihrer App hinzufügen. Zum Beispiel:

builder.Services.AddAzureClients(clientBuilder =>
{
    clientBuilder.AddSecretClient(
        new Uri($"https://{keyVaultName}.vault.azure.net"));
    clientBuilder.AddBlobServiceClient(
        new Uri($"https://{storageAccountName}.blob.core.windows.net"));

    clientBuilder.UseCredential(new ChainedTokenCredential(
        new AzurePowerShellCredential(),
        new VisualStudioCredential()));
});

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

Verwendungsleitfaden für DefaultAzureCredential

DefaultAzureCredential ist zweifellos die einfachste Möglichkeit, mit der Azure Identity-Bibliothek zu beginnen, doch dieser Komfort erfordert Kompromisse. 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. Die Optionen finden Sie in der Liste Abgeleitet.

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 verketteter 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. Daher schlägt ManagedIdentityCredential in der lokalen Entwicklungsumgebung imme fehl, es sei denn, dies ist explizit über die entsprechende Eigenschaft mit demExclude-Präfix deaktiviert.
• 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. Weitere Informationen zur Unvorstellbarkeit finden Sie unter Verwenden von deterministischen Anmeldeinformationen in Produktionsumgebungen.

Debuggen von verketteten Anmeldeinformationen

Um ein unerwartetes Problem zu diagnostizieren oder zu verstehen, was verkettete Anmeldeinformationen tun, aktivieren Sie die Protokollierung in Ihrer App. Filtern Sie die Protokolle optional nur auf die Ereignisse, die aus der Azure Identity-Bibliothek ausgegeben werden. Zum Beispiel:

using AzureEventSourceListener listener = new((args, message) =>
{
    if (args is { EventSource.Name: "Azure-Identity" })
    {
        Console.WriteLine(message);
    }
}, EventLevel.LogAlways);

Nehmen Sie zur Veranschaulichung an, dass die parameterlose Form von DefaultAzureCredential verwendet wurde, um eine Anforderung an einen Log Analytics-Arbeitsbereich zu authentifizieren. Die App wurde in der lokalen Entwicklungsumgebung ausgeführt, und Visual Studio wurde bei einem Azure-Konto authentifiziert. Wenn die App das nächste Mal ausgeführt wurde, wurden die folgenden relevanten Einträge in der Ausgabe angezeigt:

DefaultAzureCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
EnvironmentCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): EnvironmentCredential authentication unavailable. Environment variables are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/environmentcredential/troubleshoot
WorkloadIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
WorkloadIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured. See the troubleshooting guide for more information. https://aka.ms/azsdk/net/identity/workloadidentitycredential/troubleshoot
ManagedIdentityCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
ManagedIdentityCredential.GetToken was unable to retrieve an access token. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 Exception: Azure.Identity.CredentialUnavailableException (0x80131500): ManagedIdentityCredential authentication unavailable. No response received from the managed identity endpoint.
VisualStudioCredential.GetToken invoked. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342
VisualStudioCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00
DefaultAzureCredential credential selected: Azure.Identity.VisualStudioCredential
DefaultAzureCredential.GetToken succeeded. Scopes: [ https://api.loganalytics.io//.default ] ParentRequestId: d7ef15d1-50f8-451d-afeb-6b06297a3342 ExpiresOn: 2024-08-13T17:16:50.8023621+00:00

In der obigen Ausgabe können Sie Folgendes sehen:

• EnvironmentCredential, WorkloadIdentityCredential und ManagedIdentityCredential schlagen jeweils fehl beim Abrufen eines Microsoft Entra-Zugriffstokens in dieser Reihenfolge.
• Der Eintrag mit dem Präfix DefaultAzureCredential credential selected: gibt die ausgewählten Anmeldeinformationen an, in diesem Fall: VisualStudioCredential. Da VisualStudioCredential erfolgreich war, wurden keine Anmeldeinformationen darüber hinaus verwendet.