Freigeben über

Anmeldeinformationsketten in der Azure Identity-Bibliothek für Python

Die Azure Identity-Bibliothek stellt Anmeldeinformationen bereit – öffentliche Klassen, die das TokenCredential-Protokoll 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 unten stehende Diagramm veranschaulicht dieses Verhalten:

Diagramm, das die Sequenz der Anmeldeinformationskette zeigt.

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:

    # Set up credential based on environment (Azure or local development)
if os.getenv("WEBSITE_HOSTNAME"):
    credential = ManagedIdentityCredential(client_id=user_assigned_client_id)
else:
    credential = 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 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 Anmeldeinformationen. 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:

Diagramm, das den DefaultAzureCredential-Authentifizierungsfluss zeigt.

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

Auftrag Berechtigung Beschreibung Standardmäßig aktiviert?
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. Ja
2 Workloadidentität Wenn die App auf einem Azure-Host mit aktivierter Workloadidentität bereitgestellt wird, authentifizieren Sie dieses Konto. Ja
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. Ja
4 Cache für freigegebene Token Wenn sich der Entwickler nur unter Windows bei Azure authentifiziert hat, indem er sich bei Visual Studio anmeldet, authentifizieren Sie die App mit diesem Konto bei Azure. Ja
5 Azure-Befehlszeilenschnittstelle Wenn sich der Entwickler mit dem az login-Befehl der Azure CLI bei Azure authentifiziert hat, authentifizieren Sie die App mit demselben Konto bei Azure. Ja
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. Ja
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. Ja
8 Interaktiver Browser Falls aktiviert, wird der Entwickler interaktiv über den Standardbrowser des aktuellen Systems authentifiziert. Nein

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

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

# Acquire a credential object
credential = DefaultAzureCredential()

blob_service_client = BlobServiceClient(
    account_url="https://<my_account_name>.blob.core.windows.net",
    credential=credential
)

So passen Sie DefaultAzureCredential an

In den folgenden Abschnitten werden Strategien zum Weglassen von Anmeldeinformationen aus der Kette beschrieben.

Ausschließen einzelner Anmeldeinformationen

Verwenden Sie den entsprechenden, mit DefaultAzureCredential-präfixierten exclude, um eine einzelne Anmeldeinformation von auszuschließen. Zum Beispiel:

