Avvio rapido: Libreria client di Azure Key Vault per .NET (SDK v4)Quickstart: Azure Key Vault client library for .NET (SDK v4)

Introduzione alla libreria client di Azure Key Vault per .NET.Get started with the Azure Key Vault client library for .NET. 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.

L'insieme di credenziali delle chiavi di Azure consente di proteggere le chiavi e i segreti di crittografia usati da servizi e applicazioni cloud.Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Usare la libreria client di Azure Key Vault per .NET per:Use the Key Vault client library for .NET to:

  • Aumentare la sicurezza e il controllo di chiavi e password.Increase security and control over keys and passwords.
  • Creare e importare chiavi di crittografia in pochi minuti.Create and import encryption keys in minutes.
  • Ridurre la latenza con ridondanza globale e su scala cloud.Reduce latency with cloud scale and global redundancy.
  • Semplificare e automatizzare le attività per i certificati TLS/SSL.Simplify and automate tasks for TLS/SSL certificates.
  • Usare moduli di protezione hardware convalidati in base agli standard FIPS 140-2 livello 2.Use FIPS 140-2 Level 2 validated HSMs.

Documentazione di riferimento dell'API | Codice sorgente della libreria | Pacchetto (NuGet)API reference documentation | Library source code | Package (NuGet)

PrerequisitiPrerequisites

Questo argomento di avvio rapido presuppone che si eseguano i comandi di dotnet, dell'interfaccia della riga di comando di Azure e di Windows in un terminale di Windows, ad esempio PowerShell Core, Windows PowerShell o Azure Cloud Shell.This quickstart assumes you are running dotnet, Azure CLI, and Windows commands in a Windows terminal (such as PowerShell Core, Windows PowerShell, or the Azure Cloud Shell).

ConfigurazioneSetting up

Creare una nuova app console .NETCreate new .NET console app

In una finestra della console usare il comando dotnet new per creare una nuova app console .NET denominata key-vault-console-app.In a console window, use the dotnet new command to create a new .NET console app with the name key-vault-console-app.

dotnet new console -n key-vault-console-app

Spostarsi nella cartella dell'app appena creata.Change your directory to the newly created app folder. È possibile compilare l'applicazione con il comando seguente:You can build the application with:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.The build output should contain no warnings or errors.

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

Installare il pacchettoInstall the package

Nella finestra della console installare la libreria client di Azure Key Vault per .NET:From the console window, install the Azure Key Vault client library for .NET:

dotnet add package Azure.Security.KeyVault.Secrets

Per questo argomento di avvio rapido, è necessario installare anche i pacchetti seguenti:For this quickstart, you will need to install the following packages as well:

dotnet add package Azure.Identity

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

In questo argomento di avvio rapido si usa un'istanza creata in precedenza di Azure Key Vault.This quickstart uses a pre-created Azure key vault. È possibile creare un insieme di credenziali delle chiavi seguendo la procedura descritta negli argomenti di avvio rapido per l'interfaccia della riga di comando di Azure, Azure PowerShell o il portale di Azure.You can create a key vault by following the steps in the Azure CLI quickstart, Azure PowerShell quickstart, or Azure portal quickstart.

In alternativa, è possibile eseguire semplicemente i seguenti comandi dell'interfaccia della riga di comando di Azure o di Azure PowerShell.Alternatively, you can simply run the Azure CLI or Azure PowerShell commands below.

Importante

Ogni insieme di credenziali delle chiavi deve avere un nome univoco.Each key vault must have a unique name. Negli esempi seguenti sostituire con il nome dell'insieme di credenziali delle chiavi in uso.Replace with the name of your key vault in the following examples.

az group create --name "myResourceGroup" -l "EastUS"

az keyvault create --name "<your-unique-keyvault-name>" -g "myResourceGroup"
New-AzResourceGroup -Name myResourceGroup -Location EastUS

New-AzKeyVault -Name "<your-unique-keyvault-name>" -ResourceGroupName "myResourceGroup" -Location "EastUS"

Creare un'entità servizioCreate a service principal

Il modo più semplice per autenticare un'applicazione Python basata sul cloud consiste nell'usare un'identità gestita. Per informazioni dettagliate, vedere Usare un'identità gestita del servizio app per accedere ad Azure Key Vault.The simplest way to authenticate a cloud-based Python application is with a managed identity; see Use an App Service managed identity to access Azure Key Vault for details.

