Quickstart: Azure Key Vault secret client library for .NET (SDK v4)
Get started with the Azure Key Vault secret client library for .NET. Azure Key Vault is a cloud service that provides a secure store for secrets. You can securely store keys, passwords, certificates, and other secrets. Azure key vaults may be created and managed through the Azure portal. In this quickstart, you learn how to create, retrieve, and delete secrets from an Azure key vault using the .NET client library
Key Vault client library resources:
API reference documentation | Library source code | Package (NuGet)
For more information about Key Vault and secrets, see:
Prerequisites
- An Azure subscription - create one for free
- .NET Core 3.1 SDK or later
- Azure CLI
- Azure PowerShell
- A Key Vault - you can create one using Azure portal Azure CLI, or Azure PowerShell
This quickstart is using dotnet
and Azure CLI or Azure PowerShell.
Setup
This quickstart is using Azure Identity library with Azure CLI to authenticate user to Azure Services. Developers can also use Visual Studio or Visual Studio Code to authenticate their calls, for more information, see Authenticate the client with Azure Identity client library.
Sign in to Azure
Run the
az login
command.az login
If the CLI can open your default browser, it will do so and load an Azure sign-in page.
Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal.
Sign in with your account credentials in the browser.
Grant access to your key vault
Create an access policy for your key vault that grants secret permissions to your user account
az keyvault set-policy --name <YourKeyVaultName> --upn user@domain.com --secret-permissions delete get list set purge
Create new .NET console app
In a command shell, run the following command to create a project named
key-vault-console-app
:dotnet new console --name key-vault-console-app
Change to the newly created key-vault-console-app directory, and run the following command to build the project:
dotnet build
The build output should contain no warnings or errors.
Build succeeded. 0 Warning(s) 0 Error(s)
Install the packages
From the command shell, install the Azure Key Vault secret client library for .NET:
dotnet add package Azure.Security.KeyVault.Secrets
For this quickstart, you'll also need to install the Azure SDK client library for Azure Identity:
dotnet add package Azure.Identity
Set environment variables
This application is using key vault name as an environment variable called KEY_VAULT_NAME
.
Windows
set KEY_VAULT_NAME=<your-key-vault-name>
Windows PowerShell
$Env:KEY_VAULT_NAME="<your-key-vault-name>"
macOS or Linux
export KEY_VAULT_NAME=<your-key-vault-name>
Object model
The Azure Key Vault secret client library for .NET allows you to manage secrets. The Code examples section shows how to create a client, set a secret, retrieve a secret, and delete a secret.
Code examples
Add directives
Add the following directives to the top of Program.cs:
using System;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
Authenticate and create a client
In this quickstart, logged in user is used to authenticate to key vault, which is preferred method for local development. For applications deployed to Azure, managed identity should be assigned to App Service or Virtual Machine, for more information, see Managed Identity Overview.
In below example, the name of your key vault is expanded to the key vault URI, in the format "https://<your-key-vault-name>.vault.azure.net". This example is using 'DefaultAzureCredential()' class from Azure Identity Library, which allows to use the same code across different environments with different options to provide identity. For more information about authenticating to key vault, see Developer's Guide.
string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = "https://" + keyVaultName + ".vault.azure.net";
var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
Save a secret
Now that the console app is authenticated, add a secret to the key vault. For this task, use the SetSecretAsync method. The method's first parameter accepts a name for the secret—"mySecret" in this sample.
await client.SetSecretAsync(secretName, secretValue);
Note
If secret name exists, above code will create new version of that secret.
Retrieve a secret
You can now retrieve the previously set value with the GetSecretAsync method.
var secret = await client.GetSecretAsync(secretName);
Your secret is now saved as secret.Value
.
Delete a secret
Finally, let's delete the secret from your key vault with the StartDeleteSecretAsync and PurgeDeletedSecretAsync methods.
var operation = await client.StartDeleteSecretAsync("mySecret");
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();
await client.PurgeDeletedKeyAsync("mySecret");
Sample code
Modify the .NET Core console app to interact with the Key Vault by completing the following steps:
Replace the code in Program.cs with the following code:
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 and verify
Execute the following command to run the app.
dotnet run
When prompted, enter a secret value. For example, mySecretPassword.
A variation of the following output appears:
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.
Next steps
To learn more about Key Vault and how to integrate it with your apps, see the following articles:
Feedback
Submit and view feedback for