Bibliothèque de client Azure Key Vault Keys pour Python - version 4.8.0
Azure Key Vault aide à résoudre les problèmes suivants :
- Gestion des clés de chiffrement (cette bibliothèque) : créer, stocker et contrôler l’accès aux clés utilisées pour chiffrer vos données
- Gestion des secrets (azure-keyvault-secrets) : stocker et contrôler en toute sécurité l’accès aux jetons, mots de passe, certificats, clés API et autres secrets
- Gestion des certificats (azure-keyvault-certificates) : créer, gérer et déployer des certificats SSL/TLS publics et privés
- Administration du coffre (azure-keyvault-administration) : contrôle d’accès en fonction du rôle (RBAC) et options de sauvegarde et de restauration au niveau du coffre
| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | API | Documentation produitÉchantillons
Clause d’exclusion de responsabilité
La prise en charge des packages Python du SDK Azure pour Python 2.7 a pris fin le 1er janvier 2022. Pour obtenir plus d’informations et poser des questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691.
Python 3.7 ou version ultérieure est requis pour utiliser ce package. Pour plus d’informations, reportez-vous à la stratégie de prise en charge des versions du Kit de développement logiciel (SDK) Azure pour Python.
Prise en main
Installer le package
Installez azure-keyvault-keys et azure-identity avec pip :
pip install azure-keyvault-keys 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.
- Si vous utilisez un HSM managé, un HSM managé Key Vault existant. Si vous devez créer un HSM managé, 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 KeyClient, 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 clé (en remplaçant la valeur de VAULT_URL par l’URL de votre coffre) :
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = KeyClient(vault_url=VAULT_URL, credential=credential)
NOTE: Pour un client asynchrone, importez
azure.keyvault.keys.aioà laKeyClientplace.
Concepts clés
Touches
Azure Key Vault pouvez créer et stocker des clés rsa et de courbe elliptique. Les deux peuvent éventuellement être protégés par des modules de sécurité matériels (HSM). Azure Key Vault peuvent également effectuer des opérations de chiffrement avec eux. Pour plus d’informations sur les clés et les opérations et algorithmes pris en charge, consultez la documentation Key Vault.
KeyClient peut créer des clés dans le coffre, obtenir des clés existantes à partir du coffre, mettre à jour les métadonnées de clé et supprimer des clés, comme indiqué dans les exemples ci-dessous.
Exemples
Cette section contient des extraits de code couvrant les tâches courantes :
- Création d’une clé
- Récupérer une clé
- Mettre à jour une clé existante
- Suppression d’une clé
- Configurer la rotation automatique des clés
- Afficher la liste des clés
- Effectuer des opérations de chiffrement
- API asynchrone
- Créer une clé de manière asynchrone
- Lister les clés de manière asynchrone
Créer une clé
create_rsa_key et create_ec_key créer des clés de courbes RSA et elliptique dans le coffre, respectivement. Si une clé portant le même nom existe déjà, une nouvelle version de cette clé est créée.
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)
Récupérer une clé
get_key récupère une clé précédemment stockée dans le coffre.
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)
Mettre à jour une clé existante
update_key_properties met à jour les propriétés d’une clé précédemment stockée dans le Key Vault.
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)
Supprimer une clé
begin_delete_key demande Key Vault supprimer une clé, en retournant un pollneur 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) la clé dès que possible. Lorsque la suppression réversible est désactivée, begin_delete_key elle-même est permanente.
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)
Configurer la rotation automatique des clés
update_key_rotation_policy vous permet de configurer la rotation automatique des clés pour une clé en spécifiant une stratégie de rotation. En outre, rotate_key vous permet de faire pivoter une clé à la demande en créant une nouvelle version de la clé donnée.
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")
Afficher la liste des clés
list_properties_of_keys répertorie les propriétés de toutes les clés dans le coffre du client.
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)
Opérations de chiffrement
CryptographyClient active les opérations de chiffrement (chiffre/déchiffrement, wrap/unwrap, sign/verify) à l’aide d’une clé particulière.
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)
Pour plus d’informations sur l’API de chiffrement, consultez la documentation du package .
API asynchrone
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.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:
...
Créer une clé de manière asynchrone
create_rsa_key et create_ec_key créer des clés de courbes RSA et elliptique dans le coffre, respectivement. Si une clé portant le même nom existe déjà, une nouvelle version de la clé est créée.
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)
Lister les clés de manière asynchrone
list_properties_of_keys répertorie les propriétés de toutes les clés dans le coffre du client.
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)
Dépannage
Consultez le azure-keyvault-keysguide 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, KeyClient déclenche ResourceNotFoundError :
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)
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.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)
De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :
client.get_key("my-key", 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.
Ceux-ci 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 clés | | list_operations.py (version asynchrone) | opérations de liste de base pour les clés | | backup_restore_operations.py (version asynchrone) | sauvegarder et récupérer des clés | | recover_purge_operations.py (version asynchrone) | récupérer et vider les clés | | send_request.py | utiliser la send_request méthode cliente |
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.
Azure SDK for Python