Guida introduttiva: Libreria client dei segreti di Azure Key Vault per .NET

Introduzione alla libreria client dei segreti di Azure Key Vault per .NET. Azure Key Vault è un servizio cloud che offre un archivio sicuro per i segreti. È 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 segreti 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 segreti, vedere:

Prerequisiti

Questa guida introduttiva usa e l'interfaccia dotnet della riga di comando di Azure o Azure PowerShell.

Attrezzaggio

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 az 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 il segreto all'account utente

az keyvault set-policy --name <YourKeyVaultName> --upn user@domain.com --secret-permissions delete get list set 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 dei segreti di Azure Key Vault per .NET:

dotnet add package Azure.Security.KeyVault.Secrets

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.

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

Esempi di codice

Aggiungere le direttive

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

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

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 questa guida introduttiva viene DefaultAzureCredential eseguita l'autenticazione in Key Vault 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, una macchina virtuale o 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 SecretClient(new Uri(kvUri), new DefaultAzureCredential());

Salvare un segreto

Una volta autenticata l'applicazione console, aggiungere un segreto all'insieme di credenziali delle chiavi. Per questa attività, usare il metodo SetSecretAsync.

Il primo parametro del metodo accetta un nome per il segreto. In questo esempio la variabile secretName archivia la stringa "mySecret".

Il secondo parametro del metodo accetta un valore per il segreto. In questo esempio il segreto viene immesso dall'utente tramite la riga di comando e archiviato nella variabile secretValue.

await client.SetSecretAsync(secretName, secretValue);

Nota

Se esiste un nome segreto, il codice creerà una nuova versione di tale segreto.

Recuperare un segreto

È ora possibile recuperare il valore impostato in precedenza con il metodo GetSecretAsync.

var secret = await client.GetSecretAsync(secretName);

Il segreto è ora salvato come secret.Value.

consente di eliminare un segreto

Eliminare infine il segreto dall'insieme di credenziali delle chiavi con i metodi StartDeleteSecretAsync e PurgeDeletedSecretAsync.

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

await client.PurgeDeletedSecretAsync(secretName);

Codice di esempio

Modificare l'app console .NET per interagire con Key Vault completando i passaggi seguenti:

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

    using System;
    using System.Threading.Tasks;
    using Azure.Identity;
    using Azure.Security.KeyVault.Secrets;
    
    namespace key_vault_console_app
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                const string secretName = "mySecret";
                var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
                var kvUri = $"https://{keyVaultName}.vault.azure.net";
    
                var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
    
                Console.Write("Input the value of your secret > ");
                var secretValue = Console.ReadLine();
    
                Console.Write($"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...");
                await client.SetSecretAsync(secretName, secretValue);
                Console.WriteLine(" done.");
    
                Console.WriteLine("Forgetting your secret.");
                secretValue = string.Empty;
                Console.WriteLine($"Your secret is '{secretValue}'.");
    
                Console.WriteLine($"Retrieving your secret from {keyVaultName}.");
                var secret = await client.GetSecretAsync(secretName);
                Console.WriteLine($"Your secret is '{secret.Value.Value}'.");
    
                Console.Write($"Deleting your secret from {keyVaultName} ...");
                DeleteSecretOperation operation = await client.StartDeleteSecretAsync(secretName);
                // You only need to wait for completion if you want to purge or recover the secret.
                await operation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.Write($"Purging your secret from {keyVaultName} ...");
                await client.PurgeDeletedSecretAsync(secretName);
                Console.WriteLine(" done.");
            }
        }
    }
    

Test e verifica

  1. Eseguire il comando seguente per eseguire l'app.

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

Compare una variante dell'output seguente:

Input the value of your secret > mySecretPassword
Creating a secret in <your-unique-keyvault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <your-unique-keyvault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <your-unique-keyvault-name> ... done.    
Purging your secret from <your-unique-keyvault-name> ... done.

Passaggi successivi

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