Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für C++

Die Azure Identity-Clientbibliothek stellt Anmeldeinformationen bereit – öffentliche Typen, die von der abstrakten Basisklasse tokenCredential der Azure Core-Bibliothek abgeleitet sind. Ein Berechtigungsnachweis stellt einen eindeutigen Authentifizierungsfluss zum Abrufen eines Zugriffstokens aus 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 mit dieser Anmeldeinformation kein Zugriffstoken abgerufen werden kann, wird die nächste Anmeldeinformation in der Folge ausprobiert, bis ein Zugriffstoken erfolgreich abgerufen wird. Das folgende Sequenzdiagramm veranschaulicht dieses Verhalten:

Gründe für die Verwendung von Berechtigungsnachweisketten

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:

  // Set up credential based on environment (Azure or local development)
  std::shared_ptr<Azure::Core::Credentials::TokenCredential> credential;
  if (std::getenv("WEBSITE_HOSTNAME"))
  {
      credential = std::make_shared<Azure::Identity::ManagedIdentityCredential>();
  }
  else
  {
      credential = std::make_shared<Azure::Identity::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

Bei C++ gibt es zwei Möglichkeiten für die Verkettung von Anmeldeinformationen:

• Vorkonfigurierte Kette verwenden: Verwenden Sie die vorkonfigurierte Kette, die DefaultAzureCredential vom Typ implementiert wird. Informationen zu diesem Ansatz finden Sie im Abschnitt DefaultAzureCredential-Übersicht.
• Erstellen einer benutzerdefinierten Anmeldeinformationskette: 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 vorgabebasierte, vorkonfigurierte Kette von Anmeldeinformationen. Sein Design unterstützt viele Umgebungen sowie die am häufigsten verwendeten Authentifizierungsflüsse und Entwicklertools. In grafischer Form sieht die zugrunde liegende Kette wie folgt aus:

Die Reihenfolge, in der DefaultAzureCredential Anmeldeinformationen überprüft, ist wie folgt.

Bestellung	Berechtigung	BESCHREIBUNG
1	Umgebung	Liest eine Auflistung von Umgebungsvariablen , um festzustellen, 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.
2	Workload-Identität	Wenn die App auf einem Azure-Host mit aktivierter Workload-Identität bereitgestellt wird, authentifizieren Sie dieses Konto.
3	Verwaltete Identität	Wenn die App auf einem Azure-Host bereitgestellt wird, während die Funktion „Verwaltete Identität“ aktiviert ist, wird die App bei Azure mit dieser verwalteten Identität authentifiziert.
4	Azure CLI	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.

In der einfachsten Form können Sie die parameterlose Version von DefaultAzureCredential folgendermaßen verwenden:

#include <azure/identity/default_azure_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>();

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, 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:

Diagramm, das DefaultAzureCredential zeigt, wobei AZURE_TOKEN_CREDENTIALS auf "prod" festgelegt sind.

Wenn ein Wert von dev verwendet wird, besteht die Kette nur aus AzureCliCredential.

Um sicherzustellen, dass die Umgebungsvariable definiert ist und auf eine unterstützte Zeichenfolge gesetzt wird, übergeben Sie true an den Konstruktor von DefaultAzureCredential.

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Von Bedeutung

Die oben genannte Konstruktorüberladung wird in azure-identity-cpp Paketversionen 1.13.1 und höher unterstützt.

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
• EnvironmentCredential
• ManagedIdentityCredential
• WorkloadIdentityCredential

Um sicherzustellen, dass die Umgebungsvariable definiert ist und auf eine unterstützte Zeichenfolge gesetzt wird, übergeben Sie true an den Konstruktor von DefaultAzureCredential.

auto credential = std::make_shared<Azure::Identity::DefaultAzureCredential>(true);

Von Bedeutung

Die oben genannte Konstruktorüberladung wird in azure-identity-cpp Paketversionen 1.13.1 und höher unterstützt.

Übersicht über ChainedTokenCredential

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

#include <azure/identity/azure_cli_credential.hpp>
#include <azure/identity/chained_token_credential.hpp>
#include <azure/identity/managed_identity_credential.hpp>
#include <azure/storage/blobs/blob_client.hpp>

int main()
{
    // create a credential
    auto credential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
        Azure::Identity::ChainedTokenCredential::Sources{
            std::make_shared<Azure::Identity::ManagedIdentityCredential>(),
            std::make_shared<Azure::Identity::AzureCliCredential>()});

    // create a Blob service client
    auto blobUrl = "https://<my_account_name>.blob.core.windows.net/mycontainer/myblob";
    Azure::Storage::Blobs::BlobClient blobClient{blobUrl, credential};
}

