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

Articolo
10/05/2024

Introduzione alla libreria client di chiavi di Azure Key Vault per .NET. Azure Key Vault è un servizio cloud che offre un archivio sicuro per le chiavi crittografiche. È possibile archiviare in modo sicuro chiavi crittografiche, 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 chiavi da Azure Key Vault usando la libreria client di chiavi per .NET

Risorse per la libreria client di chiavi di Key Vault:

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

Per altre informazioni su Key Vault e sulle chiavi, vedere:

Prerequisiti

Sottoscrizione di Azure: creare un account gratuitamente
.NET 6 SDK o versioni successive
Interfaccia della riga di comando di Azure
Un'istanza di Key Vault: è possibile crearne una con il portale di Azure, l'interfaccia della riga di comando di Azure o Azure PowerShell.

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

Impostazione

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.

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.
Accedere con le credenziali dell'account nel browser.

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 Crypto 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 una nuova app console .NET

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
```
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 chiavi di Azure Key Vault per .NET:

dotnet add package Azure.Security.KeyVault.Keys

Per questo argomento di avvio rapido è 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.

Finestre

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 chiavi di Azure Key Vault per .NET consente di gestire le chiavi. La sezione Esempi di codice illustra come creare un client e come impostare, recuperare ed eliminare una chiave.

Esempi di codice

Aggiungere le direttive

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

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

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.

In questo esempio, il nome dell'istanza dell’insieme di credenziali delle chiavi viene espanso nel relativo URI, 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.

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

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

Salvare una chiave

Per questa attività, usare il metodo CreateKeyAsync. I parametri del metodo accettano un nome di chiave e il tipo di chiave.

var key = await client.CreateKeyAsync("myKey", KeyType.Rsa);

Nota

Se il nome della chiave esiste, questo codice ne creerà una nuova versione.

Recuperare una chiave

È ora possibile recuperare la chiave creata in precedenza con il metodo GetKeyAsync.

var key = await client.GetKeyAsync("myKey");

Eliminare una chiave

Infine, eliminare e rimuovere definitivamente la chiave dall'insieme di credenziali delle chiavi con i metodi StartDeleteKeyAsync e PurgeDeletedKeyAsync.

var operation = await client.StartDeleteKeyAsync("myKey");

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

var key = operation.Value;
await client.PurgeDeletedKeyAsync("myKey");

Codice di esempio

Modificare l'app console .NET per interagire con l'insieme di credenziali delle chiavi seguendo questa procedura:

Sostituire il codice nel file Program.cs con il codice seguente:

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

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

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

            Console.Write($"Creating a key in {keyVaultName} called '{keyName}' ...");
            var createdKey = await client.CreateKeyAsync(keyName, KeyType.Rsa);
            Console.WriteLine("done.");

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

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

            Console.Write($"Purging your key from {keyVaultName} ...");
            await client.PurgeDeletedKeyAsync(keyName);
            Console.WriteLine(" done.");
        }
    }
}

Test e verifica

Eseguire il comando seguente per creare il progetto
```
dotnet build
```
Eseguire il comando seguente per eseguire l'app.
```
dotnet run
```

Quando richiesto, immettere un valore di un segreto. Ad esempio, mySecretPassword.

Compare una variante dell'output seguente:

Creating a key in mykeyvault called 'myKey' ... done.
Retrieving your key from mykeyvault.
Your key version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your key from jl-kv ... done
Purging your key from <your-unique-keyvault-name> ... done.

Passaggi successivi

In questo argomento di avvio rapido è stato creato un insieme di credenziali delle chiavi e quindi è stata archiviata e recuperata una chiave.

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

Leggere una panoramica di Azure Key Vault
Vedere una panoramica delle chiavi
Seguire un'esercitazione sull'accesso a Key Vault da un'applicazione del servizio app
Seguire un'esercitazione sull'accesso a Key Vault da una macchina virtuale
Vedere la Guida per gli sviluppatori per Azure Key Vault
Vedere Panoramica della sicurezza di Key Vault

Condividi tramite

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

Prerequisiti

Impostazione

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare una nuova app console .NET

Installare i pacchetti

Impostare le variabili di ambiente

Modello a oggetti

Esempi di codice

Aggiungere le direttive

Autenticare e creare un client

Salvare una chiave

Recuperare una chiave

Eliminare una chiave

Codice di esempio

Test e verifica

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

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

Prerequisiti

Impostazione

Accedere ad Azure

Concedere l'accesso all'insieme di credenziali delle chiavi

Creare una nuova app console .NET

Installare i pacchetti

Impostare le variabili di ambiente

Modello a oggetti

Esempi di codice

Aggiungere le direttive

Autenticare e creare un client

Salvare una chiave

Recuperare una chiave

Eliminare una chiave

Codice di esempio

Test e verifica

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive