Quickstart: Set and retrieve a secret from Azure Key Vault by using a .NET web app

In this quickstart, you follow the steps for getting an Azure web application to read information from Azure Key Vault by using managed identities for Azure resources. Using Key Vault helps keep the information secure. You learn how to:

  • Create a key vault.
  • Store a secret in the key vault.
  • Retrieve a secret from the key vault.
  • Create an Azure web application.
  • Enable a managed service identity for the web app.
  • Grant the required permissions for the web application to read data from the key vault.

Before we go any further, please read the basic concepts for Key Vault.

Note

Key Vault is a central repository to store secrets programmatically. But to do so, applications and users need to first authenticate to Key Vault--that is, present a secret. In keeping with security best practices, this first secret needs to be rotated periodically.

With managed service identities for Azure resources, applications that run in Azure get an identity that Azure manages automatically. This helps solve the secret introduction problem so that users and applications can follow best practices and not have to worry about rotating the first secret.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Cloud Shell lets you use either bash or PowerShell to work with Azure services. You can use the Cloud Shell pre-installed commands to run the code in this article without having to install anything on your local environment.

To launch Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the top-right menu bar in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Launch Cloud Shell.
  2. Select the Copy button on a code block to copy the code.
  3. Paste the code into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS.
  4. Press Enter to run the code.

Prerequisites

Log in to Azure

To log in to Azure by using the Azure CLI, enter:

az login

Create a resource group

Create a resource group by using the az group create command. An Azure resource group is a logical container into which Azure resources are deployed and managed.

Select a resource group name and fill in the placeholder. The following example creates a resource group in the East US location:

# To list locations: az account list-locations --output table
az group create --name "<YourResourceGroupName>" --location "East US"

The resource group that you just created is used throughout this article.

Create a key vault

Next you create a key vault in the resource group that you created in the previous step. Provide the following information:

  • Key vault name: The name must be a string of 3-24 characters and must contain only 0-9, a-z, A-Z, and a hyphen (-).
  • Resource group name.
  • Location: East US.
az keyvault create --name "<YourKeyVaultName>" --resource-group "<YourResourceGroupName>" --location "East US"

At this point, your Azure account is the only one that's authorized to perform any operations on this new vault.

Add a secret to the key vault

We're adding a secret to help illustrate how this works. You might be storing a SQL connection string or any other information that you need to keep securely but make available to your application.

Type the following commands to create a secret in the key vault called AppSecret. This secret will store the value MySecret.

az keyvault secret set --vault-name "<YourKeyVaultName>" --name "AppSecret" --value "MySecret"

To view the value contained in the secret as plain text:

az keyvault secret show --name "AppSecret" --vault-name "<YourKeyVaultName>"

This command shows the secret information, including the URI. After you complete these steps, you should have a URI to a secret in a key vault. Make note of this information. You'll need it in a later step.

Clone the repo

Clone the repo to make a local copy where you can edit the source. Run the following command:

git clone https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart.git

Open and edit the solution

Edit the program.cs file to run the sample with your specific key vault name:

  1. Browse to the folder key-vault-dotnet-core-quickstart.
  2. Open the key-vault-dotnet-core-quickstart.sln file in Visual Studio 2019.
  3. Open the Program.cs file and update the placeholder YourKeyVaultName with the name of the key vault that you created earlier.

This solution uses AppAuthentication and KeyVault NuGet libraries.

Run the app

From the main menu of Visual Studio 2019, select Debug > Start without debugging. When the browser appears, go to the About page. The value for AppSecret is displayed.

Publish the web application to Azure

Publish this app to Azure to see it live as a web app, and to see that you can fetch the secret value:

  1. In Visual Studio, select the key-vault-dotnet-core-quickstart project.
  2. Select Publish > Start.
  3. Create a new App Service, and then select Publish.
  4. Change the app name to keyvaultdotnetcorequickstart.
  5. Select Create.

Enable a managed identity for the web app

Azure Key Vault provides a way to securely store credentials and other keys and secrets, but your code needs to authenticate to Key Vault to retrieve them. Managed identities for Azure resources overview makes solving this problem simpler, by giving Azure services an automatically managed identity in Azure Active Directory (Azure AD). You can use this identity to authenticate to any service that supports Azure AD authentication, including Key Vault, without having any credentials in your code.

In the Azure CLI, run the assign-identity command to create the identity for this application:

az webapp identity assign --name "keyvaultdotnetcorequickstart" --resource-group "<YourResourceGroupName>"

Note

The command in this procedure is the equivalent of going to the portal and switching the Identity / System assigned setting to On in the web application properties.

Assign permissions to your application to read secrets from Key Vault

Make a note of the output when you publish the application to Azure. It should be of the format:

    {
      "principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "type": "SystemAssigned"
    }
    

Then, run this command by using the name of your key vault and the value of PrincipalId:


az keyvault set-policy --name '<YourKeyVaultName>' --object-id <PrincipalId> --secret-permissions get list

Now when you run the application, you should see your secret value retrieved. In the preceding command, you're giving the identity of the app service permissions to do get and list operations on your key vault.

Clean up resources

Delete the resource group, virtual machine, and all related resources when you no longer need them. To do so, select the resource group for the key vault and select Delete.

Delete the key vault by using the az keyvault delete command:

az keyvault delete --name
                   [--resource-group]
                   [--subscription]

Next steps