Per semplicità, tuttavia, in questo avvio rapido viene creata un'applicazione desktop, per la quale sono richiesti un'entità servizio e un criterio di controllo di accesso.For the sake of simplicity however, this quickstart creates a desktop application, which requires the use of a service principal and an access control policy. L'entità servizio richiede un nome univoco nel formato "http://<nome-univoco-entità-servizio>".Your service principal requires a unique name in the format "http://<my-unique-service-principal-name>".

Creare un'entità servizio usando il comando az ad sp create-for-rbac dell'interfaccia della riga di comando di Azure:Create a service principal using the Azure CLI az ad sp create-for-rbac command:

az ad sp create-for-rbac -n "http://<my-unique-service-principal-name>" --sdk-auth

Questa operazione restituisce una serie di coppie chiave-valore.This operation will return a series of key / value pairs.

{
  "clientId": "7da18cae-779c-41fc-992e-0527854c6583",
  "clientSecret": "b421b443-1669-4cd7-b5b1-394d5c945002",
  "subscriptionId": "443e30da-feca-47c4-b68f-1636b75e16b3",
  "tenantId": "35ad10f1-7799-4766-9acf-f2d946161b77",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

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

Creare un criterio di accesso per l'insieme di credenziali delle chiavi che conceda l'autorizzazione all'entità servizio, passando clientId al comando az keyvault set-policy.Create an access policy for your key vault that grants permission to your service principal by passing clientId to the az keyvault set-policy command. Concedere all'entità servizio le autorizzazioni get, list e set sia per le chiavi che per i segreti.Give the service principal get, list, and set permissions for both keys and secrets.

az keyvault set-policy -n <your-unique-keyvault-name> --spn <clientId-of-your-service-principal> --secret-permissions delete get list set --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey

Impostare le variabili di ambienteSet environmental variables

Il metodo DefaultAzureCredential usato nell'applicazione si basa sulle tre variabili di ambiente AZURE_CLIENT_ID, AZURE_CLIENT_SECRET e AZURE_TENANT_ID.The DefaultAzureCredential method in our application relies on three environmental variables: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID. Impostare queste variabili sui valori clientId, clientSecret e tenantId restituiti nel passaggio "Creare un'entità servizio" usando il formato export VARNAME=VALUE.Set these variables to the clientId, clientSecret, and tenantId values that were returned in the "Create a service principal" step using the export VARNAME=VALUE format. Questo metodo imposta solo le variabili per la shell corrente e per i processi creati dalla shell. Per aggiungere in modo permanente queste variabili all'ambiente, modificare il file /etc/environment .(This method only sets the variables for your current shell and processes created from the shell; to permanently add these variables to your environment, edit your /etc/environment file.)

Sarà anche necessario salvare il nome dell'insieme di credenziali delle chiavi come una variabile di ambiente denominata KEY_VAULT_NAME.You will also need to save your key vault name as an environment variable called KEY_VAULT_NAME.

export AZURE_CLIENT_ID=<your-clientID>

export AZURE_CLIENT_SECRET=<your-clientSecret>

export AZURE_TENANT_ID=<your-tenantId>

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

Modello a oggettiObject model

La libreria client di Azure Key Vault per .NET consente di gestire le chiavi e gli asset correlati, come i certificati e i segreti.The Azure Key Vault client library for .NET allows you to manage keys and related assets such as certificates and secrets. Gli esempi di codice riportati di seguito illustrano come creare un client e come impostare, recuperare ed eliminare un segreto.The code samples below will show you how to create a client, set a secret, retrieve a secret, and delete a secret.

L'intera app console è disponibile all'indirizzo https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/key-vault-console-app.The entire console app is available at https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/key-vault-console-app.

Esempi di codiceCode examples

Aggiungere le direttiveAdd directives

Aggiungere le direttive seguenti all'inizio del codice:Add the following directives to the top of your code:

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

Autenticare e creare un clientAuthenticate and create a client

L'autenticazione rispetto all'insieme di credenziali delle chiavi e la creazione di un client dell'insieme di credenziali delle chiavi dipendono dalle variabili di ambiente indicate nel passaggio precedente Impostare le variabili di ambiente.Authenticating to your key vault and creating a key vault client depends on the environmental variables in the Set environmental variables step above. Il nome dell'insieme di credenziali delle chiavi viene espanso nel relativo URI, nel formato "https://<your-key-vault-name>.vault.azure.net".The name of your key vault is expanded to the key vault URI, in the format "https://<your-key-vault-name>.vault.azure.net". Il codice seguente utilizza 'DefaultAzureCredential()' per l’autenticazione nell’insieme di credenziali delle chiavi, che legge le variabili di ambiente per recuperare il token di accesso.Below code is using 'DefaultAzureCredential()' for authentication to key vault, which is reading environment variables to retrieve access token.

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 segretoSave a secret

Ora che l'applicazione è stata autenticata, è possibile inserire un segreto nell'insieme di credenziali delle chiavi usando il metodo client.SetSecret. L'operazione richiede un nome per il segreto. In questo esempio viene usato "mySecret".Now that your application is authenticated, you can put a secret into your keyvault using the client.SetSecret method This requires a name for the secret -- we're using "mySecret" in this sample.

client.SetSecret(secretName, secretValue);

È possibile verificare che il segreto sia stato impostato con il comando az keyvault secret show:You can verify that the secret has been set with the az keyvault secret show command:

az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret
(Get-AzKeyVaultSecret -VaultName <your-unique-keyvault-name> -Name mySecret).SecretValueText

Recuperare un segretoRetrieve a secret

È ora possibile recuperare il valore impostato in precedenza con il metodo client.GetSecret.You can now retrieve the previously set value with the client.GetSecret method.

KeyVaultSecret secret = client.GetSecret(secretName);

Il segreto è ora salvato come secret.Value.Your secret is now saved as secret.Value.

consente di eliminare un segretoDelete a secret

Eliminare infine il segreto dall'insieme di credenziali delle chiavi con il metodo client.DeleteSecret.Finally, let's delete the secret from your key vault with the client.DeleteSecret method.

client.StartDeleteSecret(secretName);

È possibile verificare che il segreto non sia più dotato del comando az keyvault secret show:You can verify that the secret is gone with the az keyvault secret show command:

az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret
(Get-AzKeyVaultSecret -VaultName <your-unique-keyvault-name> -Name mySecret).SecretValueText

Pulire le risorseClean up resources

Quando non sono più necessari, è possibile usare l'interfaccia della riga di comando di Azure o Azure PowerShell per rimuovere l'insieme di credenziali delle chiavi e il gruppo di risorse corrispondente.When no longer needed, you can use the Azure CLI or Azure PowerShell to remove your key vault and the corresponding resource group.

Eliminare un insieme di credenziali delle chiaviDelete a Key Vault

az keyvault delete --name <your-unique-keyvault-name>
Remove-AzKeyVault -VaultName <your-unique-keyvault-name>

Rimuovere un insieme di credenziali delle chiaviPurge a Key Vault

az keyvault purge --location eastus --name <your-unique-keyvault-name>
Remove-AzKeyVault -VaultName <your-unique-keyvault-name> -InRemovedState -Location eastus

Eliminare un gruppo di risorseDelete a resource group

az group delete -g "myResourceGroup"
Remove-AzResourceGroup -Name "myResourceGroup"

Codice di esempioSample code

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

namespace key_vault_console_app
{
    class Program
    {
        static void Main(string[] args)
        {
            string secretName = "mySecret";

            string 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 > ");
            string secretValue = Console.ReadLine();

            Console.Write("Creating a secret in " + keyVaultName + " called '" + secretName + "' with the value '" + secretValue + "` ...");

            client.SetSecret(secretName, secretValue);

            Console.WriteLine(" done.");

            Console.WriteLine("Forgetting your secret.");
            secretValue = "";
            Console.WriteLine("Your secret is '" + secretValue + "'.");

            Console.WriteLine("Retrieving your secret from " + keyVaultName + ".");

            KeyVaultSecret secret = client.GetSecret(secretName);

            Console.WriteLine("Your secret is '" + secret.Value + "'.");

            Console.Write("Deleting your secret from " + keyVaultName + " ...");

            client.StartDeleteSecret(secretName);

            System.Threading.Thread.Sleep(5000);
            Console.WriteLine(" done.");

        }
    }
}

Passaggi successiviNext steps

In questo argomento di avvio rapido è stato creato un insieme di credenziali delle chiavi, quindi è stato archiviato e recuperato un segreto.In this quickstart you created a key vault, stored a secret, and retrieved that secret. Vedere l'intera app console in GitHub.See the entire console app in GitHub.

Per altre informazioni sul servizio Key Vault e su come integrarlo nelle applicazioni, continuare con gli articoli seguenti.To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.