Azure Key Vault-Verwaltungsclientbibliothek für Python – Version 4.3.0
Hinweis: Die Verwaltungsbibliothek funktioniert nur mit verwaltetem HSM. Funktionen, die auf eine Key Vault abzielen, schlagen fehl.
Mit Azure Key Vault lassen sich folgende Probleme lösen:
- Tresorverwaltung (diese Bibliothek): Rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) und Sicherungs- und Wiederherstellungsoptionen auf Tresorebene
- Kryptografische Schlüsselverwaltung (azure-keyvault-keys): Erstellen, Speichern und Steuern des Zugriffs auf die Schlüssel, die zum Verschlüsseln Ihrer Daten verwendet werden
- Geheimnisseverwaltung (azure-keyvault-secrets): Sicheres Speichern und Steuern des Zugriffs auf Token, Kennwörter, Zertifikate, API-Schlüssel und andere Geheimnisse
- Zertifikatverwaltung (azure-keyvault-certificates): Erstellen, Verwalten und Bereitstellen öffentlicher und privater SSL/TLS-Zertifikate
Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben
Haftungsausschluss
Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Fragen finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 oder höher ist erforderlich, um dieses Paket zu verwenden. Weitere Informationen finden Sie unter Supportrichtlinie für Azure SDK für Python-Versionen.
Erste Schritte
Installieren von Paketen
Installieren Sie azure-keyvault-administration und azure-identity mit pip:
pip install azure-keyvault-administration 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
- Ein vorhandenes Key Vault Verwaltetes HSM. 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
Um mit dem Azure Key Vault-Dienst zu interagieren, benötigen Sie entweder eine Instanz von KeyVaultAccessControlClient oder KeyVaultBackupClient sowie eine Tresor-URL (die im Azure-Portal als "DNS-Name" angezeigt wird) 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 KeyVaultAccessControlClient
Nachdem Sie Ihre Umgebung für DefaultAzureCredential für die Verwendung einer geeigneten Authentifizierungsmethode konfiguriert haben, können Sie einen Zugriffssteuerungsclient wie folgt erstellen (indem Sie den Wert von vault_url durch die URL Ihres verwalteten HSMs ersetzen):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
HINWEIS: Für einen asynchronen Client importieren Sie
azure.keyvault.administration.aiostattdessen "sKeyVaultAccessControlClient".
Erstellen eines KeyVaultBackupClient
Nachdem Sie Ihre Umgebung für DefaultAzureCredential konfiguriert haben, um eine geeignete Authentifizierungsmethode zu verwenden, können Sie einen Sicherungsclient erstellen (indem Sie den Wert von vault_url durch die URL Ihres verwalteten HSM ersetzen):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
HINWEIS: Für einen asynchronen Client importieren Sie
azure.keyvault.administration.aiostattdessen "sKeyVaultBackupClient".
Erstellen eines KeyVaultSettingsClient
Nachdem Sie Ihre Umgebung für DefaultAzureCredential konfiguriert haben, um eine geeignete Authentifizierungsmethode zu verwenden, können Sie wie folgt vorgehen, um einen Einstellungsclient zu erstellen (indem Sie den Wert von vault_url durch die URL Ihres verwalteten HSMs ersetzen):
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient
credential = DefaultAzureCredential()
client = KeyVaultSettingsClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
HINWEIS: Für einen asynchronen Client importieren Sie
azure.keyvault.administration.aiostattdessen "sKeyVaultSettingsClient".
Wichtige Begriffe
Rollendefinition
Eine Rollendefinition definiert die Vorgänge, die ausgeführt werden können, z. B. Lese-, Schreib- und Löschvorgänge. Sie kann auch die Vorgänge definieren, die von zulässigen Vorgängen ausgeschlossen sind.
Eine Rollendefinition wird im Rahmen einer Rollenzuweisung angegeben.
Rollenzuweisung
Eine Rollenzuweisung ist die Zuordnung einer Rollendefinition zu einem Dienstprinzipal. Sie können erstellt, aufgelistet, einzeln abgerufen und gelöscht werden.
KeyVaultAccessControlClient
A KeyVaultAccessControlClient verwaltet Rollendefinitionen und Rollenzuweisungen.
KeyVaultBackupClient
A KeyVaultBackupClient führt vollständige Schlüsselsicherungen, vollständige Schlüsselwiederherstellungen und selektive Schlüsselwiederherstellungen durch.
KeyVaultSettingsClient
Verwaltete KeyVaultSettingsClient HSM-Kontoeinstellungen werden verwaltet.
Beispiele
Dieser Abschnitt enthält Codeausschnitte zu häufigen Aufgaben:
- Zugriffssteuerung
- Sichern und Wiederherstellen
Auflisten aller Rollendefinitionen
Listet die für die Zuweisung verfügbaren Rollendefinitionen auf.
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)
for definition in role_definitions:
print(definition.id)
print(definition.role_name)
print(definition.description)
Festlegen, Abrufen und Löschen einer Rollendefinition
set_role_definition kann verwendet werden, um entweder eine benutzerdefinierte Rollendefinition zu erstellen oder eine vorhandene Definition mit dem angegebenen Namen zu aktualisieren.
import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
KeyVaultAccessControlClient,
KeyVaultDataAction,
KeyVaultPermission,
KeyVaultRoleScope
)
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)
# update the custom role definition
permissions = [
KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)
# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)
Auflisten aller Rollenzuweisungen
Listen Sie vor dem Erstellen einer neuen Rollenzuweisung im nächsten Codeausschnitt alle aktuellen Rollenzuweisungen auf:
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)
for assignment in role_assignments:
print(assignment.name)
print(assignment.principal_id)
print(assignment.role_definition_id)
Erstellen, Abrufen und Löschen einer Rollenzuweisung
Weisen Sie einem Dienstprinzipal eine Rolle zu. Dies erfordert eine Rollendefinitions-ID und eine Dienstprinzipalobjekt-ID. Sie können eine ID aus der abgerufenen Liste der Rollendefinitionen für erstere und eine Zuweisung principal_id aus der Liste verwenden, die im obigen Codeausschnitt abgerufen wurde.
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(
vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
credential=credential
)
# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"
# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)
Ausführen einer vollständigen Schlüsselsicherung
Sichern Sie Ihre gesamte Schlüsselsammlung. Der Sicherungsspeicher für vollständige Schlüsselsicherungen ist ein Blobspeichercontainer, der die Shared Access Signature-Authentifizierung verwendet.
Weitere Informationen zum Erstellen eines SAS-Tokens mithilfe von BlobServiceClientfinden Sie im folgenden Beispiel.
Alternativ ist es möglich, ein SAS-Token in Storage-Explorer
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()
# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)
Ausführen einer vollständigen Schlüsselwiederherstellung
Stellen Sie Ihre gesamte Sammlung von Schlüsseln aus einer Sicherung wieder her. Die Datenquelle für eine vollständige Schlüsselwiederherstellung ist ein Speicherblob, auf das mithilfe der Shared Access Signature-Authentifizierung zugegriffen wird.
Sie benötigen auch den azure_storage_blob_container_uri aus dem obigen Codeausschnitt.
Weitere Informationen zum Erstellen eines SAS-Tokens mithilfe von BlobServiceClientfinden Sie im folgenden Beispiel.
Alternativ ist es möglich, ein SAS-Token in Storage-Explorer
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient
credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
sas_token = "<your-sas-token>" # replace with a sas token to your storage account
# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"
# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()
Problembehandlung
Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im azure-keyvault-administrationLeitfaden zur Problembehandlung .
Allgemein
Key Vault Clients lösen ausnahmen aus, die in azure-core definiert sind. Wenn Sie beispielsweise versuchen, eine nicht vorhandene Rollenzuweisung abzurufen, löst KeyVaultAccessControlClient ResourceNotFoundError aus:
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)
try:
client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
print(e.message)
Clients aus der Verwaltungsbibliothek können nur zum Ausführen von Vorgängen auf einem verwalteten HSM verwendet werden. Wenn Sie dies auf einer Key Vault tun, wird ein Fehler ausgelöst.
Nächste Schritte
Im GitHub-Repository des Azure SDK für Python sind mehrere Beispiele verfügbar. Diese Beispiele bieten Beispielcode für zusätzliche Key Vault Szenarien: | Datei | Beschreibung | |-------------|-------------| | access_control_operations.py | Erstellen/Aktualisieren/Löschen von Rollendefinitionen und Rollenzuweisungen | | access_control_operations_async.py | Erstellen/Aktualisieren/Löschen von Rollendefinitionen und Rollenzuweisungen mit einem asynchronen Client | | backup_restore_operations.py | vollständige Sicherung und Wiederherstellung | | | backup_restore_operations_async.py | vollständige Sicherung und Wiederherstellung mit einem asynchronen Client | | settings_operations.py | Key Vault Einstellungen auflisten und aktualisieren | | settings_operations_async.py | Auflisten und Aktualisieren Key Vault Einstellungen mit einem asynchronen Client |
Zusätzliche Dokumentation
Eine ausführlichere Dokumentation zu Azure Key Vault finden Sie in der API-Referenzdokumentation.
Eine ausführlichere Dokumentation zu verwaltetem HSM finden Sie in der Dienstdokumentation.
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