教程：在 ASP.NET Core 应用中使用 Key Vault 引用

2025-10-24

在本教程中，将 Azure 应用配置服务与 Azure Key Vault 一起使用。应用程序配置和 Key Vault 是互补性的服务，大多数应用程序部署中会同时使用两者。

应用程序可以使用应用配置客户端提供程序来检索 Key Vault 引用，就像对应用程序配置中存储的任何其他密钥一样。向应用配置添加 Key Vault 引用时，应用配置将创建一个引用 Key Vault 中存储值的密钥。应用配置存储的值不是 Key Vault 值或凭据。而是引用 Key Vault 中的值的 URI。由于客户端提供程序将密钥识别为 Key Vault 引用，因此它使用 Key Vault 检索其值。

应用程序负责向应用程序配置和 Key Vault 进行适当的身份验证。这两项服务不直接通信。

本教程介绍如何在代码中实现 Key Vault 引用。它基于先决条件中列出的 ASP.NET Core 快速入门中引入的 Web 应用。在继续之前，请完成本快速入门。

你可以使用任何代码编辑器执行本教程中的步骤。例如，Visual Studio Code 是适用于 Windows、macOS 和 Linux 操作系统的跨平台代码编辑器。

在本教程中，你将：

创建一个应用程序配置密钥，用于引用 Key Vault 中存储的值
从 ASP.NET Core Web 应用程序访问此密钥的值。

先决条件

完成使用应用配置创建 ASP.NET Core 应用快速入门。

创建密钥保管库

转到 Azure 门户，然后选择“ 创建资源”。
在搜索框中输入 Key Vault。在结果列表中，选择 Key Vault。
在 Key Vault 页上，选择“ 创建”。
在 “创建密钥保管库 ”页上，输入以下信息：
- 对于订阅：选择订阅。
- 对于 资源组：输入现有资源组的名称，或选择“ 新建 ”并输入资源组名称。
- 对于 密钥库名称：输入唯一名称。
- 对于区域：选择位置。
对于其他选项，请使用默认值。
选择“查看 + 创建”。
系统验证并显示输入后，选择“ 创建”。

目前，只有你的 Azure 帐户有权访问这个新保管库。

向 Key Vault 添加机密

若要在应用中测试 Key Vault 检索，请先执行以下步骤，将机密添加到保管库。添加的机密称为 Message，其值为“Hello from Key Vault”。

在 Key Vault 资源菜单上，选择 “对象>机密”。
选择“生成/导入”。
在 “创建机密 ”对话框中，输入以下值：
- 对于 “上传”选项：输入 “手动”。
- 对于名称：输入消息。
- 对于 机密值：输入 Hello from Key Vault。
对于其他选项，请使用默认值。
选择“创建” 。

将 Key Vault 引用添加到应用程序配置

登录 Azure 门户。选择 “所有资源”，然后选择在快速入门中创建的应用配置存储。
选择 配置资源管理器。
选择 “创建>Key Vault 引用”，然后输入以下值：
- 对于密钥: 输入 TestApp:Settings:KeyVaultMessage。
- 对于标签：将值留空。
- 对于订阅、 资源组和 Key Vault：输入在本教程前面创建密钥保管库时使用的值。
- 对于机密：选择在上一部分创建的名为 “消息 ”的机密。

更新代码以使用 Key Vault 引用

转到包含在快速入门中创建的 ASP.NET Core Web 应用项目的文件夹。
请在命令提示符处运行以下命令。此命令将 Azure.Identity NuGet 包引用添加到项目文件或更新它。
```
dotnet add package Azure.Identity
```
打开 Program.cs。在 using 指令部分中，添加以下行以从 Azure.Identity 命名空间导入类型：
```
using Azure.Identity;
```

在 Program.cs中，将对 AddAzureAppConfiguration 方法的调用替换为以下代码中的调用。更新后的调用包括该 ConfigureKeyVault 选项。此选项使用SetCredential方式传递与您的密钥保管库进行身份验证所需的凭据。

var builder = WebApplication.CreateBuilder(args);

// Retrieve the App Configuration endpoint.
string endpoint = builder.Configuration.GetValue<string>("Endpoints:AppConfiguration")

// Load the configuration from App Configuration.
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(new Uri(endpoint), new DefaultAzureCredential());

    options.ConfigureKeyVault(keyVaultOptions =>
    {
        keyVaultOptions.SetCredential(new DefaultAzureCredential());
    });
});

提示

