.NET Aspire Azure Key Vault 集成

2025-04-10

包含： - Client 集成

Azure Key Vault 是一项云服务，用于安全地存储和访问机密。 .NET Aspire Azure Key Vault 集成使你能够从 Azure Key Vault 应用程序连接到 .NET 实例。

托管集成

托管集成 Azure Key Vault 将 Key Vault 资源建模为 AzureKeyVaultResource 类型。若要访问此类型和 API 以在应用主机项目中表达它们，请安装 📦Aspire.Hosting.Azure.KeyVault NuGet 包：

.NET 命令行界面
包引用

dotnet add package Aspire.Hosting.Azure.KeyVault

<PackageReference Include="Aspire.Hosting.Azure.KeyVault"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖项。

添加 Azure Key Vault 资源

在应用主机项目中，对生成器实例调用 AddAzureKeyVault 以添加 Azure Key Vault 资源：

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddAzureKeyVault("key-vault");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(keyVault);

// After adding all resources, run the app...

WithReference 方法在 ExampleProject 中配置一个名为 "key-vault"的连接。

重要

默认情况下，AddAzureKeyVault 配置 Key Vault 管理员内置角色。

提示

调用 AddAzureKeyVault时，它会隐式调用 AddAzureProvisioning，这增加了在应用启动期间动态生成 Azure 资源的支持。应用程序必须配置相应的订阅和位置。有关详细信息，请参阅本地预配：配置。

由预配生成的 Bicep

如果你不熟悉 Bicep，它是一种领域专用语言，用于定义 Azure 资源。使用 .NET.NET Aspire，您不需要手动编写 Bicep，预配 API 会为您自动生成 Bicep。发布应用时，生成的 Bicep 文件将会与清单文件一同输出。添加 Azure Key Vault 资源时，会生成以下的 Bicep：

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' = {
  name: take('keyvault-${uniqueString(resourceGroup().id)}', 24)
  ___location: ___location
  properties: {
    tenantId: tenant().tenantId
    sku: {
      family: 'A'
      name: 'standard'
    }
    enableRbacAuthorization: true
  }
  tags: {
    'aspire-resource-name': 'key-vault'
  }
}

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

前述的 Bicep 是一个配置 Azure Key Vault 资源的模块。此外，在单独的模块中为 Azure 资源创建角色分配：

@description('The ___location for the resource(s) to be deployed.')
param ___location string = resourceGroup().___location

param key_vault_outputs_name string

param principalType string

param principalId string

resource key_vault 'Microsoft.KeyVault/vaults@2023-07-01' existing = {
  name: key_vault_outputs_name
}

resource key_vault_KeyVaultSecretsUser 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '4633458b-17de-408a-b874-0445c86b69e6')
    principalType: principalType
  }
  scope: key_vault
}

生成的 Bicep 作为起点，受 C# 中资源配置基础设施更改的影响。直接对 Bicep 文件的自定义项所做的更改将被覆盖，因此请通过 C# 预配 API 进行更改，以确保它们反映在生成的文件中。

自定义预配基础结构

所有 .NET AspireAzure 资源都是 AzureProvisioningResource 类型的子类。此类型通过提供一个流畅的 API，使用 Azure API 对 ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) 资源进行配置，从而实现对生成的 Bicep 的自定义。例如，可以配置 sku、RBAC、tags等。以下示例演示如何自定义 Azure Key Vault 资源：

builder.AddAzureKeyVault("key-vault")
    .ConfigureInfrastructure(infra =>
    {
        var keyVault = infra.GetProvisionableResources()
                            .OfType<KeyVaultService>()
                            .Single();

        keyVault.Properties.Sku = new()
        {
            Family = KeyVaultSkuFamily.A,
            Name = KeyVaultSkuName.Premium,
        };
        keyVault.Properties.EnableRbacAuthorization = true;
        keyVault.Tags.Add("ExampleKey", "Example value");
    });

前面的代码：

将一个调用链接至 ConfigureInfrastructure API：
- infra 参数是 AzureResourceInfrastructure 类型的实例。
- 通过调用 GetProvisionableResources() 方法检索可预配资源。
- 单个 KeyVaultService 资源已被检索。
- Sku 属性设置为新的 KeyVaultSku 实例。
- KeyVaultProperties.EnableRbacAuthorization 属性设置为 true。
- 标记将添加到资源中，其键为 ExampleKey，值为 Example value。

