Condividi tramite

Avvio rapido: Libreria client dei certificati di Azure Key Vault per Python

  • Articolo

Introduzione alla libreria client dei certificati di Azure Key Vault per Python. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base. Usando Key Vault per l'archiviazione dei certificati si evita di archiviarli nel codice, aumentando la sicurezza dell'app.

Documentazione di riferimento delle API | Codice sorgente della libreria | Pacchetto (Indice dei pacchetti Python)

Prerequisiti

Questa guida di avvio rapido presuppone che sia in esecuzione l'interfaccia della riga di comando di Azure o Azure PowerShell in una finestra del terminale Linux.

Configurare l'ambiente locale

Questa guida di avvio rapido usa la libreria di identità di Azure con l'interfaccia della riga di comando di Azure o Azure PowerShell per autenticare l'utente nei servizi di Azure. Gli sviluppatori possono anche usare Visual Studio o Visual Studio Code per autenticare le chiamate. Per altre informazioni, vedere Autenticare il client con la libreria client di identità di Azure.

Accedere ad Azure

  1. Eseguire il comando login.

    az login

    Se l'interfaccia della riga di comando può aprire il browser predefinito, eseguirà questa operazione e caricherà una pagina di accesso di Azure.

    In caso contrario, aprire una pagina del browser all'indirizzo https://aka.ms/devicelogin e immettere il codice di autorizzazione visualizzato nel terminale.

  2. Accedere con le credenziali dell'account nel browser.

Installare i pacchetti

  1. In un terminale o un prompt dei comandi creare una cartella di progetto appropriata e quindi creare e attivare un ambiente virtuale Python come descritto in Usare ambienti virtuali Python

  2. Installare la libreria di identità di Microsoft Entra:

    pip install azure.identity

  3. Installare la libreria client dei certificati di Key Vault:

    pip install azure-keyvault-certificates

Creare un gruppo di risorse e un insieme di credenziali delle chiavi

  1. Usare il comando az group create per creare un gruppo di risorse:

    az group create --name myResourceGroup --location eastus

    È possibile sostituire "eastus" con una località più vicina, se si preferisce.

  2. Usare az keyvault create per creare l'insieme di credenziali delle chiavi:

    az keyvault create --name <your-unique-keyvault-name> --resource-group myResourceGroup

    Sostituire <your-unique-keyvault-name> con un nome univoco in tutto Azure. In genere si usa il nome personale o dell'azienda insieme ad altri numeri e identificatori.

Impostare la variabile di ambiente KEY_VAULT_NAME

Lo script userà il valore assegnato alla variabile di ambiente KEY_VAULT_NAME come nome dell'istanza di Key Vault. È quindi necessario impostare questo valore usando il comando seguente:

export KEY_VAULT_NAME=<your-unique-keyvault-name>

Concedere l'accesso all'insieme di credenziali delle chiavi

Per ottenere le autorizzazioni per l’insieme di credenziali delle chiavi tramite il controllo degli accessi in base al ruolo (RBAC), assegnare un ruolo all’UPN (User Principal Name) usando il comando dell’interfaccia della riga di comando di Azure az role assignment create.

az role assignment create --role "Key Vault Certificate Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Sostituire <upn>, <subscription-id>, <resource-group-name> e <your-unique-keyvault-name> con i valori effettivi. L'UPN in genere sarà nel formato di un indirizzo e-mail (ad esempio, username@domain.com).

Creare il codice di esempio

La libreria client dei certificati di Azure Key Vault per Python consente di gestire i certificati. L'esempio di codice seguente mostra come creare un client e come impostare, recuperare ed eliminare un certificato.

Creare un file denominato kv_certificates.py che contiene questo codice.

import os
from azure.keyvault.certificates import CertificateClient, CertificatePolicy
from azure.identity import DefaultAzureCredential

keyVaultName = os.environ["KEY_VAULT_NAME"]
KVUri = "https://" + keyVaultName + ".vault.azure.net"

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

certificateName = input("Input a name for your certificate > ")

print(f"Creating a certificate in {keyVaultName} called '{certificateName}' ...")

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

print(" done.")

print(f"Retrieving your certificate from {keyVaultName}.")

retrieved_certificate = client.get_certificate(certificateName)

print(f"Certificate with name '{retrieved_certificate.name}' was found'.")
print(f"Deleting your certificate from {keyVaultName} ...")

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

