Quickstart: Azure Key Vault certificate client library for .NET (SDK v4)

Get started with the Azure Key Vault certificate client library for .NET. Azure Key Vault is a cloud service that provides a secure store for certificates. 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 certificates 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 certificates, see:

Prerequisites

This quickstart is using dotnet and Azure CLI

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

  1. Run the 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.

  2. 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 certificate permissions to your user account

az keyvault set-policy --name <your-key-vault-name> --upn user@domain.com --certificate-permissions delete get list create purge

Create new .NET console app

  1. 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
    
  2. 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 certificate client library for .NET:

dotnet add package Azure.Security.KeyVault.Certificates

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 certificate client library for .NET allows you to manage certificates. The Code examples section shows how to create a client, set a certificate, retrieve a certificate, and delete a certificate.

Code examples

Add directives

Add the following directives to the top of Program.cs:

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

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 CertificateClient(new Uri(kvUri), new DefaultAzureCredential());

Save a certificate

In this example, for simplicity you can use self-signed certificate with default issuance policy. For this task, use the StartCreateCertificateAsync method. The method's parameters accepts a certificate name and the certificate policy.

var operation = await client.StartCreateCertificateAsync("myCertificate", CertificatePolicy.Default);
var certificate = await operation.WaitForCompletionAsync();

Note

If certificate name exists, above code will create new version of that certificate.

Retrieve a certificate

You can now retrieve the previously created certificate with the GetCertificateAsync method.

var certificate = await client.GetCertificateAsync("myCertificate");

Delete a certificate

Finally, let's delete and purge the certificate from your key vault with the StartDeleteCertificateAsync and PurgeDeletedCertificateAsync methods.

var operation = await client.StartDeleteCertificateAsync("myCertificate");

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

var certificate = operation.Value;
await client.PurgeDeletedCertificateAsync("myCertificate");

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.Certificates;
    
    namespace key_vault_console_app
    {
        class Program
        {
            static async Task Main(string[] args)
            {
                const string certificateName = "myCertificate";
                var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
                var kvUri = $"https://{keyVaultName}.vault.azure.net";
    
                var client = new CertificateClient(new Uri(kvUri), new DefaultAzureCredential());
    
                Console.Write($"Creating a certificate in {keyVaultName} called '{certificateName}' ...");
                CertificateOperation operation = await client.StartCreateCertificateAsync(certificateName, CertificatePolicy.Default);
                await operation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.WriteLine($"Retrieving your certificate from {keyVaultName}.");
                var certificate = await client.GetCertificateAsync(certificateName);
                Console.WriteLine($"Your certificate version is '{certificate.Value.Properties.Version}'.");
    
                Console.Write($"Deleting your certificate from {keyVaultName} ...");
                DeleteCertificateOperation deleteOperation = await client.StartDeleteCertificateAsync(certificateName);
                // You only need to wait for completion if you want to purge or recover the certificate.
                await deleteOperation.WaitForCompletionAsync();
                Console.WriteLine(" done.");
    
                Console.Write($"Purging your certificate from {keyVaultName} ...");
                await client.PurgeDeletedCertificateAsync(certificateName);
                Console.WriteLine(" done.");
            }
        }
    }
    

Test and verify

Execute the following command to build the project

dotnet build

A variation of the following output appears:

Creating a certificate in mykeyvault called 'myCertificate' ... done.
Retrieving your certificate from mykeyvault.
Your certificate version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your certificate from mykeyvault ... done
Purging your certificate from mykeyvault ... done

Next steps

In this quickstart, you created a key vault, stored a certificate, and retrieved that certificate.

To learn more about Key Vault and how to integrate it with your apps, see the following articles: