Freigeben über

Azure Key Vault Keys-Clientbibliothek für Python– Version 4.8.0

  • Artikel

Mit Azure Key Vault lassen sich folgende Probleme lösen:

  • Verwaltung kryptografischer Schlüssel (diese Bibliothek): Erstellen, Speichern und Steuern des Zugriffs auf die Schlüssel, die zum Verschlüsseln Ihrer Daten verwendet werden
  • Geheimnisverwaltung (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
  • 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 des Pakets

Installieren Sie azure-keyvault-keys und azure-identity mit pip:

pip install azure-keyvault-keys azure-identity

azure-identity wird für die Azure Active Directory-Authentifizierung verwendet, wie unten gezeigt.

Voraussetzungen

Authentifizieren des Clients

Für die Interaktion mit dem Azure Key Vault-Dienst benötigen Sie eine Instanz eines KeyClient 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 Schlüsselclient zu erstellen (indem Sie den Wert von durch VAULT_URL die URL Ihres Tresors ersetzen):

VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)

HINWEIS: Für einen asynchronen Client importieren Sie azure.keyvault.keys.aiostattdessen die von KeyClient .

Wichtige Begriffe

Tasten

Azure Key Vault kann RSA- und elliptische Kurvenschlüssel erstellen und speichern. Beide können optional durch Hardwaresicherheitsmodule (HSMs) geschützt werden. Azure Key Vault kann auch kryptografische Vorgänge mit ihnen ausführen. Weitere Informationen zu Schlüsseln und unterstützten Vorgängen und Algorithmen finden Sie in der Key Vault-Dokumentation.

KeyClient kann Schlüssel im Tresor erstellen, vorhandene Schlüssel aus dem Tresor abrufen, Schlüsselmetadaten aktualisieren und Schlüssel löschen, wie in den folgenden Beispielen gezeigt.

Beispiele

Dieser Abschnitt enthält Codeausschnitte zu allgemeinen Aufgaben:

Erstellen eines Schlüssels

create_rsa_key und create_ec_key rsa- bzw. elliptische Kurvenschlüssel im Tresor erstellen. Wenn bereits ein Schlüssel mit demselben Namen vorhanden ist, wird eine neue Version dieses Schlüssels erstellt.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Abrufen eines Schlüssels

get_key ruft einen Schlüssel ab, der zuvor im Tresor gespeichert wurde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
key = key_client.get_key("key-name")
print(key.name)

Aktualisieren eines vorhandenen Schlüssels

update_key_properties aktualisiert die Eigenschaften eines Schlüssels, der zuvor im Key Vault gespeichert wurde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# we will now disable the key for further use
updated_key = key_client.update_key_properties("key-name", enabled=False)

print(updated_key.name)
print(updated_key.properties.enabled)

Löschen eines Schlüssels

begin_delete_key Anforderungen Key Vault Löschen eines Schlüssels und geben einen Poller 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 den Schlüssel so schnell wie möglich löschen (dauerhaft löschen) möchten. Wenn vorläufiges Löschen deaktiviert ist, begin_delete_key ist selbst dauerhaft.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_key = key_client.begin_delete_key("key-name").result()

print(deleted_key.name)
print(deleted_key.deleted_date)

Konfigurieren der automatischen Schlüsselrotation

mit update_key_rotation_policy können Sie die automatische Schlüsselrotation für einen Schlüssel konfigurieren, indem Sie eine Rotationsrichtlinie angeben. Darüber hinaus können Sie mit rotate_key einen Schlüssel bei Bedarf rotieren, indem Sie eine neue Version des angegebenen Schlüssels erstellen.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Set the key's automated rotation policy to rotate the key 30 days before the key expires
actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
# You may also specify the duration after which the newly rotated key will expire
# In this example, any new key versions will expire after 90 days
updated_policy = key_client.update_key_rotation_policy("key-name", expires_in="P90D", lifetime_actions=actions)

# You can get the current rotation policy for a key with get_key_rotation_policy
current_policy = key_client.get_key_rotation_policy("key-name")

# Finally, you can rotate a key on-demand by creating a new version of the key
rotated_key = key_client.rotate_key("key-name")

Auflisten von Schlüsseln

list_properties_of_keys listet die Eigenschaften aller Schlüssel im Tresor des Clients auf.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient

credential = DefaultAzureCredential()

key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

for key in keys:
    # the list doesn't include values or versions of the keys
    print(key.name)

Kryptografische Vorgänge

CryptographyClient ermöglicht kryptografische Vorgänge (Verschlüsseln/Entschlüsseln, Packen/Entpacken, Signieren/Überprüfen) mithilfe eines bestimmten Schlüssels.

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

key = key_client.get_key("key-name")
crypto_client = CryptographyClient(key, credential=credential)
plaintext = b"plaintext"

result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep, plaintext)
decrypted = crypto_client.decrypt(result.algorithm, result.ciphertext)

Weitere Informationen zur Kryptografie-API finden Sie in der Paketdokumentation .

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.keys.aio import KeyClient

credential = DefaultAzureCredential()

# call close when the client and credential are no longer needed
client = KeyClient(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 = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
  async with credential:
    ...

Asynchrones Erstellen eines Schlüssels

create_rsa_key und create_ec_key rsa- bzw. elliptische Kurvenschlüssel im Tresor erstellen. Wenn bereits ein Schlüssel mit demselben Namen vorhanden ist, wird eine neue Version des Schlüssels erstellt.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

# Create an RSA key
rsa_key = await key_client.create_rsa_key("rsa-key-name", size=2048)
print(rsa_key.name)
print(rsa_key.key_type)

# Create an elliptic curve key
ec_key = await key_client.create_ec_key("ec-key-name", curve="P-256")
print(ec_key.name)
print(ec_key.key_type)

Asynchrones Auflisten von Schlüsseln

list_properties_of_keys listet die Eigenschaften aller Schlüssel im Tresor des Clients auf.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.keys.aio import KeyClient

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
keys = key_client.list_properties_of_keys()

async for key in keys:
    print(key.name)

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie im azure-keyvault-keysLeitfaden 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 KeyClientResourceNotFoundError aus:

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)

try:
    key_client.get_key("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.keys import KeyClient
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
client = KeyClient(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:

client.get_key("my-key", 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) | Schlüssel erstellen/abrufen/aktualisieren/löschen | | list_operations.py (asynchrone Version) | grundlegende Listenvorgänge für Schlüssel | | backup_restore_operations.py (asynchrone Version) | Sichern und Wiederherstellen von Schlüsseln | | recover_purge_operations.py (asynchrone Version) | Wiederherstellungs- und Bereinigungsschlüssel | | send_request.py | Verwenden der send_request Clientmethode |

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.

Aufrufe