Quickstart: Azure Key Vault-clientbibliotheek voor .NET (SDK v4)Quickstart: Azure Key Vault client library for .NET (SDK v4)

Ga aan de slag met de Azure Key Vault-clientbibliotheek voor .NET.Get started with the Azure Key Vault client library for .NET. Volg de onderstaande stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.Follow the steps below to install the package and try out example code for basic tasks.

Met Azure Sleutelkluis kunt u de cryptografische sleutels en geheimen beveiligen die door cloudtoepassingen en -services worden gebruikt.Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Gebruik de Key Vault-clientbibliotheek voor .NET voor het volgende:Use the Key Vault client library for .NET to:

  • De beveiliging en controle over sleutels en wachtwoorden verbeteren.Increase security and control over keys and passwords.
  • In een paar minuten versleutelingssleutels maken en importeren.Create and import encryption keys in minutes.
  • Latentie verminderen met schalen in de cloud en globale redundantie.Reduce latency with cloud scale and global redundancy.
  • Taken voor TLS/SSL-certificaten vereenvoudigen en automatiseren.Simplify and automate tasks for TLS/SSL certificates.
  • FIPS 140-2 level 2-gevalideerde HSM's gebruiken.Use FIPS 140-2 Level 2 validated HSMs.

API-referentiedocumentatie | Broncode bibliotheek | Pakket (NuGet)API reference documentation | Library source code | Package (NuGet)

VereistenPrerequisites

In deze quickstart wordt ervan uitgegaan dat u dotnet, Azure CLI en Windows-opdrachten in een Windows-terminal (zoals PowerShell Core, Windows PowerShell of Azure Cloud Shell) uitvoert.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).

InstellenSetting up

Nieuwe .NET-console-app makenCreate new .NET console app

Gebruik in een consolevenster de opdracht dotnet new om een nieuwe .NET-console-app te maken met de naam 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

Wijzig uw map in de zojuist gemaakte app-map.Change your directory to the newly created app folder. U kunt de toepassing maken met:You can build the application with:

dotnet build

De build-uitvoer mag geen waarschuwingen of fouten bevatten.The build output should contain no warnings or errors.

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

Het pakket installerenInstall the package

Installeer vanuit het consolevenster de Azure Key Vault-clientbibliotheek voor .NET:From the console window, install the Azure Key Vault client library for .NET:

dotnet add package Azure.Security.KeyVault.Secrets

Voor deze quickstart moet u ook de volgende pakketten installeren:For this quickstart, you will need to install the following packages as well:

dotnet add package Azure.Identity

Een resourcegroep en sleutelkluis makenCreate a resource group and key vault

In deze quickstart wordt gebruikgemaakt van een vooraf gemaakte Azure-sleutelkluis.This quickstart uses a pre-created Azure key vault. U kunt een sleutelkluis maken met behulp van de stappen in de quickstart voor Azure CLI, de quickstart voor Azure PowerShell of de quickstart voor de Azure-portal.You can create a key vault by following the steps in the Azure CLI quickstart, Azure PowerShell quickstart, or Azure portal quickstart.

U kunt ook de onderstaande Azure CLI- of Azure PowerShell-opdrachten uitvoeren.Alternatively, you can simply run the Azure CLI or Azure PowerShell commands below.

Belangrijk

Elke sleutelkluis moet een unieke naam hebben.Each key vault must have a unique name. Vervang door de naam van uw sleutelkluis in de volgende voorbeelden.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"

Een service-principal makenCreate a service principal

De eenvoudigste manier om een cloudtoepassing te verifiëren, is met een beheerde identiteit. Zie Verificatie bij Azure Key Vault voor meer informatie.The simplest way to authenticate a cloud-based application is with a managed identity; see Authenticate to Key Vault for details.

In deze quickstart wordt echter een desktoptoepassing gemaakt, omdat dit eenvoudiger is. Voor deze toepassing is het gebruik van een service-principal en een toegangsbeheerbeleid vereist.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. Voor uw service-principal is een unieke naam vereist met de notatie http://<mijn-unieke-service-principal-naam>.Your service principal requires a unique name in the format "http://<my-unique-service-principal-name>".

Maak een service-principal met behulp van de Azure CLI-opdracht az ad sp create-for-rbac:Create a service principal using the Azure CLI az ad sp create-for-rbac command:

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

Met deze bewerking wordt een reeks sleutel-waardeparen geretourneerd.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/"
}

De service-principal toegang verlenen tot uw sleutelkluisGive the service principal access to your key vault