还有更多配置选项可用于自定义 Key Vault 资源。有关详细信息，请参阅 Azure.Provisioning.KeyVault 和 Azure。预配自定义。

连接到现有 Azure Key Vault 实例

你可能有一个现有的 Azure Key Vault 实例，你想连接到它。您可以向应用程序主机添加连接字符串，而无需创建新的 Azure Key Vault 资源。若要向现有 Azure Key Vault 资源添加连接，请调用 AddConnectionString 方法：

var builder = DistributedApplication.CreateBuilder(args);

var keyVault = builder.AddConnectionString("key-vault");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(keyVault);

// After adding all resources, run the app...

注释

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

连接字符串是在应用主机的配置中配置的，通常在部分下的 ConnectionStrings下。应用主机将此连接字符串作为环境变量注入到所有依赖资源中，例如：

{
  "ConnectionStrings": {
    "key-vault": "https://{account_name}.vault.azure.net/"
  }
}

依赖资源可以通过调用 GetConnectionString 方法并传递连接名称作为参数来访问注入的连接字符串，在本例中为 "key-vault"。 GetConnectionString API 是 IConfiguration.GetSection("ConnectionStrings")[name]的简称。

Client 集成

若要开始 .NET AspireAzure Key Vault 客户端集成，请在客户端所使用的项目中安装 📦Aspire.Azure.Security.KeyVault NuGet 包，即在使用 Azure Key Vault 客户端的应用程序的项目中。

.NET 命令行界面
包引用

dotnet add package Aspire.Azure.Security.KeyVault

<PackageReference Include="Aspire.Azure.Security.KeyVault"
                  Version="*" />

客户端集成提供两种方法来从 Azure Key Vault访问密钥。

使用 IConfiguration 或 IOptions<T> 模式将机密添加到应用配置。
使用 SecretClient 按需检索机密。

将机密添加到配置

在客户端使用项目的 Program.cs 文件中，对 AddAzureKeyVaultSecrets 调用 IConfiguration 扩展方法，将机密添加为应用的配置的一部分。该方法采用连接名称参数。

builder.Configuration.AddAzureKeyVaultSecrets(connectionName: "key-vault");

注释

AddAzureKeyVaultSecrets API 名称引起了一点混淆。该方法用于根据给定的连接名称配置 SecretClient，它不用于向配置添加机密。

提示

connectionName 参数必须与在应用主机项目中添加 Azure Key Vault 资源时使用的名称匹配。有关详细信息，请参阅添加 Azure Key Vault 资源。

然后，可以通过普通的 IConfiguration API 检索基于机密的配置值，甚至可以通过将其绑定到强类型的类来使用选项模式。若要从已向依赖项注入容器注册的示例服务类检索机密，请考虑以下代码片段：

检索 `IConfiguration` 实例

public class ExampleService(IConfiguration configuration)
{
    // Use configuration...
    private string _secretValue = configuration["SecretKey"];
}

前面的示例假定你还注册了 IConfiguration 实例用于依赖项的注入。有关详细信息，请参阅 .NET中的依赖关系注入。

检索 `IOptions<T>` 实例

public class ExampleService(IOptions<SecretOptions> options)
{
    // Use options...
    private string _secretValue = options.Value.SecretKey;
}

前面的示例假定你已配置 SecretOptions 类以用于选项模式。有关详细信息，请参阅 .NET中的选项模式。

以下方案可以选择使用其他 AddAzureKeyVaultSecrets API 参数：

Action<AzureSecurityKeyVaultSettings>? configureSettings：设置一些或全部内嵌选项。
Action<SecretClientOptions>? configureClientOptions：设置内联SecretClientOptions。
AzureKeyVaultConfigurationOptions? options：将 AzureKeyVaultConfigurationOptions 配置为内联方式。

添加 Azure 机密客户端

或者，你可以直接使用 SecretClient 来按需检索机密。这需要略有不同的注册 API。

在客户端使用项目的 Program.cs 文件中，调用 AddAzureKeyVaultClient 实例上的 IHostApplicationBuilder 扩展，以注册 SecretClient，以便通过依赖项注入容器使用。

builder.AddAzureKeyVaultClient(connectionName: "key-vault");

提示

connectionName 参数必须与在应用主机项目中添加 Azure Key Vault 资源时使用的名称匹配。有关详细信息，请参阅添加 Azure Key Vault 资源。

