Azure Key Vault Secrets-Clientbibliothek für Python– Version 4.7.0
Mit Azure Key Vault lassen sich folgende Probleme lösen:
- Geheimnisverwaltung (diese Bibliothek): Sicheres Speichern und Steuern des Zugriffs auf Token, Kennwörter, Zertifikate, API-Schlüssel und andere Geheimnisse
- Verwaltung kryptografischer Schlüssel (azure-keyvault-keys): Erstellen, Speichern und Steuern des Zugriffs auf die Schlüssel, die zum Verschlüsseln Ihrer Daten verwendet werden
- Zertifikatverwaltung (azure-keyvault-certificates): Erstellen, Verwalten und Bereitstellen öffentlicher und privater SSL/TLS-Zertifikate
- Tresorverwaltung (azure-keyvault-administration): Rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) und Sicherungs- und Wiederherstellungsoptionen auf Tresorebene
Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben
Haftungsausschluss
Die Unterstützung von Azure SDK-Python-Paketen für Python 2.7 endet am 01. Januar 2022. Weitere Informationen und Antworten finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691. Für die Verwendung dieses Pakets ist Python 3.7 oder höher erforderlich. Weitere Informationen finden Sie unter Unterstützungsrichtlinie für Azure SDK für Python-Versionen.
Erste Schritte
Installieren von Paketen
Installieren Sie azure-keyvault-secrets und azure-identity mit pip:
pip install azure-keyvault-secrets azure-identity
azure-identity wird für die Azure Active Directory-Authentifizierung verwendet, wie unten gezeigt.
Voraussetzungen
- Ein Azure-Abonnement
- Python 3.7 oder höher
- Eine vorhandene Azure Key Vault. Wenn Sie eine erstellen müssen, können Sie dies mithilfe der Azure CLI tun, indem Sie die Schritte in diesem Dokument ausführen.
Authentifizieren des Clients
Für die Interaktion mit dem Azure Key Vault-Dienst benötigen Sie eine Instanz eines SecretClient sowie eine Tresor-URL und ein Anmeldeinformationsobjekt. In diesem Dokument wird die Verwendung von DefaultAzureCredential veranschaulicht, die für die meisten Szenarien geeignet ist, einschließlich lokaler Entwicklungs- und Produktionsumgebungen. Es wird empfohlen, eine verwaltete Identität für die Authentifizierung in Produktionsumgebungen zu verwenden.
Weitere Informationen zu anderen Authentifizierungsmethoden und den entsprechenden Anmeldeinformationstypen finden Sie in der Dokumentation zu azure-identity .
Erstellen eines Clients
Nachdem Sie Ihre Umgebung für defaultAzureCredential für die Verwendung einer geeigneten Authentifizierungsmethode konfiguriert haben, können Sie wie folgt vorgehen, um einen geheimen Client zu erstellen (indem Sie den Wert von durch VAULT_URL die URL Ihres Tresors ersetzen):
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)
HINWEIS: Für einen asynchronen Client importieren Sie
azure.keyvault.secrets.aiostattdessen die vonSecretClient.
Wichtige Begriffe
`Secret`
Ein Geheimnis besteht aus einem Geheimniswert und den zugehörigen Metadaten und Verwaltungsinformationen. Diese Bibliothek verarbeitet Geheimwerte als Zeichenfolgen, aber Azure Key Vault speichert sie nicht als solche. Weitere Informationen zu Geheimnissen und wie Key Vault sie speichert und verwaltet, finden Sie in der Key Vault-Dokumentation.
SecretClient kann Geheimniswerte im Tresor festlegen, geheime Metadaten aktualisieren und Geheimnisse löschen, wie in den folgenden Beispielen gezeigt.
Beispiele
Dieser Abschnitt enthält Codeausschnitte zu allgemeinen Aufgaben:
- Festlegen eines Geheimnisses
- Abrufen eines Geheimnisses
- Aktualisieren von Geheimnismetadaten
- Löschen eines Geheimnisses
- Auflisten von Geheimnissen
- Asynchrone API
- Asynchrones Erstellen eines Geheimnisses
- Asynchrones Auflisten von Geheimnissen
Festlegen eines Geheimnisses
set_secret erstellt neue Geheimnisse und ändert die Werte vorhandener Geheimnisse. Wenn kein Geheimnis mit dem angegebenen Namen vorhanden ist, set_secret erstellt ein neues Geheimnis mit diesem Namen und dem angegebenen Wert. Wenn der angegebene Name verwendet wird, set_secret erstellt eine neue Version dieses Geheimnisses mit dem angegebenen Wert.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
Abrufen eines Geheimnisses
get_secret ruft ein Geheimnis ab, das zuvor im Key Vault gespeichert wurde.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")
print(secret.name)
print(secret.value)
Aktualisieren von Geheimnismetadaten
update_secret_properties aktualisiert die Metadaten eines Geheimnisses. Der Wert des Geheimnisses kann nicht geändert werden. verwenden Sie set_secret , um den Wert eines Geheimnisses festzulegen.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"
# We will also disable the secret for further use
updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)
print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)
Löschen eines Geheimnisses
begin_delete_secret Anforderungen Key Vault Löschen eines Geheimnisses und geben einen Abruf zurück, mit dem Sie auf den Abschluss des Löschvorgangs warten können. Warten ist hilfreich, wenn für den Tresor vorläufiges Löschen aktiviert ist und Sie das Geheimnis so schnell wie möglich löschen (dauerhaft löschen) möchten. Wenn vorläufiges Löschen deaktiviert ist, begin_delete_secret ist selbst dauerhaft.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()
print(deleted_secret.name)
print(deleted_secret.deleted_date)
Auflisten geheimer Schlüssel
list_properties_of_secrets listet die Eigenschaften aller Geheimnisse im Tresor des Clients auf. Diese Liste enthält nicht die Werte des Geheimnisses.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
Asynchrone API
Diese Bibliothek enthält einen vollständigen Satz von asynchronen APIs. Um sie 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 Clients und Anmeldeinformationen sollten geschlossen werden, wenn sie nicht mehr benötigt werden. Diese Objekte sind asynchrone Kontext-Manager und definieren asynchrone close Methoden. Beispiel:
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
...
await client.close()
await credential.close()
# alternatively, use them as async context managers (contextlib.AsyncExitStack can help)
client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
Asynchrones Erstellen eines Geheimnisses
set_secret erstellt ein Geheimnis im Key Vault mit den angegebenen optionalen Argumenten.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = await secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
Asynchrones Auflisten von Geheimnissen
list_properties_of_secrets listet die Eigenschaften aller Geheimnisse im Tresor des Clients auf.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
async for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
Problembehandlung
Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im azure-keyvault-secretsLeitfaden zur Problembehandlung .
Allgemein
Key Vault Clients lösen ausnahmen aus, die in azure-core definiert sind. Wenn Sie beispielsweise versuchen, einen Schlüssel abzurufen, der nicht im Tresor vorhanden ist, löst SecretClientResourceNotFoundError aus:
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
secret_client.get_secret("which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
Protokollierung
Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.
Die detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable -Argument aktiviert werden:
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
import sys
import logging
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)
# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
credential = DefaultAzureCredential()
# This client will log detailed information about its HTTP sessions, at DEBUG level
secret_client = SecretClient(
vault_url="https://my-key-vault.vault.azure.net/",
credential=credential,
logging_enable=True
)
Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:
secret_client.get_secret("my-secret", logging_enable=True)
Nächste Schritte
Im GitHub-Repository azure SDK für Python sind mehrere Beispiele verfügbar. Diese bieten Beispielcode für zusätzliche Key Vault Szenarien: | Datei | Beschreibung | |-------------|-------------| | hello_world.py (asynchrone Version) | Erstellen/Abrufen/Aktualisieren/Löschen von Geheimnissen | | list_operations.py (asynchrone Version) | grundlegende Listenvorgänge für Geheimnisse | | backup_restore_operations.py (asynchrone Version) | Sichern und Wiederherstellen von Geheimnissen | | recover_purge_operations.py (asynchrone Version) | Wiederherstellen und Bereinigen von Geheimnissen |
Zusätzliche Dokumentation
Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.
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 ausführen, die unsere CLA verwenden.
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.
Azure SDK for Python
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für