Im vorherigen Codebeispiel wird eine maßgeschneiderte Anmeldeinformationskette erstellt, die aus zwei Anmeldeinformationen besteht. ManagedIdentityCredential wird zuerst versucht, gegebenenfalls gefolgt von AzureCliCredential. 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-Clientbibliothek zu beginnen, aber mit diesem Komfort kommt ein Kompromiss. 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 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. 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.

Debuggen von verketteten Anmeldeinformationen

Um ein unerwartetes Problem zu diagnostizieren oder zu verstehen, was verkettete Anmeldeinformationen tun, aktivieren Sie die Protokollierung in Ihrer App. Nehmen Sie zur Veranschaulichung an, dass die parameterlose Form von DefaultAzureCredential verwendet wird, um eine Anforderung an ein Blob Storage-Konto zu authentifizieren. Die App wird in der lokalen Entwicklungsumgebung ausgeführt und der Entwickler bei Azure mithilfe der Azure CLI authentifiziert. Wenn die App ausgeführt wird, werden die folgenden relevanten Einträge in der Ausgabe angezeigt:

DEBUG : Identity: Creating DefaultAzureCredential which combines multiple parameterless credentials into a single one.
DefaultAzureCredential is only recommended for the early stages of development, and not for usage in production environment.
Once the developer focuses on the Credentials and Authentication aspects of their application, DefaultAzureCredential needs to be replaced with the credential that is the better fit for the application.
INFO  : Identity: EnvironmentCredential gets created with ClientSecretCredential.
DEBUG : Identity: EnvironmentCredential: 'AZURE_TENANT_ID', 'AZURE_CLIENT_ID', and 'AZURE_CLIENT_SECRET' environment variables are set, so ClientSecretCredential with corresponding tenantId, clientId, and clientSecret gets created.
WARN  : Identity: Azure Kubernetes environment is not set up for the WorkloadIdentityCredential credential to work.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2019 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with App Service 2017 source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Cloud Shell source.
DEBUG : Identity: ManagedIdentityCredential: Environment is not set up for the credential to be created with Azure Arc source.
INFO  : Identity: ManagedIdentityCredential will be created with Azure Instance Metadata Service source.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: AzureCliCredential created.
Successful creation does not guarantee further successful token retrieval.
INFO  : Identity: DefaultAzureCredential: Created with the following credentials: EnvironmentCredential, WorkloadIdentityCredential, ManagedIdentityCredential, AzureCliCredential.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from EnvironmentCredential: GetToken(): error response: 400 Bad Request

{"error":"invalid_grant","error_description":"AADSTS53003: Access has been blocked by Conditional Access policies. The access policy does not allow token issuance. Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2025-03-07 21:25:44Z","error_codes":[53003],"timestamp":"2025-03-07 21:25:44Z","trace_id":"0000aaaa-11bb-cccc-dd22-eeeeee333333","correlation_id":"aaaa0000-bb11-2222-33cc-444444dddddd","error_uri":"https://login.microsoftonline.com/error?code=53003","suberror":"message_only","claims":"{\"access_token\":{\"capolids\":{\"essential\":true,\"values\":[\"cccc2222-dd33-4444-55ee-666666ffffff\"]}}}"}
WARN  : Identity: WorkloadIdentityCredential authentication unavailable. See earlier WorkloadIdentityCredential log messages for details.
DEBUG : Identity: DefaultAzureCredential: Failed to get token from WorkloadIdentityCredential: WorkloadIdentityCredential authentication unavailable. Azure Kubernetes environment is not set up correctly.
INFO  : Identity: DefaultAzureCredential: Successfully got token from ManagedIdentityCredential. This credential will be reused for subsequent calls.
DEBUG : Identity: DefaultAzureCredential: Saved this credential at index 2 for subsequent calls.

In der vorangegangenen Ausgabe beachten Sie, dass:

• EnvironmentCredential, WorkloadIdentityCredential und ManagedIdentityCredential haben jeweils in dieser Reihenfolge nicht geschafft, ein Microsoft Entra-Zugriffstoken zu erhalten.
• ManagedIdentityCredential ist erfolgreich, wie durch einen Eintrag dargestellt, der mit "Successfully got token from ManagedIdentityCredential" beginnt.