Bibliothèque de client Azure Key Vault Secrets pour Python - version 4.7.0
Azure Key Vault aide à résoudre les problèmes suivants :
- Gestion des secrets (cette bibliothèque) : 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 clés de chiffrement (azure-keyvault-keys) : créer, stocker et contrôler l’accès aux clés utilisées pour chiffrer vos données
- 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 des packages
Installez azure-keyvault-secrets et azure-identity avec pip :
pip install azure-keyvault-secrets 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 SecretClient, 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 secret (en remplaçant la valeur de VAULT_URL par l’URL de votre coffre) :
VAULT_URL = os.environ["VAULT_URL"]
credential = DefaultAzureCredential()
client = SecretClient(vault_url=VAULT_URL, credential=credential)
NOTE: Pour un client asynchrone, importez
azure.keyvault.secrets.aioà laSecretClientplace.
Concepts clés
Secret
Un secret se compose d’une valeur secrète et de ses métadonnées et informations de gestion associées. Cette bibliothèque gère les valeurs secrètes sous forme de chaînes, mais Azure Key Vault ne les stocke pas en tant que telles. Pour plus d’informations sur les secrets et la façon dont Key Vault les stocke et les gère, consultez la documentation Key Vault.
SecretClient peut définir des valeurs de secret dans le coffre, mettre à jour les métadonnées de secret et supprimer des secrets, comme illustré dans les exemples ci-dessous.
Exemples
Cette section contient des extraits de code couvrant les tâches courantes :
- Définir un secret
- Récupérer un secret
- Mettre à jour les métadonnées de secret
- Suppression d’une clé secrète
- Lister des secrets
- API asynchrone
- Créer un secret de manière asynchrone
- Répertorier les secrets de manière asynchrone
Définir un secret
set_secret crée de nouveaux secrets et modifie les valeurs des secrets existants. S’il n’existe aucun secret portant le nom donné, set_secret crée un nouveau secret avec ce nom et la valeur donnée. Si le nom donné est utilisé, set_secret crée une nouvelle version de ce secret, avec la valeur donnée.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
Récupérer un secret
get_secret récupère un secret précédemment stocké dans le Key Vault.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = secret_client.get_secret("secret-name")
print(secret.name)
print(secret.value)
Mettre à jour les métadonnées de secret
update_secret_properties met à jour les métadonnées d’un secret. Il ne peut pas modifier la valeur du secret ; utilisez set_secret pour définir la valeur d’un secret.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
# Clients may specify the content type of a secret to assist in interpreting the secret data when it's retrieved
content_type = "text/plain"
# We will also disable the secret for further use
updated_secret_properties = secret_client.update_secret_properties("secret-name", content_type=content_type, enabled=False)
print(updated_secret_properties.updated_on)
print(updated_secret_properties.content_type)
print(updated_secret_properties.enabled)
supprimer un secret
begin_delete_secret demande Key Vault supprimer un secret, 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 secret dès que possible. Lorsque la suppression réversible est désactivée, begin_delete_secret elle-même est permanente.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
deleted_secret = secret_client.begin_delete_secret("secret-name").result()
print(deleted_secret.name)
print(deleted_secret.deleted_date)
Afficher la liste des secrets
list_properties_of_secrets répertorie les propriétés de tous les secrets dans le coffre du client. Cette liste n’inclut pas les valeurs du secret.
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
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.secrets.aio import SecretClient
credential = DefaultAzureCredential()
# call close when the client and credential are no longer needed
client = SecretClient(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 = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
async with client:
async with credential:
...
Créer un secret de manière asynchrone
set_secret crée un secret dans le Key Vault avec les arguments facultatifs spécifiés.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret = await secret_client.set_secret("secret-name", "secret-value")
print(secret.name)
print(secret.value)
print(secret.properties.version)
Répertorier les secrets de manière asynchrone
list_properties_of_secrets répertorie les propriétés de tous les secrets dans le coffre du client.
from azure.identity.aio import DefaultAzureCredential
from azure.keyvault.secrets.aio import SecretClient
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
secret_properties = secret_client.list_properties_of_secrets()
async for secret_property in secret_properties:
# the list doesn't include values or versions of the secrets
print(secret_property.name)
Dépannage
Consultez le azure-keyvault-secretsguide 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, SecretClient déclenche ResourceNotFoundError :
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient
from azure.core.exceptions import ResourceNotFoundError
credential = DefaultAzureCredential()
secret_client = SecretClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
try:
secret_client.get_secret("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.secrets import SecretClient
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
secret_client = SecretClient(
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 :
secret_client.get_secret("my-secret", 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 secrets | | list_operations.py (version asynchrone) | opérations de liste de base pour les secrets | | backup_restore_operations.py (version asynchrone) | sauvegarder et restaurer des secrets | | recover_purge_operations.py (version asynchrone) | récupérer et vider les secrets |
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
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour