Bibliothèque de client Azure Key Vault Certificates pour Python - version 4.7.0

Prise en main

Installer le package

Installez azure-keyvault-certificates et azure-identity avec pip :

pip install azure-keyvault-certificates azure-identity

azure-identity est utilisé pour l’authentification Azure Active Directory, comme illustré ci-dessous.

Prérequis

• Un abonnement Azure
• Python 3.7 ou version ultérieure
• Un Key Vault Azure existant. Si vous devez en créer un, vous pouvez le faire à l’aide d’Azure CLI en suivant les étapes décrites dans ce document.

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous avez besoin d’une instance d’un CertificateClient, ainsi que d’une URL de coffre et d’un objet d’informations d’identification. Ce document illustre l’utilisation d’une valeur DefaultAzureCredential, qui convient à la plupart des scénarios, y compris les environnements de développement et de production locaux. Nous vous recommandons d’utiliser une identité managée pour l’authentification dans les environnements de production.

Consultez la documentation azure-identity pour plus d’informations sur les autres méthodes d’authentification et leurs types d’informations d’identification correspondants.

Créer un client

Après avoir configuré votre environnement pour que DefaultAzureCredential utilise une méthode d’authentification appropriée, vous pouvez effectuer les opérations suivantes pour créer un client de certificat (en remplaçant la valeur de VAULT_URL par l’URL de votre coffre) :

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

NOTE: Pour un client asynchrone, importez azure.keyvault.certificates.aioà la CertificateClient place.

Concepts clés

CertificateClient

Avec un CertificateClient , vous pouvez obtenir des certificats à partir du coffre, créer de nouveaux certificats et de nouvelles versions de certificats existants, mettre à jour les métadonnées de certificat et supprimer des certificats. Vous pouvez également gérer les émetteurs de certificats, les contacts et les stratégies de gestion des certificats. Cela est illustré dans les exemples ci-dessous.

Exemples

Cette section contient des extraits de code couvrant les tâches courantes :

• Créer un certificat
• Récupérer un certificat
• Mettre à jour les propriétés d’un certificat existant
• Supprimer un certificat
• Répertorier les propriétés des certificats
• Opérations asynchrones
• Créer un certificat de manière asynchrone
• Répertorier de manière asynchrone les propriétés des certificats

Créer un certificat

begin_create_certificate crée un certificat à stocker dans le Key Vault Azure. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée. Avant de créer un certificat, vous pouvez créer une stratégie de gestion pour le certificat ou utiliser notre stratégie par défaut. Cette méthode retourne un pollueur d’opérations de longue durée.

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())

Si vous souhaitez vérifier l’état de la création de votre certificat, vous pouvez appeler status() sur l’polleur ou get_certificate_operation avec le nom du certificat.

Récupérer un certificat

get_certificate récupère la dernière version d’un certificat précédemment stocké dans le Key Vault.

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 récupère une version spécifique d’un certificat.

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)

Mettre à jour les propriétés d’un certificat existant

update_certificate_properties met à jour un certificat précédemment stocké dans le Key Vault.

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)

Supprimer un certificat

begin_delete_certificate demande Key Vault supprimer un certificat, en retournant un pollur qui vous permet d’attendre la fin de la suppression. L’attente est utile lorsque la suppression réversible est activée dans le coffre et que vous souhaitez vider (supprimer définitivement) le certificat dès que possible. Lorsque la suppression réversible est désactivée, begin_delete_certificate elle-même est permanente.

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)

Répertorier les propriétés des certificats

list_properties_of_certificates répertorie les propriétés de tous les certificats dans le Key Vault spécifié.

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)

Opérations asynchrones

Cette bibliothèque inclut un ensemble complet d’API asynchrones. Pour les utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les clients et les informations d’identification asynchrones doivent être fermés lorsqu’ils ne sont plus nécessaires. Ces objets sont des gestionnaires de contexte asynchrones et définissent des méthodes asynchrones close . Par exemple :

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:
    ...

Créer un certificat de manière asynchrone

create_certificate crée un certificat à stocker dans le Key Vault Azure. Si un certificat portant le même nom existe déjà, une nouvelle version du certificat est créée. Avant de créer un certificat, vous pouvez créer une stratégie de gestion pour le certificat ou utiliser notre stratégie par défaut. L’attente create_certificate retourne votre certificat créé si la création réussit, et un CertificateOperation si ce n’est pas le cas.

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)

Répertorier de manière asynchrone les propriétés des certificats

list_properties_of_certificates répertorie toutes les propriétés des certificats dans le coffre du client :

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)

Dépannage

Consultez le azure-keyvault-certificatesguide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Général

Key Vault clients déclenchent des exceptions définies dans azure-core. Par exemple, si vous essayez d’obtenir une clé qui n’existe pas dans le coffre, CertificateClient déclenche ResourceNotFoundError :

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)

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable :

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
)

La journalisation des traces réseau peut également être activée pour n’importe quelle opération unique :

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

Étapes suivantes

Plusieurs exemples sont disponibles dans le référentiel GitHub du Kit de développement logiciel (SDK) Azure pour Python. Ces exemples fournissent un exemple de code pour des scénarios de Key Vault supplémentaires : | Fichier | Description | |-------------|-------------| | hello_world.py (version asynchrone) | créer/obtenir/mettre à jour/supprimer des certificats | | backup_restore_operations.py (version asynchrone) | sauvegarder et récupérer des certificats | | import_certificate.py (version asynchrone) | importer des certificats au format PKCS#12 (PFX) et PEM dans Key Vault | | list_operations.py (version asynchrone) | répertorier les certificats | | recover_purge_operations.py (version asynchrone) | récupérer et vider des certificats | | issuers.py (version asynchrone) | gérer les émetteurs de certificats | | contacts.py (version asynchrone) | gérer les contacts de certificat | | parse_certificate.py (version asynchrone) | extraire la clé privée d’un certificat |

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Key Vault, consultez la documentation de référence sur les API.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.