AKV client secret using a Managed Identity (#35670)

guardrex · web-flow · commit 7c1ad551aca2 · 2025-06-25T11:01:46.000-04:00
diff --git a/aspnetcore/blazor/call-web-api.md b/aspnetcore/blazor/call-web-api.md
@@ -166,7 +166,15 @@ if (builder.Environment.IsProduction())
 else
 {
     // Local development and testing only
-    credential = new DefaultAzureCredential();
+    DefaultAzureCredentialOptions options = new()
+    {
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
+
+    credential = new DefaultAzureCredential(options);
 }
 
 builder.Services.AddDataProtection()
@@ -177,6 +185,8 @@ builder.Services.AddDataProtection()
 
 `{MANAGED IDENTITY CLIENT ID}`: The Azure Managed Identity Client ID (GUID).
 
+`{TENANT ID}`: Tenant ID.
+
 `{APPLICATION NAME}`: <xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.SetApplicationName%2A> sets the unique name of this app within the data protection system. The value should match across deployments of the app.
 
 `{BLOB URI}`: Full URI to the key file. The URI is generated by Azure Storage when you create the key file. Do not use a SAS.
diff --git a/aspnetcore/blazor/security/account-confirmation-and-password-recovery.md b/aspnetcore/blazor/security/account-confirmation-and-password-recovery.md
@@ -78,12 +78,18 @@ For more information, see <xref:security/app-secrets>.
 
 [Azure Key Vault](https://azure.microsoft.com/products/key-vault/) provides a safe approach for providing the app's client secret to the app.
 
-To create a key vault and set a secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. To implement the code in this section, record the key vault URI and the secret name from Azure when you create the key vault and secret. When you set the access policy for the secret in the **Access policies** panel:
+To create a key vault and set a secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. For the example in this section, the secret name is "`EmailAuthKey`."
 
-* Only the **Get** secret permission is required.
-* Select the application as the **Principal** for the secret.
+When establishing the key vault in the Entra or Azure portal:
 
-Confirm in the Azure or Entra portal that the app has been granted access to the secret that you created for the email provider key.
+* Configure the key vault to use Azure role-based access control (RABC). If you aren't operating on an [Azure Virtual Network](/azure/virtual-network/virtual-networks-overview), including for local development and testing, confirm that public access on the **Networking** step is **enabled** (checked). Enabling public access only exposes the key vault endpoint. Authenticated accounts are still required for access.
+
+* Create an Azure Managed Identity (or add a role to the existing Managed Identity that you plan to use) with the **Key Vault Secrets User** role. Assign the Managed Identity to the Azure App Service that's hosting the deployment: **Settings** > **Identity** > **User assigned** > **Add**.
+
+  > [!NOTE]
+  > If you also plan to run an app locally with an authorized user for blob access using the [Azure CLI](/cli/azure/) or Visual Studio's Azure Service Authentication, add your developer Azure user account in **Access Control (IAM)** with the **Key Vault Secrets User** role. If you want to use the Azure CLI through Visual Studio, execute the `az login` command from the Developer PowerShell panel and follow the prompts to authenticate with the tenant.
+
+To implement the code in this section, record the key vault URI (example: "`https://contoso.vault.azure.net/`", trailing slash required) and the secret name (example: "`EmailAuthKey`") from Azure when you create the key vault and secret.
 
 > [!IMPORTANT]
 > A key vault secret is created with an expiration date. Be sure to track when a key vault secret is going to expire and create a new secret for the app prior to that date passing.
@@ -93,74 +99,66 @@ Add the following `AzureHelper` class to the server project. The `GetKeyVaultSec
 `Helpers/AzureHelper.cs`:
 
 ```csharp
-using Azure;
-using Azure.Identity;
+using Azure.Core;
 using Azure.Security.KeyVault.Secrets;
 
 namespace BlazorSample.Helpers;
 
 public static class AzureHelper
 {
-    public static string GetKeyVaultSecret(string tenantId, string vaultUri, string secretName)
+    public static string GetKeyVaultSecret(string vaultUri, 
+        TokenCredential credential, string secretName)
     {
-        DefaultAzureCredentialOptions options = new()
-        {
-            // Specify the tenant ID to use the dev credentials when running the app locally
-            // in Visual Studio.
-            VisualStudioTenantId = tenantId,
-            SharedTokenCacheTenantId = tenantId
-        };
-
-        var client = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential(options));
+        var client = new SecretClient(new Uri(vaultUri), credential);
         var secret = client.GetSecretAsync(secretName).Result;
 
         return secret.Value.Value;
     }
 }
 ```
 
-> [!NOTE]
-> The preceding example uses <xref:Azure.Identity.DefaultAzureCredential> to simplify authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. When moving to production, an alternative is a better choice, such as <xref:Azure.Identity.ManagedIdentityCredential>. For more information, see [Authenticate Azure-hosted .NET apps to Azure resources using a system-assigned managed identity](/dotnet/azure/sdk/authentication/system-assigned-managed-identity).
-
 Where services are registered in the server project's `Program` file, obtain and bind the secret with [Options configuration](xref:fundamentals/configuration/options):
 
 ```csharp
-var tenantId = builder.Configuration.GetValue<string>("AzureAd:TenantId")!;
-var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
-
-var emailAuthKey = AzureHelper.GetKeyVaultSecret(
-    tenantId, vaultUri, "EmailAuthKey");
-
-var authMessageSenderOptions = 
-    new AuthMessageSenderOptions() { EmailAuthKey = emailAuthKey };
-builder.Configuration.GetSection(authMessageSenderOptions.EmailAuthKey)
-    .Bind(authMessageSenderOptions);
-```
+TokenCredential? credential;
 
-If you wish to control the environment where the preceding code operates, for example to avoid running the code locally because you've opted to use the [Secret Manager tool](#secret-manager-tool) for local development, you can wrap the preceding code in a conditional statement that checks the environment:
-
-```csharp
-if (!context.HostingEnvironment.IsDevelopment())
+if (builder.Environment.IsProduction())
 {
-    ...
+    credential = new ManagedIdentityCredential("{MANAGED IDENTITY CLIENT ID}");
 }
-```
-
-In the `AzureAd` section of `appsettings.json` in the server project, confirm the presence of the app's Entra ID `TenantId` and add the following `VaultUri` configuration key and value, if it isn't already present:
-
-```json
-"VaultUri": "{VAULT URI}"
-```
+else
+{
+    // Local development and testing only
+    DefaultAzureCredentialOptions options = new()
+    {
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
 
-In the preceding example, the `{VAULT URI}` placeholder is the key vault URI. Include the trailing slash on the URI.
+    credential = new DefaultAzureCredential(options);
+}
 
-Example:
+var emailAuthKey = AzureHelper.GetKeyVaultSecret("{VAULT URI}", credential, 
+    "EmailAuthKey");
 
-```json
-"VaultUri": "https://contoso.vault.azure.net/"
+var authMessageSenderOptions = 
+    new AuthMessageSenderOptions() { EmailAuthKey = emailAuthKey };
+builder.Configuration.GetSection(authMessageSenderOptions.EmailAuthKey)
+    .Bind(authMessageSenderOptions);
 ```
 
-Configuration is used to facilitate supplying dedicated key vaults and secret names based on the app's environmental configuration files. For example, you can supply different configuration values for `appsettings.Development.json` in development, `appsettings.Staging.json` when staging, and `appsettings.Production.json` for the production deployment. For more information, see <xref:blazor/fundamentals/configuration>.
+> [!NOTE]
+> In non-Production environments, the preceding example uses <xref:Azure.Identity.DefaultAzureCredential> to simplify authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. For more information, see [Authenticate Azure-hosted .NET apps to Azure resources using a system-assigned managed identity](/dotnet/azure/sdk/authentication/system-assigned-managed-identity).
+>
+> The preceding example implies that the Managed Identity Client ID (`{MANAGED IDENTITY CLIENT ID}`), directory (tenant) ID (`{TENANT ID}`), and key vault URI (`{VAULT URI}`, example: `https://contoso.vault.azure.net/`, trailing slash required) are supplied by hard-coded values. Any or all of these values can be supplied from app settings configuration. For example, the following obtains the vault URI from the `AzureAd` node of an app settings file, and `vaultUri` can be used in the call to `GetKeyVaultSecret` in the preceding example:
+>
+> ```csharp
+> var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
+> ```
+>
+> For more information, see <xref:blazor/fundamentals/configuration>.
 
 ## Implement `IEmailSender`
 
diff --git a/aspnetcore/blazor/security/blazor-web-app-with-entra.md b/aspnetcore/blazor/security/blazor-web-app-with-entra.md
@@ -478,10 +478,18 @@ If using Visual Studio, you can confirm that the secret is set by right-clicking
 
 [Azure Key Vault](https://azure.microsoft.com/products/key-vault/) provides a safe approach for providing the app's client secret to the app.
 
-To create a key vault and set a client secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. To implement the code in this section, record the key vault URI and the secret name from Azure when you create the key vault and secret. When you set the access policy for the secret in the **Access policies** panel:
+To create a key vault and set a client secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. To implement the code in this section, record the key vault URI and the secret name from Azure when you create the key vault and secret. For the example in this section, the secret name is "`BlazorWebAppEntraClientSecret`."
 
-* Only the **Get** secret permission is required.
-* Select the application as the **Principal** for the secret.
+When establishing the key vault in the Entra or Azure portal:
+
+* Configure the key vault to use Azure role-based access control (RABC). If you aren't operating on an [Azure Virtual Network](/azure/virtual-network/virtual-networks-overview), including for local development and testing, confirm that public access on the **Networking** step is **enabled** (checked). Enabling public access only exposes the key vault endpoint. Authenticated accounts are still required for access.
+
+* Create an Azure Managed Identity (or add a role to the existing Managed Identity that you plan to use) with the **Key Vault Secrets User** role. Assign the Managed Identity to the Azure App Service that's hosting the deployment: **Settings** > **Identity** > **User assigned** > **Add**.
+
+  > [!NOTE]
+  > If you also plan to run an app locally with an authorized user for blob access using the [Azure CLI](/cli/azure/) or Visual Studio's Azure Service Authentication, add your developer Azure user account in **Access Control (IAM)** with the **Key Vault Secrets User** role. If you want to use the Azure CLI through Visual Studio, execute the `az login` command from the Developer PowerShell panel and follow the prompts to authenticate with the tenant.
+
+To implement the code in this section, record the key vault URI (example: "`https://contoso.vault.azure.net/`", trailing slash required) and the secret name (example: "`BlazorWebAppEntraClientSecret`") from Azure when you create the key vault and secret.
 
 > [!IMPORTANT]
 > A key vault secret is created with an expiration date. Be sure to track when a key vault secret is going to expire and create a new secret for the app prior to that date passing.
@@ -491,25 +499,17 @@ Add the following `AzureHelper` class to the server project. The `GetKeyVaultSec
 `Helpers/AzureHelper.cs`:
 
 ```csharp
-using Azure;
-using Azure.Identity;
+using Azure.Core;
 using Azure.Security.KeyVault.Secrets;
 
 namespace BlazorWebAppEntra.Helpers;
 
 public static class AzureHelper
 {
-    public static string GetKeyVaultSecret(string tenantId, string vaultUri, string secretName)
+    public static string GetKeyVaultSecret(string vaultUri, 
+        TokenCredential credential, string secretName)
     {
-        DefaultAzureCredentialOptions options = new()
-        {
-            // Specify the tenant ID to use the dev credentials when running the app locally
-            // in Visual Studio.
-            VisualStudioTenantId = tenantId,
-            SharedTokenCacheTenantId = tenantId
-        };
-
-        var client = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential(options));
+        var client = new SecretClient(new Uri(vaultUri), credential);
         var secret = client.GetSecretAsync(secretName).Result;
 
         return secret.Value.Value;
@@ -523,46 +523,41 @@ public static class AzureHelper
 Where services are registered in the server project's `Program` file, obtain and apply the client secret using the following code:
 
 ```csharp
-var tenantId = builder.Configuration.GetValue<string>("AzureAd:TenantId")!;
-var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
-var secretName = builder.Configuration.GetValue<string>("AzureAd:SecretName")!;
+TokenCredential? credential;
 
-builder.Services.Configure<MicrosoftIdentityOptions>(
-    OpenIdConnectDefaults.AuthenticationScheme,
-    options =>
+if (builder.Environment.IsProduction())
+{
+    credential = new ManagedIdentityCredential("{MANAGED IDENTITY CLIENT ID}");
+}
+else
+{
+    // Local development and testing only
+    DefaultAzureCredentialOptions options = new()
     {
-        options.ClientSecret = 
-            AzureHelper.GetKeyVaultSecret(tenantId, vaultUri, secretName);
-    });
-```
-
-If you wish to control the environment where the preceding code operates, for example to avoid running the code locally because you've opted to use the Secret Manager tool for local development, you can wrap the preceding code in a conditional statement that checks the environment:
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
 
-```csharp
-if (!context.HostingEnvironment.IsDevelopment())
-{
-    ...
+    credential = new DefaultAzureCredential(options);
 }
 ```
 
-In the `AzureAd` section of `appsettings.json`, add the following `VaultUri` and `SecretName` configuration keys and values:
+Where <xref:Microsoft.Identity.Web.MicrosoftIdentityOptions> are set, call `GetKeyVaultSecret` to receive and assign the app's client secret:
 
-```json
-"VaultUri": "{VAULT URI}",
-"SecretName": "{SECRET NAME}"
+```csharp
+msIdentityOptions.ClientSecret = AzureHelper.GetKeyVaultSecret("{VAULT URI}", 
+    credential, "{SECRET NAME}");
 ```
 
-In the preceding example:
+`{MANAGED IDENTITY CLIENT ID}`: The Azure Managed Identity Client ID (GUID).
 
-* The `{VAULT URI}` placeholder is the key vault URI. Include the trailing slash on the URI.
-* The `{SECRET NAME}` placeholder is the secret name.
+`{TENANT ID}`: The directory (tenant) ID. Example: `aaaabbbb-0000-cccc-1111-dddd2222eeee`
 
-Example:
+`{VAULT URI}`: Key vault URI. Include the trailing slash on the URI. Example: `https://contoso.vault.azure.net/`
 
-```json
-"VaultUri": "https://contoso.vault.azure.net/",
-"SecretName": "BlazorWebAppEntra"
-```
+`{SECRET NAME}`: Secret name. Example: `BlazorWebAppEntraClientSecret`
 
 Configuration is used to facilitate supplying dedicated key vaults and secret names based on the app's environmental configuration files. For example, you can supply different configuration values for `appsettings.Development.json` in development, `appsettings.Staging.json` when staging, and `appsettings.Production.json` for the production deployment. For more information, see <xref:blazor/fundamentals/configuration>.
 
@@ -795,7 +790,15 @@ if (builder.Environment.IsProduction())
 else
 {
     // Local development and testing only
-    credential = new DefaultAzureCredential();
+    DefaultAzureCredentialOptions options = new()
+    {
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
+
+    credential = new DefaultAzureCredential(options);
 }
 
 builder.Services.AddDataProtection()
@@ -808,6 +811,8 @@ You can pass any app name to <xref:Microsoft.AspNetCore.DataProtection.DataProte
 
 `{MANAGED IDENTITY CLIENT ID}`: The Azure Managed Identity Client ID (GUID).
 
+`{TENANT ID}`: Tenant ID.
+
 `{BLOB URI}`: Full URI to the key file. The URI is generated by Azure Storage when you create the key file. Do not use a SAS.
 
 `{KEY IDENTIFIER}`: Azure Key Vault key identifier used for key encryption. An access policy allows the application to access the key vault with `Get`, `Unwrap Key`, and `Wrap Key` permissions. The version of the key is obtained from the key in the Entra or Azure portal after it's created. If you enable autorotation of the key vault key, make sure that you use a versionless key identifier in the app's key vault configuration, where no key GUID is placed at the end of the identifier (example: `https://contoso.vault.azure.net/keys/data-protection`).
diff --git a/aspnetcore/security/data-protection/configuration/overview.md b/aspnetcore/security/data-protection/configuration/overview.md
@@ -75,7 +75,15 @@ if (builder.Environment.IsProduction())
 else
 {
     // Local development and testing only
-    credential = new DefaultAzureCredential();
+    DefaultAzureCredentialOptions options = new()
+    {
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
+
+    credential = new DefaultAzureCredential(options);
 }
 
 builder.Services.AddDataProtection()
@@ -86,6 +94,8 @@ builder.Services.AddDataProtection()
 
 `{MANAGED IDENTITY CLIENT ID}`: The Azure Managed Identity Client ID (GUID).
 
+`{TENANT ID}`: Tenant ID.
+
 `{APPLICATION NAME}`: <xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.SetApplicationName%2A> sets the unique name of this app within the data protection system. The value should match across deployments of the app.
 
 `{BLOB URI}`: Full URI to the key file. The URI is generated by Azure Storage when you create the key file. Do not use a SAS.
@@ -401,7 +411,15 @@ if (builder.Environment.IsProduction())
 else
 {
     // Local development and testing only
-    credential = new DefaultAzureCredential();
+    DefaultAzureCredentialOptions options = new()
+    {
+        // Specify the tenant ID to use the dev credentials when running the app locally
+        // in Visual Studio.
+        VisualStudioTenantId = "{TENANT ID}",
+        SharedTokenCacheTenantId = "{TENANT ID}"
+    };
+
+    credential = new DefaultAzureCredential(options);
 }
 
 services.AddDataProtection()
@@ -412,6 +430,8 @@ services.AddDataProtection()
 
 `{MANAGED IDENTITY CLIENT ID}`: The Azure Managed Identity Client ID (GUID).
 
+`{TENANT ID}`: Tenant ID.
+
 `{APPLICATION NAME}`: <xref:Microsoft.AspNetCore.DataProtection.DataProtectionBuilderExtensions.SetApplicationName%2A> sets the unique name of this app within the data protection system. The value should match across deployments of the app.
 
 `{BLOB URI}`: Full URI to the key file. The URI is generated by Azure Storage when you create the key file. Do not use a SAS.
diff --git a/aspnetcore/security/data-protection/implementation/key-storage-providers.md b/aspnetcore/security/data-protection/implementation/key-storage-providers.md
