Azure Identity-Clientbibliothek für Python– Version 1.14.1

  • Artikel

Die Azure Identity-Bibliothek bietet Unterstützung für die Azure Active Directory-Tokenauthentifizierung (Azure AD) im gesamten Azure SDK. Es bietet eine Reihe von Implementierungen, die zum Erstellen von TokenCredential Azure SDK-Clients verwendet werden können, die die Azure AD-Tokenauthentifizierung unterstützen.

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Azure AD-Dokumentation

Erste Schritte

Installieren des Pakets

Installieren von Azure Identity mit pip:

pip install azure-identity

Voraussetzungen

  • Ein Azure-Abonnement
  • Python 3.7 oder eine aktuelle Version von Python 3 (diese Bibliothek unterstützt keine End-of-Life-Versionen)

Authentifizieren während der lokalen Entwicklung

Beim lokalen Debuggen und Ausführen von Code ist es typisch, dass Entwickler ihre eigenen Konten für die Authentifizierung von Aufrufen von Azure-Diensten verwenden. Die Azure Identity-Bibliothek unterstützt die Authentifizierung über Entwicklertools, um die lokale Entwicklung zu vereinfachen.

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 oder VisualStudioCodeCredential verwendenDefaultAzureCredential, können dieses Konto dann verwenden, um Aufrufe in ihrer App zu authentifizieren, wenn sie lokal ausgeführt werden.

Stellen Sie für die Authentifizierung in Visual Studio Code sicher, dass die Azure-Kontoerweiterung installiert ist. Öffnen Sie nach der Installation die Befehlspalette , und führen Sie den Befehl Azure: Anmelden aus .

Es handelt sich um ein bekanntes Problem , das VisualStudioCodeCredential mit Azure-Kontoerweiterungsversionen neuer als 0.9.11 nicht funktioniert. Eine langfristige Lösung dieses Problems wird ausgeführt. In der Zwischenzeit sollten Sie sich über die Azure CLI authentifizieren.

Authentifizieren über die Azure CLI

DefaultAzureCredential und AzureCliCredential kann sich als benutzer authentifizieren, der bei der Azure CLI angemeldet ist. Führen az loginSie aus, um sich bei der Azure CLI anzumelden. Auf einem System mit einem Standardwebbrowser startet die Azure CLI den Browser, um einen Benutzer zu authentifizieren.

Wenn kein Standardbrowser verfügbar ist, az login verwendet den Authentifizierungsflow für Gerätecode. Dieser Flow kann auch manuell ausgewählt werden, indem Sie ausführen az login --use-device-code.

Authentifizieren über die Azure Developer CLI

Entwickler, die außerhalb einer IDE programmieren, können auch die Azure Developer CLI verwenden, um sich zu authentifizieren. Anwendungen, die DefaultAzureCredential oder AzureDeveloperCliCredential verwenden, können dieses Konto beim lokalen Ausführen dann zum Authentifizieren von Aufrufen in ihrer Anwendung verwenden.

Um sich beim Azure Developer CLI zu 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 azd auth login --use-device-code-Befehl den Gerätecode-Authentifizierungsfluss.

Wichtige Begriffe

Anmeldeinformationen

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 gesamten Azure SDK akzeptieren beim Erstellen von Anmeldeinformationen eine instance und verwenden diese Anmeldeinformationen zum Authentifizieren von Anforderungen.

Die Azure Identity-Bibliothek konzentriert sich auf die OAuth-Authentifizierung mit Azure AD. Es bietet verschiedene Anmeldeinformationsklassen, die ein Azure AD-Zugriffstoken abrufen können. Eine Liste der dieser Bibliothek finden Sie weiter unten im Abschnitt Anmeldeinformationsklassen.

DefaultAzureCredential

DefaultAzureCredential eignet sich für die meisten Anwendungen, die in Azure ausgeführt werden, da allgemeine Produktionsanmeldeinformationen mit Entwicklungsanmeldeinformationen kombiniert werden. DefaultAzureCredential versucht, sich über die folgenden Mechanismen in dieser Reihenfolge zu authentifizieren, und wird beendet, wenn eine erfolgreich ist:

