Bibliothèque de client Azure Key Vault Administration pour Python - version 4.3.0

  • Article

Note: La bibliothèque d’administration fonctionne uniquement avec le HSM managé : les fonctions ciblant un Key Vault échouent.

Azure Key Vault aide à résoudre les problèmes suivants :

  • Administration du coffre (cette bibliothèque) : contrôle d’accès en fonction du rôle (RBAC) et options de sauvegarde et de restauration au niveau du coffre
  • 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 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

| 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 plus d’informations et de questions, reportez-vous à https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 ou version ultérieure nécessaire 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-administration et azure-identity avec pip :

pip install azure-keyvault-administration azure-identity

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

Prérequis

Authentifier le client

Pour interagir avec le service Azure Key Vault, vous aurez besoin d’une instance d’un KeyVaultAccessControlClient ou d’un KeyVaultBackupClient, ainsi que d’une URL de coffre (que vous pouvez voir comme « Nom DNS » dans le portail Azure) et d’un objet d’informations d’identification. Ce document illustre l’utilisation d’un defaultAzureCredential, qui convient à la plupart des scénarios, y compris aux 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 KeyVaultAccessControlClient

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 contrôle d’accès (en remplaçant la valeur de par l’URL de vault_url votre HSM managé) :

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTE: Pour un client asynchrone, importez azure.keyvault.administration.aioà la KeyVaultAccessControlClient place.

Créer un KeyVaultBackupClient

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 sauvegarde (en remplaçant la valeur de par l’URL de vault_url votre HSM managé) :

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTE: Pour un client asynchrone, importez azure.keyvault.administration.aioà la KeyVaultBackupClient place.

Créer un KeyVaultSettingsClient

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 paramètres (en remplaçant la valeur de par l’URL de vault_url votre HSM managé) :

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

credential = DefaultAzureCredential()

client = KeyVaultSettingsClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOTE: Pour un client asynchrone, importez azure.keyvault.administration.aioà la KeyVaultSettingsClient place.

Concepts clés

Définition de rôle

Une définition de rôle définit les opérations qui peuvent être effectuées, telles que la lecture, l’écriture et la suppression. Il peut également définir les opérations qui sont exclues des opérations autorisées.

Une définition de rôle est spécifiée dans le cadre d’une attribution de rôle.

Attribution de rôle

Une attribution de rôle est l’association d’une définition de rôle à un principal de service. Ils peuvent être créés, répertoriés, extraits individuellement et supprimés.

KeyVaultAccessControlClient

Un KeyVaultAccessControlClient gère les définitions de rôles et les attributions de rôles.

KeyVaultBackupClient

A KeyVaultBackupClient effectue des sauvegardes de clés complètes, des restaurations de clés complètes et des restaurations de clés sélectives.

KeyVaultSettingsClient

Un KeyVaultSettingsClient gère les paramètres du compte HSM managé.

Exemples

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

Liste de toutes les définitions de rôles

Répertoriez les définitions de rôle disponibles pour l’affectation.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)

for definition in role_definitions:
    print(definition.id)
    print(definition.role_name)
    print(definition.description)

Définir, obtenir et supprimer une définition de rôle

set_role_definition peut être utilisé pour créer une définition de rôle personnalisée ou mettre à jour une définition existante avec le nom spécifié.

import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
    KeyVaultAccessControlClient,
    KeyVaultDataAction,
    KeyVaultPermission,
    KeyVaultRoleScope
)

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)

# update the custom role definition
permissions = [
    KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)

# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

Répertorie toutes les affectations de rôle

Avant de créer une attribution de rôle dans l’extrait de code suivant, répertoriez toutes les attributions de rôle actuelles :

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)

for assignment in role_assignments:
    print(assignment.name)
    print(assignment.principal_id)
    print(assignment.role_definition_id)

Créer, obtenir et supprimer une attribution de rôle

Attribuez un rôle à un principal de service. Cela nécessite un ID de définition de rôle et un ID d’objet de principal de service. Vous pouvez utiliser un ID de la liste récupérée des définitions de rôle pour la première et une affectation de la liste récupérée dans l’extrait principal_idde code ci-dessus pour la seconde.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"

# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

Effectuer une sauvegarde de clé complète

Sauvegardez l’ensemble de votre collection de clés. Le magasin de stockage pour les sauvegardes à clé complète est un conteneur de stockage d’objets blob utilisant l’authentification par signature d’accès partagé.

Pour plus d’informations sur la création d’un jeton SAS à l’aide de BlobServiceClient, consultez l’exemple ici. Vous pouvez également générer un jeton SAP dans Explorateur Stockage

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()

# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)

Effectuer une restauration de clé complète

Restaurez l’ensemble de votre collection de clés à partir d’une sauvegarde. La source de données d’une restauration de clé complète est un objet blob de stockage accessible à l’aide de l’authentification par signature d’accès partagé. Vous aurez également besoin de l’extrait azure_storage_blob_container_uri de code ci-dessus.

Pour plus d’informations sur la création d’un jeton SAS à l’aide de BlobServiceClient, consultez l’exemple ici. Vous pouvez également générer un jeton SAP dans Explorateur Stockage

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"

# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()

Dépannage

Consultez le azure-keyvault-administrationguide 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 attribution de rôle qui n’existe pas, KeyVaultAccessControlClient lève ResourceNotFoundError :

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
    client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Les clients de la bibliothèque d’administration ne peuvent être utilisés que pour effectuer des opérations sur un HSM managé. Par conséquent, si vous essayez de le faire sur un Key Vault génère une erreur.

É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 | |-------------|-------------| | access_control_operations.py | créer/mettre à jour/supprimer des définitions de rôle et des attributions de rôles | | access_control_operations_async.py | créer/mettre à jour/supprimer des définitions de rôle et des attributions de rôles avec un client asynchrone | | backup_restore_operations.py | sauvegarde et restauration complètes | | | backup_restore_operations_async.py | sauvegarde et restauration complètes avec un client asynchrone | | settings_operations.py | répertorier et mettre à jour les paramètres de Key Vault | | settings_operations_async.py | répertorier et mettre à jour les paramètres Key Vault avec un client asynchrone |

Documentation complémentaire

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

Pour obtenir une documentation plus complète sur le HSM managé, consultez la documentation du service.

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.

Impressions