Azure Key Vault Certificates-Clientbibliothek für Python– Version 4.7.0

Erste Schritte

Installieren des Pakets

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

pip install azure-keyvault-certificates 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 CertificateClient 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 konfiguriert haben, um eine geeignete Authentifizierungsmethode zu verwenden, können Sie folgendes tun, um einen Zertifikatclient zu erstellen (indem Sie den Wert von VAULT_URL durch die URL Ihres Tresors ersetzen):

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

HINWEIS: Für einen asynchronen Client importieren Sie azure.keyvault.certificates.aiostattdessen "s CertificateClient ".

Wichtige Begriffe

CertificateClient

Mit einem CertificateClient können Sie Zertifikate aus dem Tresor abrufen, neue Zertifikate und neue Versionen vorhandener Zertifikate erstellen, Zertifikatmetadaten aktualisieren und Zertifikate löschen. Sie können auch Zertifikataussteller, Kontakte und Verwaltungsrichtlinien für Zertifikate verwalten. Dies wird in den folgenden Beispielen veranschaulicht.

Beispiele

Dieser Abschnitt enthält Codeausschnitte zu häufigen Aufgaben:

• Ein Zertifikat erstellen
• Abrufen eines Zertifikats
• Aktualisieren der Eigenschaften eines vorhandenen Zertifikats
• Ein Zertifikat löschen
• Auflisten der Eigenschaften von Zertifikaten
• Asynchrone Vorgänge
• Asynchrones Erstellen eines Zertifikats
• Asynchrones Auflisten der Eigenschaften von Zertifikaten

Erstellen eines Zertifikats

begin_create_certificate erstellt ein Zertifikat, das im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt. Vor dem Erstellen eines Zertifikats kann eine Verwaltungsrichtlinie für das Zertifikat erstellt werden, oder die Standardrichtlinie wird verwendet. Diese Methode gibt einen Abfragevorgang mit langer Ausführungsdauer zurück.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient, CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_poller = certificate_client.begin_create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_poller.result())

Wenn Sie den Status Ihrer Zertifikaterstellung überprüfen möchten, können Sie den Poller aufrufen status() oder mit dem Namen des Zertifikats get_certificate_operation .

Abrufen eines Zertifikats

get_certificate ruft die neueste Version eines Zertifikats ab, das zuvor im Key Vault gespeichert wurde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificate = certificate_client.get_certificate("cert-name")

print(certificate.name)
print(certificate.properties.version)
print(certificate.policy.issuer_name)

get_certificate_version ruft eine bestimmte Version eines Zertifikats ab.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

certificate_client = CertificateClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
certificate = certificate_client.get_certificate_version(certificate_name="cert-name", version="cert-version")

print(certificate.name)
print(certificate.properties.version)

Aktualisieren der Eigenschaften eines vorhandenen Zertifikats

update_certificate_properties aktualisiert ein Zertifikat, das zuvor im Key Vault gespeichert wurde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

# we will now disable the certificate for further use
updated_certificate= certificate_client.update_certificate_properties(
    certificate_name="cert-name", enabled=False
)

print(updated_certificate.name)
print(updated_certificate.properties.enabled)

Löschen eines Zertifikats

begin_delete_certificate Anforderungen Key Vault Löschen eines Zertifikats und geben einen Poller zurück, mit dem Sie warten können, bis der Löschvorgang abgeschlossen ist. Das Warten ist hilfreich, wenn für den Tresor vorläufiges Löschen aktiviert ist und Sie das Zertifikat so schnell wie möglich löschen (endgültig löschen) möchten. Wenn vorläufiges Löschen deaktiviert ist, begin_delete_certificate ist dies selbst dauerhaft.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

deleted_certificate_poller = certificate_client.begin_delete_certificate("cert-name")

deleted_certificate = deleted_certificate_poller.result()
print(deleted_certificate.name)
print(deleted_certificate.deleted_on)

Auflisten der Eigenschaften von Zertifikaten

list_properties_of_certificates listet die Eigenschaften aller Zertifikate im angegebenen Key Vault auf.

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()

for certificate in certificates:
    # this list doesn't include versions of the certificates
    print(certificate.name)

Asynchrone Vorgänge

Diese Bibliothek enthält einen vollständigen Satz asynchroner APIs. Um sie zu verwenden, müssen Sie zuerst 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.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

Asynchrones Erstellen eines Zertifikats

create_certificate erstellt ein Zertifikat, das im Azure-Key Vault gespeichert werden soll. Wenn bereits ein Zertifikat mit demselben Namen vorhanden ist, wird eine neue Version des Zertifikats erstellt. Vor dem Erstellen eines Zertifikats kann eine Verwaltungsrichtlinie für das Zertifikat erstellt werden, oder die Standardrichtlinie wird verwendet. Warten create_certificate gibt Ihr erstelltes Zertifikat zurück, wenn die Erstellung erfolgreich war, und eine CertificateOperation , falls nicht.

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient
from azure.keyvault.certificates import CertificatePolicy

credential = DefaultAzureCredential()

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

create_certificate_result = await certificate_client.create_certificate(
    certificate_name="cert-name", policy=CertificatePolicy.get_default()
)
print(create_certificate_result)

Asynchrones Auflisten der Eigenschaften von Zertifikaten

list_properties_of_certificates listet alle Eigenschaften der Zertifikate im Tresor des Clients auf:

from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.certificates.aio import CertificateClient

credential = DefaultAzureCredential()

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

certificates = certificate_client.list_properties_of_certificates()
async for certificate in certificates:
    print(certificate.name)

Problembehandlung

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

from azure.identity import DefaultAzureCredential
from azure.keyvault.certificates import CertificateClient
from azure.core.exceptions import ResourceNotFoundError

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

try:
    certificate_client.get_certificate("which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Protokollierung

Diese Bibliothek verwendet die Standardprotokollierungsbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine 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.certificates import CertificateClient
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 = CertificateClient(
    vault_url="https://my-key-vault.vault.azure.net/",
    credential=credential,
    logging_enable=True
)

Die Protokollierung der Netzwerkablaufverfolgung kann auch für jeden einzelnen Vorgang aktiviert werden:

certificate = certificate_client.get_certificate(certificate_name="cert-name", logging_enable=True)

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 | |-------------|-------------| | hello_world.py (asynchrone Version) | Zertifikate erstellen/abrufen/aktualisieren/löschen | | backup_restore_operations.py (asynchrone Version) | Sichern und Wiederherstellen von Zertifikaten | | import_certificate.py (asynchrone Version) | Importieren von PKCS#12 (PFX) und PEM-formatierten Zertifikaten in Key Vault | | list_operations.py (asynchrone Version) | Listenzertifikate | | recover_purge_operations.py (asynchrone Version) | Wiederherstellen und Bereinigen von Zertifikaten | | issuers.py (asynchrone Version) | Verwalten von Zertifikatausstellern | | contacts.py (asynchrone Version) | Verwalten von Zertifikatkontakten | | parse_certificate.py (asynchrone Version) | Extrahieren des privaten Schlüssels eines Zertifikats |

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.