Azure Identity-Clientbibliothek für Python– Version 1.14.1
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:
DefaultAzureCredentialSoll 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.
- Umgebung -
DefaultAzureCredentialliest Kontoinformationen, die über angegeben wurden, und verwendet sie zur Authentifizierung. - Workloadidentität: Wenn die Anwendung in Azure Kubernetes Service mit aktivierter verwalteter Identität bereitgestellt wird,
DefaultAzureCredentialauthentifiziert sich damit. - Verwaltete Identität : Wenn die Anwendung auf einem Azure-Host mit aktivierter verwalteter Identität bereitgestellt wird,
DefaultAzureCredentialauthentifiziert sich damit. - Azure CLI : Wenn sich ein Benutzer über den Azure CLI-Befehl
az loginangemeldet hat,DefaultAzureCredentialauthentifiziert sich als dieser Benutzer. - Azure PowerShell: Wenn sich ein Benutzer über den Befehl Azure PowerShell
Connect-AzAccountangemeldet hat,DefaultAzureCredentialauthentifiziert sich als dieser Benutzer. - Azure Developer CLI: Wenn sich der Entwickler über den Befehl Azure Developer CLI
azd auth loginauthentifiziert hat, authentifiziert sich derDefaultAzureCredentialbei diesem Konto. - Interaktiver Browser : Wenn er aktiviert ist,
DefaultAzureCredentialauthentifiziert 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
- Definieren eines benutzerdefinierten Authentifizierungsflows mit ChainedTokenCredential
- Asynchrone Anmeldeinformationen
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:
- Azure App Service und Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes Service
- Azure Service Fabric
- Dokumentation zu virtuellen Computern
- Azure-VM-Skalierungsgruppen
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.
