Avvio rapido: Libreria client dei certificati di Azure Key Vault per PythonQuickstart: Azure Key Vault certificates client library for Python

Introduzione alla libreria client di Azure Key Vault per PythonGet started with the Azure Key Vault client library for Python. Seguire questi passaggi per installare il pacchetto e provare il codice di esempio per le attività di base.Follow the steps below to install the package and try out example code for basic tasks. Usando Key Vault per l'archiviazione dei certificati si evita di archiviarli nel codice, aumentando la sicurezza dell'app.By using Key Vault to store certificates, you avoid storing certificates in your code, which increases the security of your app.

Documentazione di riferimento delle API | Codice sorgente della libreria | Pacchetto (Indice dei pacchetti Python)API reference documentation | Library source code | Package (Python Package Index)

Configurare l'ambiente localeSet up your local environment

  1. Assicurarsi di avere un account Azure con una sottoscrizione attiva.Make sure you have an Azure account with an active subscription.

  2. Installare Python 2.7 o versione successiva oppure 3.5.3 o versione successiva.Install Python 2.7+ or 3.5.3+.

  3. Installare l'interfaccia della riga di comando di Azure.Install the Azure CLI.

  4. Seguire le istruzioni riportate in Configurare l'autenticazione per lo sviluppo locale, con cui si crea un'entità servizio locale e la si rende disponibile al client Azure Key Vault per Python tramite variabili di ambiente.Follow the instructions on Configure authentication for local development, with which you create a local service principal and make it available to the Azure Key Vault Client for Python through environment variables.

    Quando si esegue il codice direttamente in Azure, un'entità servizio separata non è necessaria se l'app usa l'identità gestita.When running code directly on Azure, a separate service principal is not needed if the app uses managed identity.

  5. 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 PythonIn a terminal or command prompt, create a suitable project folder, and then create and activate a Python virtual environment as described on Use Python virtual environments

  6. Installare la libreria di identità di Azure Active Directory:Install the Azure Active Directory identity library:

    pip install azure.identity
    
  1. Installare la libreria di certificati di Key Vault:Install the Key Vault certificates library:

    pip install azure-keyvault-certificates
    

Creare un gruppo di risorse e un insieme di credenziali delle chiaviCreate a resource group and key vault

  1. Usare il comando az group create per creare un gruppo di risorse:Use the az group create command to create a resource group:

    az group create --name KeyVault-PythonQS-rg --location eastus
    

    È possibile sostituire "eastus" con una località più vicina, se si preferisce.You can change "eastus" to a location nearer to you, if you prefer.

  2. Usare az keyvault create per creare l'insieme di credenziali delle chiavi:Use az keyvault create to create the key vault:

    az keyvault create --name <your-unique-keyvault-name> --resource-group KeyVault-PythonQS-rg
    

    Sostituire <your-unique-keyvault-name> con un nome univoco in tutto Azure.Replace <your-unique-keyvault-name> with a name that's unique across all of Azure. In genere si usa il nome personale o dell'azienda insieme ad altri numeri e identificatori.You typically use your personal or company name along with other numbers and identifiers.

  3. Creare una variabile di ambiente che fornisce il nome dell'insieme di credenziali delle chiavi al codice:Create an environment variable that supplies the name of the Key Vault to the code:

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

Concedere all'entità servizio l'accesso all'insieme di credenziali delle chiaviGive the service principal access to your key vault

Eseguire il comando az keyvault set-policy seguente per autorizzare le operazioni get, list e create nei certificati da parte dell'entità servizio.Run the following az keyvault set-policy command to authorize your service principal for get, list, and create operations on certificates.

az keyvault set-policy --name %KEY_VAULT_NAME% --spn %AZURE_CLIENT_ID% --resource-group KeyVault-PythonQS-rg --certificate-permissions delete get list create

Questo comando si basa sulle variabili di ambiente KEY_VAULT_NAME e AZURE_CLIENT_ID create nei passaggi precedenti.This command relies on the KEY_VAULT_NAME and AZURE_CLIENT_ID environment variables created in previous steps.

Per altre informazioni, vedere Assegnare un criterio di accesso - Interfaccia della riga di comandoFor more information, see Assign an access policy - CLI

Creare il codice di esempioCreate the sample code

La libreria client di Azure Key Vault per Python consente di gestire i certificati e le risorse correlate, come i segreti e le chiavi crittografiche.The Azure Key Vault client library for Python allows you to manage certificates and related assets such as secrets and cryptographic keys. L'esempio di codice seguente illustra come creare un client e come impostare, recuperare ed eliminare un segreto.The following code sample demonstrates how to create a client, set a secret, retrieve a secret, and delete a secret.