Hinweis: DefaultAzureCredential Soll den Einstieg in die Bibliothek vereinfachen, indem allgemeine Szenarien mit vernünftigen Standardverhalten behandelt werden. Entwickler, die mehr Kontrolle wünschen oder deren Szenario von den Standardeinstellungen nicht abgedeckt wird, sollten andere Anmeldeinformationstypen verwenden.

Authentifizierungsflow mit DefaultAzureCredential

  1. Umgebung - DefaultAzureCredential liest Kontoinformationen, die über angegeben wurden, und verwendet sie zur Authentifizierung.
  2. Workloadidentität: Wenn die Anwendung in Azure Kubernetes Service mit aktivierter verwalteter Identität bereitgestellt wird, DefaultAzureCredential authentifiziert sich damit.
  3. Verwaltete Identität : Wenn die Anwendung auf einem Azure-Host mit aktivierter verwalteter Identität bereitgestellt wird, DefaultAzureCredential authentifiziert sich damit.
  4. Azure CLI : Wenn sich ein Benutzer über den Azure CLI-Befehl az login angemeldet hat, DefaultAzureCredential authentifiziert sich als dieser Benutzer.
  5. Azure PowerShell: Wenn sich ein Benutzer über den Befehl Azure PowerShell Connect-AzAccount angemeldet hat, DefaultAzureCredential authentifiziert sich als dieser Benutzer.
  6. Azure Developer CLI: Wenn sich der Entwickler über den Befehl Azure Developer CLI azd auth login authentifiziert hat, authentifiziert sich der DefaultAzureCredential bei diesem Konto.
  7. Interaktiver Browser : Wenn er aktiviert ist, DefaultAzureCredential authentifiziert einen Benutzer interaktiv über den Standardbrowser. Dieser Anmeldeinformationstyp ist standardmäßig deaktiviert.

Hinweis zu VisualStudioCodeCredential

Aufgrund eines bekannten ProblemsVisualStudioCodeCredential wurde aus der DefaultAzureCredential Tokenkette entfernt. Wenn das Problem in einem zukünftigen Release behoben wird, wird diese Änderung wiederhergestellt.

Beispiele

Nachfolgend finden Sie die folgenden Beispiele:

Authentifizieren mit DefaultAzureCredential

Weitere Informationen zum Konfigurieren Ihrer Umgebung für die Verwendung von DefaultAzureCredential finden Sie in der Referenzdokumentation der -Klasse.

In diesem Beispiel wird die Authentifizierung von BlobServiceClient aus der azure-storage-blob-Bibliothek mithilfe DefaultAzureCredentialvon veranschaulicht.

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

default_credential = DefaultAzureCredential()

client = BlobServiceClient(account_url, credential=default_credential)

Aktivieren der interaktiven Authentifizierung mit DefaultAzureCredential

Die interaktive Authentifizierung ist standardmäßig DefaultAzureCredential deaktiviert und kann mit einem Schlüsselwort (keyword)-Argument aktiviert werden:

DefaultAzureCredential(exclude_interactive_browser_credential=False)

Wenn diese Option aktiviert ist, greift auf die interaktive Authentifizierung über den Standardwebbrowser des Systems zurück, DefaultAzureCredential wenn keine anderen Anmeldeinformationen verfügbar sind.

Angeben einer benutzerseitig zugewiesenen verwalteten Identität für DefaultAzureCredential

Viele Azure-Hosts ermöglichen die Zuweisung einer benutzerseitig zugewiesenen verwalteten Identität. Verwenden Sie zum Konfigurieren DefaultAzureCredential der Authentifizierung einer benutzerseitig zugewiesenen Identität das managed_identity_client_id Argument Schlüsselwort (keyword):

DefaultAzureCredential(managed_identity_client_id=client_id)

