通过

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

  • 项目

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

应用程序配置可以创建密钥来引用存储在 Key Vault 中的值，以帮助你结合使用这两个服务。 当应用程序配置创建此类密钥时，它会存储 Key Vault 值的 URI，而不是值本身。

应用程序使用应用程序配置客户端提供程序检索 Key Vault 引用，就如同检索应用程序配置中存储的任何其他密钥一样。 在这种情况下，存储在应用程序配置中的值是引用 Key Vault 中的值的 URI。 这些值不是 Key Vault 值或凭据。 由于客户端提供程序将密钥识别为 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 应用。

创建保管库

  1. 选择 Azure 门户左上角的“创建资源”选项：

    屏幕截图显示 Azure 门户中的“创建资源”选项。

  2. 在搜索框中键入“密钥保管库”，然后从下拉列表中选择“密钥保管库” 。

  3. 在结果列表中，选择左侧的“Key Vault” 。

  4. 在“Key Vault”中选择“添加”。

  5. 在“创建 Key Vault”中的右侧提供以下信息：

    • 选择“订阅”以选择订阅。
    • 在“资源组”中，选择现有的资源组名称，或者选择“新建”并输入资源组名称 。
    • 在“Key Vault 名称”中，必须输入唯一的名称。
    • 在“区域”下拉列表中，选择一个位置。

  6. 将“创建 Key Vault”的其他选项保留默认值。

  7. 单击“查看 + 创建”。

  8. 系统将验证并显示你输入的数据。 单击“创建”。

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

向 Key Vault 添加机密

只需执行几个额外的步骤即可将机密添加到保管库。 在本例中，我们将添加一条消息，用于测试 Key Vault 检索功能。 此消息名为 Message，我们将在其中存储“Hello from Key Vault”值。

  1. 在 Key Vault 属性页中选择“机密” 。
  2. 选择“生成/导入”。
  3. 在“创建机密”窗格中输入以下值：
    • 上传选项：输入 Manual。
    • Name：输入 Message。
    • 值：输入 Hello from Key Vault。
  4. 将“创建机密”的其他属性保留默认值。
  5. 选择“创建” 。

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

  1. 登录 Azure 门户。 选择“所有资源”，然后选择在快速入门中创建的应用程序配置存储实例 。

  2. 选择“配置资源管理器”。

  3. 选择“+ 创建”>“Key Vault 引用”，然后指定以下值：

    • 密钥：选择“TestApp:Settings:KeyVaultMessage”。
    • 标签：将此值保留空白。
    • “订阅”、“资源组”和“Key Vault”： 输入上一部分在 Key Vault 中创建的值相对应的值。
    • 机密：选择在上一部分创建的名为 Message 的机密。

用于创建新密钥保管库引用的窗体的屏幕截图

更新代码以使用 Key Vault 引用

  1. 运行以下命令，添加对所需 NuGet 包的引用：

    dotnet add package Azure.Identity

  2. 打开 Program.cs，添加对以下所需包的引用：

    using Azure.Identity;

  3. 通过调用 AddAzureAppConfiguration 方法使用应用程序配置。 包括 ConfigureKeyVault 选项，并使用 SetCredential 方法将正确凭据传递到 Key Vault。

    var builder = WebApplication.CreateBuilder(args);

// Retrieve the connection string
string connectionString = builder.Configuration.GetConnectionString("AppConfig");

// Load configuration from Azure App Configuration
builder.Configuration.AddAzureAppConfiguration(options =>
{
    options.Connect(connectionString);

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

    提示

    如果有多个 Key Vault，则所有 Key Vault 都使用同一凭据。 如果 Key Vault 需要不同凭据，可以使用 AzureAppConfigurationKeyVaultOptions 类中的 Register 或 SetSecretResolver 方法来进行设置。

  4. 在初始化与“应用配置”服务的连接时，你已通过调用 ConfigureKeyVault 方法设置了与 Key Vault 的连接。 初始化之后，可以像访问普通的应用程序配置密钥值一样访问 Key Vault 引用值。

    若要了解此过程的运作方式，请打开“视图”>“主页”文件夹中的 Index.cshtml。 将其内容替换为以下代码：

    @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 的值。

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

Azure 应用程序配置不会访问你的密钥保管库。 应用将直接读取密钥保管库，因此你需要为应用授予对密钥保管库中机密的访问权限。 这样，机密始终会保留在你的应用中。 可以使用密钥保管库访问策略或 Azure 基于角色的访问控制来授予访问权限。

在上面的代码中使用 DefaultAzureCredential。 它是一个自动尝试多个凭据类型（如 EnvironmentCredential、ManagedIdentityCredential、SharedTokenCacheCredential 和 VisualStudioCredential）的聚合令牌凭据。 有关详细信息，请参阅 DefaultAzureCredential 类。 可以显式将 DefaultAzureCredential 替换为任何凭据类型。 但是，通过使用 DefaultAzureCredential，你可以本地和 Azure 环境中运行相同的代码。 例如，你可以授予对密钥保管库的凭据访问权限。 使用 Visual Studio 进行本地开发时，DefaultAzureCredential 将自动回退到 SharedTokenCacheCredential 或 VisualStudioCredential。

或者，可以设置 AZURE_TENANT_ID、AZURE_CLIENT_ID 和 AZURE_CLIENT_SECRET 环境变量，然后，DefaultAzureCredential 将使用你通过 EnvironmentCredential 获取的客户端机密对密钥保管库进行身份验证。 将应用部署到启用了托管标识的 Azure 服务（例如 Azure 应用服务、Azure Kubernetes 服务或 Azure 容器实例）后，为 Azure 服务的托管标识授予对密钥保管库的访问权限。 当应用在 Azure 中运行时，DefaultAzureCredential 会自动使用 ManagedIdentityCredential。 可以使用同一个托管标识对应用程序配置和密钥保管库进行身份验证。 有关详细信息，请参阅如何使用托管标识访问应用程序配置。

在本地生成并运行应用

  1. 要通过使用 .NET CLI 生成应用，请在命令 Shell 中运行以下命令：

    dotnet build

  2. 完成生成后，使用以下命令在本地运行 Web 应用：

    dotnet run

  3. 启动浏览器窗口并转到 http://localhost:5000，即本地托管的 Web 应用的默认 URL。

    快速入门 - 本地应用启动

清理资源

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

重要

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

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

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

后续步骤

在本教程中，你已在应用程序配置中创建一个引用密钥保管库中存储的机密的密钥。 若要了解如何自动从密钥保管库重载机密和证书，请继续学习下一篇教程：

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

若要了解如何使用托管标识来简化对应用程序配置和密钥保管库的访问，请参阅以下教程：

托管标识集成