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

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à la SecretClient place.

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.