Alternativ können Sie die Umgebungsvariable AZURE_CLIENT_ID auf die Client-ID der Identität festlegen.

Definieren eines benutzerdefinierten Authentifizierungsflusses mit ChainedTokenCredential

DefaultAzureCredential ist im Allgemeinen der schnellste Weg, um mit der Entwicklung von Anwendungen für Azure zu beginnen. Für komplexere Szenarien verknüpft ChainedTokenCredential mehrere Anmeldeinformationsinstanzen, die bei der Authentifizierung sequenziell getestet werden sollen. Es werden alle verketteten Anmeldeinformationen nacheinander ausprobiert, bis ein Token bereitgestellt wird oder die Authentifizierung aufgrund eines Fehlers fehlschlägt.

Im folgenden Beispiel wird das Erstellen von Anmeldeinformationen veranschaulicht, die zuerst versuchen, sich mithilfe einer verwalteten Identität zu authentifizieren. Die Anmeldeinformationen greifen auf die Authentifizierung über die Azure CLI zurück, wenn eine verwaltete Identität nicht verfügbar ist. In diesem Beispiel wird die EventHubProducerClient aus der Azure-eventhub-Clientbibliothek verwendet.

from azure.eventhub import EventHubProducerClient
from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential

managed_identity = ManagedIdentityCredential()
azure_cli = AzureCliCredential()
credential_chain = ChainedTokenCredential(managed_identity, azure_cli)

client = EventHubProducerClient(namespace, eventhub_name, credential_chain)

Asynchrone Anmeldeinformationen

Diese Bibliothek enthält eine Reihe von asynchronen APIs. Um die asynchronen Anmeldeinformationen in azure.identity.aio verwenden zu können, müssen Sie zunächst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu azure-core.

Asynchrone Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Jede asynchrone Anmeldeinformation ist ein asynchroner Kontext-Manager und definiert eine asynchrone close Methode. Zum Beispiel:

from azure.identity.aio import DefaultAzureCredential

# call close when the credential is no longer needed
credential = DefaultAzureCredential()
...
await credential.close()

# alternatively, use the credential as an async context manager
credential = DefaultAzureCredential()
async with credential:
  ...

In diesem Beispiel wird die Authentifizierung der asynchronen SecretClient von azure-keyvault-secrets mit asynchronen Anmeldeinformationen veranschaulicht.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient

default_credential = DefaultAzureCredential()
client = SecretClient("https://my-vault.vault.azure.net", default_credential)

Unterstützung verwalteter Identitäten

Die Authentifizierung verwalteter Identitäten wird entweder über oder DefaultAzureCredentialManagedIdentityCredential direkt für die folgenden Azure-Dienste unterstützt:

Beispiele

Authentifizieren mit einer benutzerseitig zugewiesenen verwalteten Identität

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential(client_id=managed_identity_client_id)
client = SecretClient("https://my-vault.vault.azure.net", credential)

Authentifizieren mit einer systemseitig zugewiesenen verwalteten Identität

from azure.identity import ManagedIdentityCredential
from azure.keyvault.secrets import SecretClient

credential = ManagedIdentityCredential()
client = SecretClient("https://my-vault.vault.azure.net", credential)

Cloudkonfiguration

Anmeldeinformationen werden standardmäßig beim Azure AD-Endpunkt für die öffentliche Azure-Cloud authentifiziert. Um auf Ressourcen in anderen Clouds wie Azure Government oder einer privaten Cloud zuzugreifen, konfigurieren Sie Anmeldeinformationen mit dem authority Argument. AzureAuthorityHosts definiert Autoritäten für bekannte Clouds:

from azure.identity import AzureAuthorityHosts

DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT)

Wenn die Autorität für Ihre Cloud nicht in AzureAuthorityHostsaufgeführt ist, können Sie die zugehörige URL explizit angeben:

DefaultAzureCredential(authority="https://login.partner.microsoftonline.cn")

