.NET 9 Web应用如何通过@Microsoft.KeyVault解析KeyVault敏感配置？

Azure Functions的@Microsoft.KeyVault自动解析是宿主内置功能，普通.NET Web应用需要通过以下两种方案实现类似效果：

方案一：使用Azure App Configuration密钥引用（推荐，最贴近Functions体验） #

这种方式依赖Azure App Configuration服务来自动解析密钥引用，支持跨环境统一管理配置：

1. 配置Azure资源

   • 创建Azure App Configuration实例，添加配置项（如ElasticPassword），值填写Key Vault引用格式：

     @Microsoft.KeyVault(SecretUri="https://你的密钥库名称.vault.azure.net/secrets/密钥名称/版本号")
     

     或简化格式：

     @Microsoft.KeyVault(VaultName="你的密钥库名称",SecretName="密钥名称")
     

   • 给App Configuration的托管标识分配Key Vault的Secret Get权限

2. 项目配置

   • 安装NuGet包：Microsoft.Azure.AppConfiguration.AspNetCore、Azure.Identity
   • 修改Program.cs，添加Azure App Configuration并启用密钥解析：

     var builder = WebApplication.CreateBuilder(args);
     
     builder.Configuration.AddAzureAppConfiguration(options =>
     {
         options.Connect("你的App Configuration连接字符串")
                .ConfigureKeyVault(kvOpts =>
                {
                    kvOpts.SetCredential(new DefaultAzureCredential());
                });
     });
     
     // 后续服务和中间件配置...
     builder.Services.AddControllers();
     
     var app = builder.Build();
     app.MapControllers();
     app.Run();
     

3. 本地开发验证

   • 确保已通过Azure CLI登录（az login），或设置环境变量AZURE_CLIENT_ID、AZURE_CLIENT_SECRET、AZURE_TENANT_ID使用服务主体

方案二：自定义配置处理器解析本地appsettings.json指令 #

如果不需要依赖Azure App Configuration，可直接编写逻辑解析本地JSON中的指令：

1. 安装依赖包

   • 安装NuGet包：Azure.Security.KeyVault.Secrets、Azure.Identity

2. 添加解析逻辑到Program.cs

   var builder = WebApplication.CreateBuilder(args);
   
   // 注册Key Vault客户端
   builder.Services.AddSingleton(sp =>
   {
       var vaultUri = new Uri("https://你的密钥库名称.vault.azure.net/");
       return new SecretClient(vaultUri, new DefaultAzureCredential());
   });
   
   // 构建初始配置
   var configRoot = builder.Configuration.Build();
   var secretClient = builder.Services.BuildServiceProvider().GetRequiredService<SecretClient>();
   
   // 解析所有Key Vault指令并存储结果
   var resolvedSecrets = new Dictionary<string, string>();
   ResolveKeyVaultReferences(configRoot, secretClient, resolvedSecrets).Wait();
   
   // 将解析后的密钥添加到配置（优先级高于原始JSON）
   builder.Configuration.AddInMemoryCollection(resolvedSecrets);
   
   // 后续服务和中间件配置...
   builder.Services.AddControllers();
   
   var app = builder.Build();
   app.MapControllers();
   app.Run();
   
   // 递归遍历配置项解析指令
   static async Task ResolveKeyVaultReferences(IConfiguration config, SecretClient secretClient, Dictionary<string, string> resolvedSecrets)
   {
       foreach (var child in config.GetChildren())
       {
           if (!string.IsNullOrEmpty(child.Value) && child.Value.StartsWith("@Microsoft.KeyVault(", StringComparison.OrdinalIgnoreCase))
           {
               resolvedSecrets[child.Path] = await ParseKeyVaultReference(child.Value, secretClient);
           }
           await ResolveKeyVaultReferences(child, secretClient, resolvedSecrets);
       }
   }
   
   // 解析指令字符串并获取密钥值
   static async Task<string> ParseKeyVaultReference(string reference, SecretClient secretClient)
   {
       var inner = reference.Substring(19, reference.Length - 20);
       var parameters = inner.Split(',')
                             .Select(p => p.Trim())
                             .ToDictionary(p => p.Split('=')[0], p => p.Split('=')[1].Trim('"'));
   
       if (parameters.TryGetValue("SecretUri", out var uriStr))
       {
           var secret = await secretClient.GetSecretAsync(new Uri(uriStr));
           return secret.Value.Value;
       }
       else if (parameters.TryGetValue("VaultName", out var vaultName) && parameters.TryGetValue("SecretName", out var secretName))
       {
           if (secretClient.VaultUri.Host.Equals($"{vaultName}.vault.azure.net", StringComparison.OrdinalIgnoreCase))
           {
               var secret = await secretClient.GetSecretAsync(secretName);
               return secret.Value.Value;
           }
           else
           {
               var newClient = new SecretClient(new Uri($"https://{vaultName}.vault.azure.net/"), new DefaultAzureCredential());
               var secret = await newClient.GetSecretAsync(secretName);
               return secret.Value.Value;
           }
       }
       throw new InvalidOperationException($"无效的Key Vault引用格式: {reference}");
   }
   

常见问题排查 #

• 身份验证失败：本地开发确保Azure CLI已登录，Azure部署使用托管标识并配置Key Vault权限
• 指令格式错误：检查是否符合@Microsoft.KeyVault(SecretUri="xxx")或@Microsoft.KeyVault(VaultName="xxx",SecretName="xxx")格式
• 配置优先级问题：确保解析后的配置源（如内存配置、Azure App Configuration）添加顺序在appsettings.json之后，保证覆盖原始指令字符串

内容的提问来源于stack exchange，提问作者advapi