Creare un file denominato kv_certificates.py che contiene questo codice.Create a file named kv_certificates.py that contains this code.

import os
from azure.keyvault.certificates import CertificateClient, CertificatePolicy,CertificateContentType, WellKnownIssuerNames 
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 codiceRun the code

Assicurarsi che il codice della sezione precedente sia incluso in un file denominato kv_certificates.py.Make sure the code in the previous section is in a file named kv_certificates.py. Eseguire quindi il codice con il comando seguente:Then run the code with the following command:

python kv_certificates.py
  • Se si verificano errori relativi alle autorizzazioni, assicurarsi d i aver eseguito il comando az keyvault set-policy.If you encounter permissions errors, make sure you ran the az keyvault set-policy command.
  • Se il codice viene eseguito di nuovo con lo stesso nome della chiave si potrebbe verificare un errore con un messaggio analogo a "(Conflitto) Il certificato si trova attualmente in uno stato eliminato ma recuperabile".Re-running the code with the same key name may produce the error, "(Conflict) Certificate is currently in a deleted but recoverable state." Usare un nome di chiave diverso.Use a different key name.

Dettagli del codiceCode details

Autenticare e creare un clientAuthenticate and create a client

Nel codice precedente l'oggetto DefaultAzureCredential usa le variabili di ambiente create per l'entità servizio.In the preceding code, the DefaultAzureCredential object uses the environment variables you created for your service principal. Queste credenziali vengono fornite ogni volta che si crea un oggetto client da una libreria di Azure, ad esempio CertificateClient, insieme all'URI della risorsa da usare tramite il client:You provide this credential whenever you create a client object from an Azure library, such as CertificateClient, along with the URI of the resource you want to work with through that client:

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

Salvare un certificatoSave a certificate

Una volta ottenuto l'oggetto client per l'insieme di credenziali delle chiavi, è possibile creare un certificato usando il metodo begin_create_certificate:Once you've obtained the client object for the key vault, you can create a certificate using the begin_create_certificate method:

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.Here, the certificate requires a policy obtained with the CertificatePolicy.get_default method.

La chiamata a un metodo begin_create_certificate genera una chiamata asincrona all'API REST di Azure per l'insieme di credenziali delle chiavi.Calling a begin_create_certificate method generates an asynchronous call to the Azure REST API for the key vault. La chiamata asincrona restituisce un oggetto poller.The asynchronous call returns a poller object. Per attendere il risultato dell'operazione, chiamare il metodo result dell'oggetto poller.To wait for the result of the operation, call the poller's result method.

Durante la gestione della richiesta, Azure autentica l'identità del chiamante (l'entità servizio) usando l'oggetto credenziali fornito al client.When handling the request, Azure authenticates the caller's identity (the service principal) using the credential object you provided to the client.

Verifica inoltre che il chiamante sia autorizzato a eseguire l'azione richiesta.It also checks that the caller is authorized to perform the requested action. Questa autorizzazione è stata concessa all'entità servizio in precedenza usando il comando az keyvault set-policy.You granted this authorization to the service principal earlier using the az keyvault set-policy command.

Recuperare un certificatoRetrieve a certificate

Per leggere un certificato da Key Vault, usare il metodo get_certificate:To read a certificate from Key Vault, use the get_certificate method:

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.You can also verify that the certificate has been set with the Azure CLI command az keyvault certificate show.

Eliminare un certificatoDelete a certificate

Per eliminare un certificato, usare il metodo begin_delete_certificate:To delete a certificate, use the begin_delete_certificate method:

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

Il begin_delete_certificate metodo è asincrono e restituisce un oggetto poller.The begin_delete_certificate method is asynchronous and returns a poller object. La chiamata al metodo result dell'oggetto poller attende il relativo completamento.Calling the poller's result method waits for its completion.

È possibile verificare che il certificato sia stato eliminato con il comando az keyvault certificate show dell'interfaccia della riga di comando di Azure.You can verify that the certificate is deleted with the Azure CLI command az keyvault certificate show.

Una volta eliminato, un certificato rimane in uno stato eliminato ma recuperabile per un periodo di tempo.Once deleted, a certificate remains in a deleted but recoverable state for a time. Se si esegue di nuovo il codice, usare un nome di certificato diverso.If you run the code again, use a different certificate name.

Pulire le risorseClean up resources

Se si vuole sperimentare anche con segreti e chiavi, è possibile riutilizzare l'istanza di Key Vault creata in questo articolo.If you want to also experiment with secrets and keys, you can reuse the Key Vault created in this article.

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:Otherwise, when you're finished with the resources created in this article, use the following command to delete the resource group and all its contained resources:

az group delete --resource-group KeyVault-PythonQS-rg

Passaggi successiviNext steps