credential = DefaultAzureCredential(
    exclude_environment_credential=True, 
    exclude_workload_identity_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

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

Diagramm, das den Authentifizierungsfluss für eine DefaultAzureCredential-Instanz zeigt, nachdem im Konstruktor Parameter mit ausschließenden Schlüsselwörtern verwendet wurden, um die Anmeldeinformation der Umgebung und der Workloadidentität zu entfernen.

Hinweis

InteractiveBrowserCredential ist standardmäßig ausgeschlossen und wird daher nicht im vorherigen Diagramm angezeigt. Legen Sie zum Einschließen von InteractiveBrowserCredential den exclude_interactive_browser_credential-Schlüsselwortparameter auf False fest, wenn Sie den DefaultAzureCredential-Konstruktor aufrufen.

Je mehr exclude-präfixierte Schlüsselwortparameter auf True gesetzt werden (Ausschlüsse von Anmeldeinformationen konfiguriert sind), desto geringer sind die Vorteile der Nutzung von DefaultAzureCredential. 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 = DefaultAzureCredential(
    exclude_environment_credential=True,
    exclude_workload_identity_credential=True,
    exclude_shared_token_cache_credential=True,
    exclude_azure_powershell_credential=True,
    exclude_azure_developer_cli_credential=True,
    managed_identity_client_id=user_assigned_client_id
)

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 dev verwendet wird, sieht die Kette wie folgt aus:

Diagramm, das zeigt, dass DefaultAzureCredential mit AZURE_TOKEN_CREDENTIALS auf "dev" gesetzt ist.

Von Bedeutung

Die AZURE_TOKEN_CREDENTIALS Umgebungsvariable wird in azure-identity Paketversionen 1.23.0 und höher unterstützt.

Übersicht über ChainedTokenCredential

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

credential = ChainedTokenCredential(
    AzureCliCredential(),
    AzureDeveloperCliCredential()
)

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

Diagramm, das den Authentifizierungsfluss für eine ChainedTokenCredential-Instanz anzeigt, die aus Azure CLI- und Azure Developer CLI-Anmeldeinformationen besteht.

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 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 immer fehl, es sei denn, es wird explizit über die entsprechende Eigenschaft mit dem exclude-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.

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-Clientbibliothek ausgegeben werden. Zum Beispiel:

import logging
from azure.identity import DefaultAzureCredential

# Set the logging level for the Azure Identity library
logger = logging.getLogger("azure.identity")
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout. Without adding a handler,
# no logging output is visible.
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# Optional: Output logging levels to the console.
print(
    f"Logger enabled for ERROR={logger.isEnabledFor(logging.ERROR)}, "
    f"WARNING={logger.isEnabledFor(logging.WARNING)}, "
    f"INFO={logger.isEnabledFor(logging.INFO)}, "
    f"DEBUG={logger.isEnabledFor(logging.DEBUG)}"
)

Nehmen Sie zur Veranschaulichung an, dass die parameterlose Form von DefaultAzureCredential verwendet wird, um eine Anforderung an einen Blob Storage-Konto zu authentifizieren. Die App wird in der lokalen Entwicklungsumgebung ausgeführt und der Entwickler bei Azure mithilfe der Azure CLI authentifiziert. Gehen Sie auch davon aus, dass die Protokollierungsebene auf logging.DEBUG festgelegt ist. Wenn die App ausgeführt wird, werden die folgenden relevanten Einträge in der Ausgabe angezeigt:

Logger enabled for ERROR=True, WARNING=True, INFO=True, DEBUG=True
No environment configuration found.
ManagedIdentityCredential will use IMDS
EnvironmentCredential.get_token failed: EnvironmentCredential authentication unavailable. Environment variables are not fully configured.
Visit https://aka.ms/azsdk/python/identity/environmentcredential/troubleshoot to troubleshoot this issue.
ManagedIdentityCredential.get_token failed: ManagedIdentityCredential authentication unavailable, no response from the IMDS endpoint.     
SharedTokenCacheCredential.get_token failed: SharedTokenCacheCredential authentication unavailable. No accounts were found in the cache.
AzureCliCredential.get_token succeeded
[Authenticated account] Client ID: 00001111-aaaa-2222-bbbb-3333cccc4444. Tenant ID: aaaabbbb-0000-cccc-1111-dddd2222eeee. User Principal Name: unavailableUpn. Object ID (user): aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
DefaultAzureCredential acquired a token from AzureCliCredential

In der obigen Ausgabe können Sie Folgendes sehen:

  • EnvironmentCredential, ManagedIdentityCredential und SharedTokenCacheCredential haben jeweils in dieser Reihenfolge nicht geschafft, ein Microsoft Entra-Zugriffstoken zu erhalten.
  • Der AzureCliCredential.get_token Aufruf ist erfolgreich, und die Ausgabe gibt auch an, dass DefaultAzureCredential ein Token von AzureCliCredential abgerufen wurde. Da AzureCliCredential erfolgreich war, wurden keine Anmeldeinformationen darüber hinaus versucht.

Hinweis

Im vorherigen Beispiel wurde die Protokollierungsebene auf logging.DEBUG festgelegt. Achten Sie bei der Verwendung dieser Protokollierungsebene darauf, da vertrauliche Informationen ausgegeben werden können. In diesem Fall beispielsweise die Client-ID, die Mandanten-ID und die Objekt-ID des Benutzerprinzipals des Entwicklers in Azure. Alle Ablaufverfolgungsinformationen wurden aus der Ausgabe aus Gründen der Übersichtlichkeit entfernt.