Libreria client di amministrazione di Azure Key Vault per Python - versione 4.3.0

Nota: La libreria di amministrazione funziona solo con il modulo di protezione hardware gestito: le funzioni destinate a un Key Vault avranno esito negativo.

Azure Key Vault contribuisce a risolvere i problemi seguenti:

• Amministrazione dell'insieme di credenziali (questa libreria): controllo degli accessi in base al ruolo e opzioni di backup e ripristino a livello di insieme di credenziali
• Gestione delle chiavi crittografiche (azure-keyvault-keys): creare, archiviare e controllare l'accesso alle chiavi usate per crittografare i dati
• Gestione dei segreti (azure-keyvault-secrets): archiviare e controllare in modo sicuro l'accesso a token, password, certificati, chiavi API e altri segreti
• Gestione dei certificati (azure-keyvault-certificates): creare, gestire e distribuire certificati SSL/TLS pubblici e privati

Codice | sorgente Pacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APIDocumentazione | del prodotto Campioni

Dichiarazione di non responsabilità

Il supporto dei pacchetti Python di Azure SDK per Python 2.7 è terminato il 01 gennaio 2022. Per altre informazioni e domande, vedere https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 o versione successiva per usare questo pacchetto. Per altre informazioni, vedere Criteri di supporto per la versione di Azure SDK per Python.

Introduzione

Installare i pacchetti

Installare azure-keyvault-administration e azure-identity con pip:

pip install azure-keyvault-administration azure-identity

azure-identity viene usato per l'autenticazione di Azure Active Directory, come illustrato di seguito.

Prerequisiti

• Una sottoscrizione di Azure
• Python 3.7 o versione successiva
• Un modulo di protezione hardware gestito Key Vault esistente. Se è necessario crearne uno, è possibile usare l'interfaccia della riga di comando di Azure seguendo la procedura descritta in questo documento.

Autenticare il client

Per interagire con il servizio Azure Key Vault, è necessaria un'istanza di KeyVaultAccessControlClient o KeyVaultBackupClient, nonché un URL dell'insieme di credenziali (che può essere visualizzato come "Nome DNS" nel portale di Azure) e un oggetto credenziale. Questo documento illustra l'uso di un oggetto DefaultAzureCredential, appropriato per la maggior parte degli scenari, inclusi gli ambienti di sviluppo e produzione locali. È consigliabile usare un'identità gestita per l'autenticazione negli ambienti di produzione.

Per altre informazioni su altri metodi di autenticazione e sui tipi di credenziali corrispondenti, vedere la documentazione di azure-identity .

Creare un KeyVaultAccessControlClient

Dopo aver configurato l'ambiente per DefaultAzureCredential per l'uso di un metodo di autenticazione appropriato, è possibile eseguire le operazioni seguenti per creare un client di controllo di accesso (sostituendo il valore di vault_url con l'URL del modulo di protezione hardware gestito):

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
)

NOTA: Per un client asincrono, importare azure.keyvault.administration.aioinvece .KeyVaultAccessControlClient

Creare un KeyVaultBackupClient

Dopo aver configurato l'ambiente per DefaultAzureCredential per l'uso di un metodo di autenticazione appropriato, è possibile eseguire le operazioni seguenti per creare un client di backup (sostituendo il valore di vault_url con l'URL del modulo di protezione hardware gestito):

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
)

NOTA: Per un client asincrono, importare azure.keyvault.administration.aioinvece .KeyVaultBackupClient

Creare un keyvaultSettingsClient

Dopo aver configurato l'ambiente per DefaultAzureCredential per l'uso di un metodo di autenticazione appropriato, è possibile eseguire le operazioni seguenti per creare un client di impostazioni (sostituendo il valore di vault_url con l'URL del modulo di protezione hardware gestito):

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
)

NOTA: Per un client asincrono, importare azure.keyvault.administration.aioinvece .KeyVaultSettingsClient

Concetti chiave

Definizione di ruolo

Una definizione di ruolo definisce le operazioni che è possibile eseguire, ad esempio lettura, scrittura ed eliminazione. Può anche definire le operazioni escluse dalle operazioni consentite.

Una definizione di ruolo viene specificata come parte di un'assegnazione di ruolo.

Assegnazione del ruolo

Un'assegnazione di ruolo è l'associazione di una definizione di ruolo a un'entità servizio. Possono essere creati, elencati, recuperati singolarmente ed eliminati.

