Edit

Tutorial: Use a managed identity to connect Key Vault to an Azure web app in .NET

Azure Key Vault provides a way to store credentials and other secrets with increased security. But your code needs to authenticate to Key Vault to retrieve them. Managed identities for Azure resources solve this problem by giving Azure services an automatically managed identity in Microsoft Entra ID. Your code uses this identity to authenticate to any service that supports Microsoft Entra authentication, including Key Vault, without embedding credentials in the code.

In this tutorial, you create and deploy an Azure web application to Azure App Service, then use a managed identity to authenticate the app to a key vault by using the Azure Key Vault secret client library for .NET and the Azure CLI. The same principles apply if you use another language, Azure PowerShell, or the Azure portal.

For more information about App Service web apps and deployment, see:

Prerequisites

To complete this tutorial, you need:

If you already have a web app deployed in Azure App Service, skip to Configure the web app to connect to Key Vault and Modify the app to access your key vault.

Create a .NET Core app

In this step, set up the local .NET project.

In a terminal window, create a directory named akvwebapp and switch to it:

mkdir akvwebapp
cd akvwebapp

Create a .NET web app by using the dotnet new web command:

dotnet new web

Run the app locally to see how it looks before you deploy it to Azure:

dotnet run

In a web browser, open the app at http://localhost:5000. You see the "Hello World!" message from the sample app.

For more information about creating web apps, see Create an ASP.NET Core web app in Azure App Service.

Deploy the app to Azure

In this step, deploy the .NET app to Azure App Service by using zip deploy. Zip deploy is the recommended package-based deployment mechanism for App Service. For continuous delivery from source control, use GitHub Actions or Azure DevOps Pipelines instead.

Create a resource group

Create a resource group to contain the key vault and web app by using az group create:

az group create --name "<resource-group>" --location "EastUS"

Create an App Service plan

Create an App Service plan by using az appservice plan create. The following example creates a plan named myAppServicePlan in the free (FREE) tier:

az appservice plan create --name myAppServicePlan --resource-group <resource-group> --sku FREE

Create a web app

Create an Azure web app in the myAppServicePlan plan.

Important

Like a key vault, an Azure web app must have a globally unique name. Replace <webapp-name> with your web app's name.

az webapp create --resource-group "<resource-group>" --plan "myAppServicePlan" --name "<webapp-name>"

Go to the new app to confirm it's running:

https://<webapp-name>.azurewebsites.net

You see the default page for a new Azure web app.

Deploy your local app with zip deploy

From the akvwebapp project directory, build the project and create a deployment zip:

dotnet publish -c Release -o ./publish
cd publish
zip -r ../akvwebapp.zip .
cd ..

Tip

On Windows without zip, use PowerShell: Compress-Archive -Path .\publish\* -DestinationPath .\akvwebapp.zip.

Deploy the zip to your web app by using az webapp deploy:

az webapp deploy --resource-group "<resource-group>" --name "<webapp-name>" --src-path ./akvwebapp.zip --type zip

Refresh the deployed app in your web browser:

https://<webapp-name>.azurewebsites.net

You see the same "Hello World!" message you saw at http://localhost:5000.

Configure the web app to connect to Key Vault

In this section, you enable the web app to access Key Vault and update your app code to retrieve a secret.

Create and assign access to a managed identity

Use a managed identity to authenticate the web app to Key Vault. A managed identity removes the need for you to manage credentials in code.

Create the identity for the app by using az webapp identity assign:

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

The command returns a JSON snippet similar to this:

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

To gain permissions to your key vault through Role-Based Access Control (RBAC), assign a role to your "User Principal Name" (UPN) using the Azure CLI command az role assignment create.

az role assignment create --role "Key Vault Secrets User" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.KeyVault/vaults/<vault-name>"

Replace <upn>, <subscription-id>, and <vault-name> with your actual values. If you used a different resource group name, replace "myResourceGroup" as well. Your UPN will typically be in the format of an email address (e.g., username@domain.com).

Modify the app to access your key vault

This tutorial uses the Azure Key Vault secret client library. You can also use the Azure Key Vault certificate client library or the Azure Key Vault key client library.

Install the packages

From the terminal window, install the Azure Key Vault secret client library and the Azure Identity client library:

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Secrets

Update the code

Open Program.cs in your akvwebapp project.

Add these using directives at the top of the file:

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

Add the following lines before the app.MapGet call, updating <vault-name> to your key vault name. This code uses DefaultAzureCredential to authenticate to Key Vault through the web app's managed identity. For more information, see the developer's guide. The code also configures exponential backoff for retries in case Key Vault is throttled. For details on transaction limits, see Azure Key Vault throttling guidance.

SecretClientOptions options = new SecretClientOptions()
    {
        Retry =
        {
            Delay= TimeSpan.FromSeconds(2),
            MaxDelay = TimeSpan.FromSeconds(16),
            MaxRetries = 5,
            Mode = RetryMode.Exponential
         }
    };
var client = new SecretClient(new Uri("https://<vault-name>.vault.azure.net/"), new DefaultAzureCredential(), options);

KeyVaultSecret secret = client.GetSecret("<secret-name>");

string secretValue = secret.Value;

Update the line app.MapGet("/", () => "Hello World!"); to:

app.MapGet("/", () => secretValue);

Save your changes.

Redeploy your web app

Rebuild the deployment package and redeploy:

dotnet publish -c Release -o ./publish
cd publish
zip -r ../akvwebapp.zip .
cd ..
az webapp deploy --resource-group "<resource-group>" --name "<webapp-name>" --src-path ./akvwebapp.zip --type zip

Go to your completed web app

https://<webapp-name>.azurewebsites.net

Where you previously saw "Hello World!", you now see the value of your secret.

Next steps

  • Last updated on