print(" done.")

Eseguire il codice

Assicurarsi che il codice della sezione precedente sia incluso in un file denominato kv_certificates.py. Eseguire quindi il codice con il comando seguente:

python kv_certificates.py
  • Se si verificano errori relativi alle autorizzazioni, assicurarsi di aver eseguito il comando az keyvault set-policy o Set-AzKeyVaultAccessPolicy.
  • Se il codice viene eseguito di nuovo con lo stesso nome della chiave si potrebbe verificare un errore con un messaggio simile a "(Conflitto) Il certificato <nome> si trova attualmente in uno stato eliminato ma recuperabile". Usare un nome di chiave diverso.

Dettagli del codice

Autenticare e creare un client

Le richieste dell'applicazione per la maggior parte dei servizi di Azure devono essere autorizzate. L'uso della classe DefaultAzureCredential fornita dalla libreria client di identità di Azure è l'approccio consigliato per l'implementazione di connessioni senza password ai servizi di Azure nel codice. DefaultAzureCredential supporta più metodi di autenticazione e determina il metodo da usare in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e di produzione) senza implementare codice specifico dell'ambiente.

In questo avvio rapido, DefaultAzureCredential esegue l'autenticazione nell’insieme di credenziali delle chiavi usando le credenziali dell'utente di sviluppo locale connesso all'interfaccia della riga di comando di Azure. Quando l'applicazione viene distribuita in Azure, lo stesso codice DefaultAzureCredential può individuare e usare automaticamente un'identità gestita assegnata a un servizio app, a una macchina virtuale o ad altri servizi. Per altre informazioni, vedere Panoramica delle identità gestite.

Nel codice di esempio, il nome dell'istanza di Key Vault viene espanso nel relativo URI, nel formato https://\<your-key-vault-name>.vault.azure.net.

credential = DefaultAzureCredential()
client = CertificateClient(vault_url=KVUri, credential=credential)

Salvare un certificato

Una volta ottenuto l'oggetto client per l'insieme di credenziali delle chiavi, è possibile creare un certificato usando il metodo begin_create_certificate:

policy = CertificatePolicy.get_default()
poller = client.begin_create_certificate(certificate_name=certificateName, policy=policy)
certificate = poller.result()

In questo caso, il certificato richiede un criterio ottenuto con il metodo CertificatePolicy.get_default.

La chiamata a un metodo begin_create_certificate genera una chiamata asincrona all'API REST di Azure per l'insieme di credenziali delle chiavi. La chiamata asincrona restituisce un oggetto poller. Per attendere il risultato dell'operazione, chiamare il metodo result dell'oggetto poller.

Quando Azure gestisce la richiesta, autentica l'identità del chiamante (l'entità servizio) usando l'oggetto credenziali fornito al client.

Recuperare un certificato

Per leggere un certificato da Key Vault, usare il metodo get_certificate:

retrieved_certificate = client.get_certificate(certificateName)

È anche possibile verificare che il certificato sia stato impostato con il comando az keyvault certificate show dell'interfaccia della riga di comando di Azure o il cmdlet Get-AzKeyVaultCertificate di Azure PowerShell

Eliminare un certificato

Per eliminare un certificato, usare il metodo begin_delete_certificate:

poller = client.begin_delete_certificate(certificateName)
deleted_certificate = poller.result()

Il begin_delete_certificate metodo è asincrono e restituisce un oggetto poller. La chiamata al metodo result dell'oggetto poller attende il relativo completamento.

È possibile verificare che il certificato sia stato eliminato con il comando az keyvault certificate show dell'interfaccia della riga di comando di Azure o il cmdlet Get-AzKeyVaultCertificate di Azure PowerShell.

Una volta eliminato, un certificato rimane in uno stato eliminato ma recuperabile per un periodo di tempo. Se si esegue di nuovo il codice, usare un nome di certificato diverso.

Pulire le risorse

Se si vuole sperimentare anche con segreti e chiavi, è possibile riutilizzare l'istanza di Key Vault creata in questo articolo.

In caso contrario, dopo aver finito di usare le risorse create nell'articolo, eseguire il comando seguente per eliminare il gruppo di risorse e tutte le risorse contenute al suo interno:

az group delete --resource-group myResourceGroup

Passaggi successivi