Maak een toegangsbeleid voor de sleutelkluis dat machtigingen verleent aan uw service-principal door de clientId door te geven aan de opdracht 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. Geef de service-principal-machtigingen voor ophalen, weergeven en instellen voor zowel sleutels als geheimen.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

Omgevingsvariabelen instellenSet environmental variables

De methode DefaultAzureCredential in de toepassing is afhankelijk van drie omgevingsvariabelen: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET en AZURE_TENANT_ID.The DefaultAzureCredential method in our application relies on three environmental variables: AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID. Stel deze variabelen in op de clientId-, clientSecret- en tenantId-waarden die zijn geretourneerd in de stap Een service-principal maken, met de indeling 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. (Met deze methode worden alleen de variabelen ingesteld voor uw huidige shell en processen gemaakt vanuit de shell. Als u deze variabelen permanent wilt toevoegen aan uw omgeving, moet u het bestand /etc/environment bewerken.)(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.)

U moet de naam van de sleutelkluis ook opslaan als een omgevingsvariabele met de naam 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>

ObjectmodelObject model

Met de Azure Key Vault-client bibliotheek voor .NET kunt u sleutels en gerelateerde assets, zoals certificaten en geheimen, beheren.The Azure Key Vault client library for .NET allows you to manage keys and related assets such as certificates and secrets. In de onderstaande codevoorbeelden ziet u hoe u een client maakt, een geheim instelt, een geheim ophaalt en een geheim verwijdert.The code samples below will show you how to create a client, set a secret, retrieve a secret, and delete a secret.

De volledige console-app is beschikbaar op 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.

CodevoorbeeldenCode examples

Instructies toevoegenAdd directives

Voeg de volgende instructies toe aan het begin van de code:Add the following directives to the top of your code:

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

Een client verifiëren en makenAuthenticate and create a client

Het verifiëren van uw sleutelkluis en het maken van een sleutelkluis-client is afhankelijk van de omgevingsvariabelen in de stap Omgevingsvariabelen instellen hierboven.Authenticating to your key vault and creating a key vault client depends on the environmental variables in the Set environmental variables step above. De naam van de sleutelkluis wordt uitgebreid naar de sleutelkluis-URI, met de indeling 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". De onderstaande code maakt gebruik van 'DefaultAzureCredential()' voor verificatie naar de sleutelkluis, die omgevingsvariabelen leest om het toegangstoken op te halen.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());

Een geheim opslaanSave a secret

Nu uw toepassing is geverifieerd, kunt u een geheim in uw sleutelkluis plaatsen met behulp van de methode client.SetSecret. Hiervoor is een naam vereist voor het geheim. In dit voorbeeld gebruiken we "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);

U kunt controleren of het geheim is ingesteld met de opdracht 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

Een geheim ophalenRetrieve a secret

U kunt nu de eerder ingestelde waarde ophalen met de methode client.GetSecret.You can now retrieve the previously set value with the client.GetSecret method.

KeyVaultSecret secret = client.GetSecret(secretName);

Uw geheim wordt nu opgeslagen als secret.Value.Your secret is now saved as secret.Value.

Een geheim verwijderenDelete a secret

Ten slotte gaan we het geheim uit uw sleutelkluis verwijderen met de methode client.DeleteSecret.Finally, let's delete the secret from your key vault with the client.DeleteSecret method.

client.StartDeleteSecret(secretName);

U kunt controleren of het geheim is verdwenen met de opdracht 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

Resources opschonenClean up resources

Wanneer u de sleutelkluis en de bijbehorende resourcegroep niet meer nodig hebt, kunt u Azure CLI of Azure PowerShell gebruiken om ze te verwijderen.When no longer needed, you can use the Azure CLI or Azure PowerShell to remove your key vault and the corresponding resource group.

Een sleutelkluis verwijderenDelete a Key Vault

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

Een sleutelkluis opschonenPurge a Key Vault

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

Een resourcegroep verwijderenDelete a resource group

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

VoorbeeldcodeSample 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.");

        }
    }
}

Volgende stappenNext steps

In deze quickstart hebt u een sleutelkluis gemaakt, een geheim opgeslagen en dat geheim opgehaald.In this quickstart you created a key vault, stored a secret, and retrieved that secret. Zie de volledige console-app in GitHub.See the entire console app in GitHub.

Ga verder met de volgende artikelen als u meer wilt weten over Key Vault en hoe u het integreert met uw toepassingen.To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.