Alternativ zum Angeben des authority Arguments können Sie die AZURE_AUTHORITY_HOST Umgebungsvariable auch auf die URL der Autorität Ihrer Cloud festlegen. Dieser Ansatz ist nützlich, wenn mehrere Anmeldeinformationen für die Authentifizierung bei derselben Cloud konfiguriert werden:

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

Nicht für alle Anmeldeinformationen ist diese Konfiguration erforderlich. Anmeldeinformationen, die sich über ein Entwicklungstool authentifizieren, z AzureCliCredential. B. , verwenden die Konfiguration dieses Tools. Ebenso akzeptiert ein authority Argument, aber standardmäßig die Autorität, VisualStudioCodeCredential die der Einstellung "Azure: Cloud" von VS Code entspricht.

Anmeldeinformationsklassen

Authentifizieren von azure gehosteten Anwendungen

Anmeldeinformationen Verwendung
DefaultAzureCredential Bietet eine vereinfachte Authentifizierungsoberfläche, um schnell mit der Entwicklung von Anwendungen zu beginnen, die in Azure ausgeführt werden.
ChainedTokenCredential Ermöglicht Benutzern das Definieren von benutzerdefinierten Authentifizierungsflüssen, die mehrere Anmeldeinformationen erstellen.
EnvironmentCredential Authentifiziert einen Dienstprinzipal oder Benutzer über die in den Umgebungsvariablen angegebenen Anmeldeinformationen.
ManagedIdentityCredential Authentifiziert die verwaltete Identität einer Azure-Ressource.
WorkloadIdentityCredential Unterstützt die Azure AD-Workloadidentität in Kubernetes.

Authentifizieren von Dienstprinzipalen

Anmeldeinformationen Verwendung Verweis
CertificateCredential Authentifiziert einen Dienstprinzipal mithilfe eines Zertifikats. Dienstprinzipalauthentifizierung
ClientAssertionCredential Authentifiziert einen Dienstprinzipal mithilfe einer signierten Clientassertion.
ClientSecretCredential Authentifiziert einen Dienstprinzipal mithilfe eines geheimen Schlüssels. Dienstprinzipalauthentifizierung

Authentifizieren von Benutzern

Anmeldeinformationen Verwendung Verweis
AuthorizationCodeCredential Authentifiziert einen Benutzer mit einem zuvor abgerufenen Autorisierungscode. OAuth2-Authentifizierungscode
DeviceCodeCredential Authentifiziert einen Benutzer interaktiv auf Geräten mit eingeschränkter Benutzeroberfläche. Gerätecodeauthentifizierung
InteractiveBrowserCredential Authentifiziert einen Benutzer interaktiv mit dem Standardsystembrowser. OAuth2-Authentifizierungscode
OnBehalfOfCredential Gibt die delegierte Benutzeridentität und die Berechtigungen über die Anforderungskette weiter. Authentifizierung im Auftrag von
UsernamePasswordCredential Authentifiziert einen Benutzer mit einem Benutzernamen und einem Kennwort (unterstützt keine mehrstufige Authentifizierung). Authentifizierung mit Benutzername + Kennwort

Authentifizieren über Entwicklungstools

Anmeldeinformationen Verwendung Verweis
AzureCliCredential Authentifiziert sich in einer Entwicklungsumgebung mit der Azure CLI. Azure CLI-Authentifizierung
AzureDeveloperCliCredential Authentifiziert sich in einer Entwicklungsumgebung mit dem Azure Developer CLI. Azure Developer CLI-Referenz
AzurePowerShellCredential Authentifiziert sich in einer Entwicklungsumgebung mit dem Azure PowerShell. Azure PowerShell-Authentifizierung
VisualStudioCodeCredential Authentifiziert sich als Benutzer, der bei der Azure-Kontoerweiterung von Visual Studio Code angemeldet ist. Azure-Kontoerweiterung für VS Code

Umgebungsvariablen

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

Dienstprinzipal mit Geheimnis