KeyVaultAccessControlClient

Un KeyVaultAccessControlClient oggetto gestisce le definizioni dei ruoli e le assegnazioni di ruolo.

KeyVaultBackupClient

Un KeyVaultBackupClient esegue backup completi delle chiavi, ripristini completi della chiave e ripristini selettivi delle chiavi.

KeyVaultSettingsClient

Un KeyVaultSettingsClient oggetto gestisce le impostazioni dell'account HSM gestito.

Esempio

Questa sezione contiene frammenti di codice relativi alle attività comuni:

• Controllo di accesso
  • Elencare tutte le definizioni dei ruoli
  • Impostare, ottenere ed eliminare una definizione di ruolo
  • Elencare tutte le assegnazioni di ruolo
  • Creare, ottenere ed eliminare un'assegnazione di ruolo
• Backup e ripristino
  • Eseguire un backup completo della chiave
  • Eseguire un ripristino completo della chiave

Elencare tutte le definizioni dei ruoli

Elencare le definizioni di ruolo disponibili per l'assegnazione.

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)

Impostare, ottenere ed eliminare una definizione di ruolo

set_role_definition può essere usato per creare una definizione di ruolo personalizzata o aggiornare una definizione esistente con il nome specificato.

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)

Elencare tutte le assegnazioni di ruolo

Prima di creare una nuova assegnazione di ruolo nel frammento di codice successivo, elencare tutte le assegnazioni di ruolo correnti:

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)

Creare, ottenere ed eliminare un'assegnazione di ruolo

Assegnare un ruolo a un'entità servizio. Questo richiederà un ID definizione del ruolo e un ID oggetto entità servizio. È possibile usare un ID dall'elenco recuperato di definizioni di ruolo per il primo e un'assegnazione dall'elenco recuperato nel frammento di codice precedente per quest'ultimoprincipal_id.

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)

Eseguire un backup completo della chiave

Eseguire il backup dell'intera raccolta di chiavi. L'archivio di backup per i backup con chiave completa è un contenitore di archiviazione BLOB tramite l'autenticazione con firma di accesso condiviso.

Per altre informazioni sulla creazione di un token di firma di accesso condiviso con BlobServiceClient, vedere l'esempio qui. In alternativa, è possibile generare un token di firma di accesso condiviso in Storage Explorer

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)

Eseguire un ripristino completo della chiave

Ripristinare l'intera raccolta di chiavi da un backup. L'origine dati per un ripristino completo della chiave è un BLOB di archiviazione accessibile tramite l'autenticazione della firma di accesso condiviso. Sarà necessario anche dal azure_storage_blob_container_uriframmento di codice precedente.

Per altre informazioni sulla creazione di un token di firma di accesso condiviso con BlobServiceClient, vedere l'esempio qui. In alternativa, è possibile generare un token di firma di accesso condiviso in Storage Explorer

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

Risoluzione dei problemi

Per informazioni dettagliate su come diagnosticare vari scenari di errore, vedere la azure-keyvault-administrationguida alla risoluzione dei problemi .

Generale

Key Vault client generano eccezioni definite in azure-core. Ad esempio, se si tenta di ottenere un'assegnazione di ruolo che non esiste, KeyVaultAccessControlClient genera 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)

I client della libreria di amministrazione possono essere usati solo per eseguire operazioni su un modulo di protezione hardware gestito, quindi il tentativo di eseguire questa operazione in un Key Vault genererà un errore.

Passaggi successivi

Sono disponibili diversi esempi nel repository GitHub di Azure SDK per Python. Questi esempi forniscono codice di esempio per altri scenari di Key Vault: | File | Descrizione | |-------------|-------------| | access_control_operations.py | creare/aggiornare/eliminare definizioni di ruolo e assegnazioni di ruolo | | access_control_operations_async.py | creare/aggiornare/eliminare definizioni di ruolo e assegnazioni di ruolo con un client asincrono | | backup_restore_operations.py | backup e ripristino completi | | backup_restore_operations_async.py | backup completo e ripristino con un client asincrono | | settings_operations.py | elencare e aggiornare le impostazioni Key Vault | | settings_operations_async.py | elencare e aggiornare le impostazioni Key Vault con un client asincrono |

Documentazione aggiuntiva

Per una documentazione più completa su Azure Key Vault, vedere la documentazione di riferimento sulle API.

Per una documentazione più completa sul modulo di protezione hardware gestito, vedere la documentazione del servizio.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.