将 SecretClient 添加到生成器后，可以使用依赖项注入获取 SecretClient 实例。例如，若要从示例服务检索客户端，请将其定义为构造函数参数，并确保 ExampleService 类注册到依赖项注入容器：

public class ExampleService(SecretClient client)
{
    // Use client...
}

有关依赖项注入的详细信息，请参阅 .NET 依赖项注入。

添加有密钥的 Azure Key Vault 客户端

在某些情况下，可能需要使用不同的连接名称注册多个 SecretClient 实例。若要注册密钥 Azure Key Vault 客户端，请调用 AddKeyedAzureKeyVaultClient 方法：

builder.AddKeyedAzureKeyVaultClient(name: "feature-toggles");
builder.AddKeyedAzureKeyVaultClient(name: "admin-portal");

然后，可以使用依赖项注入检索 SecretClient 实例。例如，若要从示例服务检索客户端：

public class ExampleService(
    [FromKeyedServices("feature-toggles")] SecretClient featureTogglesClient,
    [FromKeyedServices("admin-portal")] SecretClient adminPortalClient)
{
    // Use clients...
}

有关密钥服务的详细信息，请参阅 .NET 依赖项注入：键式服务。

配置

.NET Aspire Azure Key Vault 集成提供了多个选项，用于根据项目的要求和约定配置 SecretClient。

使用配置提供程序

.NET Aspire Azure Key Vault 集成支持 Microsoft.Extensions.Configuration。它使用 AzureSecurityKeyVaultSettings 密钥从 appsettings.json 或其他配置文件中加载 Aspire:Azure:Security:KeyVault。

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

有关完整的 Azure Key Vault 客户端集成方案 JSON 架构，请参阅 Aspire。Azure。Security.KeyVault/ConfigurationSchema.json。

如果在 Aspire:Azure:Security:KeyVault 文件的 appsettings.json 节中设置了配置，只需调用方法 AddAzureKeyVaultSecrets 即可不传递任何参数。

使用内联委托

您还可以使用 Action<AzureSecurityKeyVaultSettings> 委托来直接在代码中设置一些或全部选项，例如设置 AzureSecurityKeyVaultSettings.VaultUri：

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureSettings: settings => settings.VaultUri = new Uri("KEY_VAULT_URI"));

你还可以通过 SecretClientOptions 委托来设置 Action<SecretClientOptions>，这是 AddAzureKeyVaultSecrets 方法的可选参数。例如，将 KeyClientOptions.DisableChallengeResourceVerification 设置为 ID 来标识客户端：

builder.AddAzureKeyVaultSecrets(
    connectionName: "key-vault",
    configureClientOptions: options => options.DisableChallengeResourceVerification = true))

配置选项

以下可配置选项通过 AzureSecurityKeyVaultSettings 类公开：

名字	描述
AzureSecurityKeyVaultSettings.Credential	用于对 Azure Key Vault进行身份验证的凭据。
AzureSecurityKeyVaultSettings.DisableHealthChecks	一个布尔值，该值指示是否禁用 Key Vault 运行状况检查。
AzureSecurityKeyVaultSettings.DisableTracing	一个布尔值，用于指示 OpenTelemetry 跟踪是否被禁用。
AzureSecurityKeyVaultSettings.VaultUri	客户端所使用的保管库的 URI。在 Azure 门户中显示为“DNS 名称”。

Client 整合健康检查

默认情况下，所有服务的.NET.NET Aspire客户端集成都启用了状态检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# .NET 应用运行状况检查
健康检查在 ASP.NET Core

.NET Aspire Azure Key Vault 集成包括以下健康监测：

添加AzureKeyVaultSecretsHealthCheck健康检查，该检查尝试连接并查询Key Vault。
与 /health HTTP 终结点集成，该终结点指定所有已注册的健康检查都必须通过，应用才会被视为准备好接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、追踪和指标配置，这些配置有时被称为可观测性支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Azure Key Vault 集成使用以下日志类别：

Azure.Core
Azure.Identity

追踪

.NET Aspire Azure Key Vault 集成将使用 OpenTelemetry 生成以下跟踪活动：

Azure.Security.KeyVault.Secrets.SecretClient

指标

由于 .NET Aspire SDK 的限制，Azure Key VaultAzure 集成目前目前不支持指标。

通过