Variablenname Wert
AZURE_CLIENT_ID ID einer Azure AD-Anwendung
AZURE_TENANT_ID ID des Azure AD-Mandanten der Anwendung
AZURE_CLIENT_SECRET Eines der Clientgeheimnisse der Anwendung

Dienstprinzipal mit Zertifikat

Variablenname Wert
AZURE_CLIENT_ID ID einer Azure AD-Anwendung
AZURE_TENANT_ID ID des Azure AD-Mandanten der Anwendung
AZURE_CLIENT_CERTIFICATE_PATH Pfad zu einer PEM- oder PKCS12-Zertifikatdatei einschließlich privatem Schlüssel
AZURE_CLIENT_CERTIFICATE_PASSWORD Kennwort der Zertifikatdatei, falls vorhanden

Benutzername und Kennwort

Variablenname Wert
AZURE_CLIENT_ID ID einer Azure AD-Anwendung
AZURE_USERNAME Ein Benutzername (normalerweise eine E-Mail-Adresse)
AZURE_PASSWORD Das Kennwort des Benutzers

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

Zwischenspeichern von Tokens

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

  • Cachetoken im Arbeitsspeicher (Standard) oder auf dem Datenträger (opt-in).
  • Verbessern sie Resilienz und Leistung.
  • Verringern Sie die Anzahl von Anforderungen, die an Azure AD zum Abrufen von Zugriffstoken gesendet werden.

Die Azure Identity-Bibliothek bietet sowohl In-Memory- als auch persistente Datenträgerzwischenspeicherung. Weitere Informationen finden Sie in der Dokumentation zur Tokenzwischenspeicherung.

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im Leitfaden zur Problembehandlung .

Fehlerbehandlung

Anmeldeinformationen werden angezeigt CredentialUnavailableError , wenn sie nicht versuchen können, die Authentifizierung zu versuchen, weil ihnen die erforderlichen Daten oder der erforderliche Zustand fehlen. Beispielsweise löst EnvironmentCredential diese Ausnahme aus, wenn unvollständig ist.

Anmeldeinformationen lösen azure.core.exceptions.ClientAuthenticationError aus, wenn sie nicht authentifiziert werden können. ClientAuthenticationError verfügt über ein message -Attribut, das beschreibt, warum die Authentifizierung fehlgeschlagen ist. Wenn sie von oder ChainedTokenCredentialausgelöst wirdDefaultAzureCredential, sammelt die Meldung Fehlermeldungen aus den einzelnen Anmeldeinformationen in der Kette.

Weitere Informationen zum Behandeln bestimmter Azure AD-Fehler finden Sie in der Dokumentation zu Azure AD-Fehlercode.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Anmeldeinformationen protokollieren grundlegende Informationen, einschließlich HTTP-Sitzungen (URLs, Header usw.) auf INFO-Ebene. Diese Protokolleinträge enthalten keine Authentifizierungsgeheimnisse.

Die detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und Headerwerten, ist standardmäßig nicht aktiviert. Sie kann mit dem logging_enable -Argument aktiviert werden. Zum Beispiel:

credential = DefaultAzureCredential(logging_enable=True)

ACHTUNG: Protokolle auf DEBUGebene von Anmeldeinformationen enthalten vertrauliche Informationen. Diese Protokolle müssen geschützt werden, um eine Beeinträchtigung der Kontosicherheit zu vermeiden.

Nächste Schritte

Unterstützung von Clientbibliotheken

Client- und Verwaltungsbibliotheken, die auf der Releaseseite des Azure SDK aufgeführt sind und azure AD-Authentifizierung unterstützen, akzeptieren Anmeldeinformationen aus dieser Bibliothek. Weitere Informationen zur Verwendung dieser Bibliotheken finden Sie in der Dokumentation, die auf der Releaseseite verlinkt ist.

Bekannte Probleme

Diese Bibliothek unterstützt Azure AD B2C nicht.

Weitere offene Probleme finden Sie im GitHub-Repository der Bibliothek.

Feedback bereitstellen

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

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys mit unserer CLA tun.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Kommentare haben.

Aufrufe