如果有多个密钥保管库，则系统对所有密钥保管库使用相同的凭据。如果密钥保管库需要不同的凭据，可以使用AzureAppConfigurationKeyVaultOptions类的Register或SetSecretResolver方法进行设置。

若要访问代码中 Key Vault 引用的值，请转到项目中的 Pages 文件夹。打开 Index.cshtml 并将其内容替换为以下代码。上一个块中的代码初始化应用配置连接并设置 Key Vault 连接。因此，在 Index.cshtml 中，可以像访问常规应用配置密钥的值一样访问 Key Vault 引用的值。
```
@page
@using Microsoft.Extensions.Configuration
@inject IConfiguration Configuration

<style>
    body {
        background-color: @Configuration["TestApp:Settings:BackgroundColor"]
    }
    h1 {
        color: @Configuration["TestApp:Settings:FontColor"];
        font-size: @Configuration["TestApp:Settings:FontSize"]px;
    }
</style>

<h1>@Configuration["TestApp:Settings:Message"]
    and @Configuration["TestApp:Settings:KeyVaultMessage"]</h1>
```
此代码使用与访问TestApp:Settings:Message的配置值相同的方法来访问 Key Vault 引用TestApp:Settings:KeyVaultMessage的值。

请授予应用对密钥保管库的访问权限

应用配置无法访问密钥保管库。相反，应用直接从 Key Vault 读取数据，因此需要向应用授予对密钥保管库中机密的访问权限。这样，秘密始终保留在你的应用中。可以使用 Key Vault 访问策略或 Azure 基于角色的访问控制来授予访问权限。

本教程中的代码使用 DefaultAzureCredential 类进行身份验证。此聚合的令牌凭据会自动尝试多种凭据类型，例如EnvironmentCredential，ManagedIdentityCredential和SharedTokenCacheCredentialVisualStudioCredential。有关详细信息，请参阅 DefaultAzureCredential 类。

可以将 DefaultAzureCredential 替换为任何显式凭据类型。但是，使用 DefaultAzureCredential时，代码可以在本地和 Azure 环境中运行。例如，当应用在 Azure 中运行时， DefaultAzureCredential 使用 ManagedIdentityCredential。但是，使用 Visual Studio 进行本地开发时，DefaultAzureCredential会自动回退到SharedTokenCacheCredential或VisualStudioCredential。

或者，可以设置AZURE_TENANT_ID和AZURE_CLIENT_IDAZURE_CLIENT_SECRET环境变量。当你这样做时，DefaultAzureCredential 使用这些变量和 EnvironmentCredential 验证您的密钥保管库。

将应用部署到启用了托管标识的 Azure 服务（例如 Azure 应用服务、Azure Kubernetes 服务或 Azure 容器实例）后，可以授予 Azure 服务访问密钥保管库的托管标识权限。当应用在 Azure 中运行时，DefaultAzureCredential 会自动使用 ManagedIdentityCredential。可以使用同一个托管标识对应用程序配置和密钥保管库进行身份验证。有关详细信息，请参阅使用托管标识访问应用程序配置。

在本地生成并运行应用

若要使用 .NET CLI 生成应用，请在命令提示符处运行以下命令：
```
dotnet build
```
完成生成后，使用以下命令在本地运行 Web 应用：
```
dotnet run
```
在命令的 dotnet run 输出中，找到 Web 应用正在侦听的 URL，例如 http://localhost:5292。打开浏览器并转到该 URL。

网页上的文本包含以下组件：
- 您的应用配置存储中与 TestApp:Settings:Message 键相关联的值
- 密钥保管库中存储的消息的机密值

清理资源

如果不想继续使用本文中创建的资源，请删除此处创建的资源组以避免产生费用。

重要

删除资源组的操作不可逆。将永久删除资源组以及其中的所有资源。请确保不要意外删除错误的资源组或资源。如果在包含要保留的其他资源的资源组中创建了本文的资源，请从相应的窗格中单独删除每个资源，而不是删除该资源组。

登录到 Azure 门户，然后选择“资源组”。
在“按名称筛选”框中，输入资源组的名称。
在结果列表中，选择资源组名称以查看概述。
选择“删除资源组”。
系统会要求确认是否删除资源组。重新键入资源组的名称进行确认，然后选择“删除”。

片刻之后，将会删除该资源组及其所有资源。

后续步骤

自动从密钥保管库重新加载机密和证书

使用托管标识简化对应用配置和 Key Vault 的访问

通过