Avvio rapido: Libreria client del certificato di Azure Key Vault per .NET

  • Articolo

Introduzione alla libreria client di certificati di Azure Key Vault per .NET. Azure Key Vault è un servizio cloud che offre un archivio sicuro per i certificati. È possibile archiviare in modo sicuro chiavi, password, certificati e altri segreti. È possibile creare e gestire istanze di Azure Key Vault tramite il portale di Azure. Questa guida di avvio rapido descrive come creare, recuperare ed eliminare certificati da Azure Key Vault usando la libreria client .NET

Risorse per la libreria client di Key Vault:

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet)

Per altre informazioni su Key Vault e sui certificati, vedere:

Prerequisiti

In questo argomento di avvio rapido si usano dotnet e l'interfaccia della riga di comando di Azure

Configurazione

Questo argomento di avvio rapido usa la libreria di identità di Azure con l'interfaccia della riga di comando di Azure 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 Azure Identity.

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.

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che concede le autorizzazioni per i certificati all'account utente

az keyvault set-policy --name <your-key-vault-name> --upn user@domain.com --certificate-permissions delete get list create purge

Creare una nuova app console .NET

  1. In una shell dei comandi eseguire questo comando per creare un progetto denominato key-vault-console-app:

    dotnet new console --name key-vault-console-app

  2. Passare alla directory key-vault-console-app appena creata ed eseguire questo comando per compilare il progetto:

    dotnet build

    L'output di compilazione non deve contenere alcun avviso o errore.

    Build succeeded.
 0 Warning(s)
 0 Error(s)

Installare i pacchetti

Nella shell dei comandi installare la libreria client di certificati di Azure Key Vault per .NET:

dotnet add package Azure.Security.KeyVault.Certificates

Per questa guida introduttiva, è anche necessario installare la libreria client di Identità di Azure:

dotnet add package Azure.Identity

Impostare le variabili di ambiente

Questa applicazione usa il nome dell'insieme di credenziali delle chiavi come variabile di ambiente denominata KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS o Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Modello a oggetti

La libreria client di certificati di Azure Key Vault per .NET consente di gestire i certificati. La sezione Esempi di codice mostra come creare un client e come impostare, recuperare ed eliminare un certificato.

Esempi di codice

Aggiungere le direttive

Aggiungere le direttive seguenti all'inizio di Program.cs:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

Autenticare e creare un client

Le richieste di applicazione alla 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 implementare connessioni senza password ai servizi di Azure nel codice. DefaultAzureCredential supporta più metodi di autenticazione e determina quale metodo deve essere usato in fase di esecuzione. Questo approccio consente all'app di usare metodi di autenticazione diversi in ambienti diversi (locale e produzione) senza implementare codice specifico dell'ambiente.

In questa guida introduttiva DefaultAzureCredential l'autenticazione all'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 DefaultAzureCredential codice può individuare e usare automaticamente un'identità gestita assegnata a un servizio app, alla macchina virtuale o ad altri servizi. Per altre informazioni, vedere Panoramica delle identità gestite.

In questo esempio il nome dell'insieme di credenziali delle chiavi viene espanso all'URI dell'insieme di credenziali delle chiavi, nel formato https://<your-key-vault-name>.vault.azure.net. Per altre informazioni sull'autenticazione nell'insieme di credenziali delle chiavi, vedere la Guida per sviluppatori.

string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";

var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

Salvare un certificato

Per semplicità, in questo esempio è possibile usare un certificato autofirmato con il criterio di emissione predefinito. Per questa attività, usare il metodo StartCreateCertificateAsync. I parametri del metodo accettano un nome di certificato e il criterio del certificato.

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

Nota

Se il nome del certificato esiste, il codice precedente ne crea una nuova versione.

Recuperare un certificato

È ora possibile recuperare il certificato creato in precedenza con il metodo GetCertificateAsync.

var certificate = await client.GetCertificateAsync("myCertificate");

Eliminare un certificato

Infine, eliminare ed eliminare il certificato dall'insieme di credenziali delle chiavi con i metodi StartDeleteCertificateAsync e PurgeDeletedCertificateAsync .

var operation = await client.StartDeleteCertificateAsync("myCertificate");

// You only need to wait for completion if you want to purge or recover the certificate.
await operation.WaitForCompletionAsync();

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

Codice di esempio

Modificare l'app console .NET per interagire con la Key Vault completando la procedura seguente:

  • Sostituire il codice in Program.cs con il codice seguente:

    using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Certificates;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string certificateName = "myCertificate";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
            CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
            var certificate = await client.GetCertificateAsync(certificateName);
            Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");

            Console.Write($"Deleting your certificate from {keyVaultName} ...");
            DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
            // You only need to wait for completion if you want to purge or recover the certificate.
            await deleteOperation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your certificate from {keyVaultName} ...");
            await client.PurgeDeletedCertificateAsync(certificateName);
            Console.WriteLine(" done.");
        }
    }
}

Test e verifica

Eseguire il comando seguente per creare il progetto

dotnet build

Compare una variante dell'output seguente:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

Passaggi successivi

In questo argomento di avvio rapido è stato creato un insieme di credenziali delle chiavi e quindi è stato archiviato e recuperato un certificato.

Per altre informazioni su Key Vault e su come integrarlo nelle app, vedere gli articoli seguenti: