Compartir a través de

integración de .NET AspireAzure Key Vault

  • Artículo

En este artículo, aprenderá a usar la integración de .NET AspireAzure Key Vault. La biblioteca de integración de Aspire.Azure.Key.Vault se utiliza para registrar un SecretClient en el contenedor DI para conectarse a Azure Key Vault. También habilita las comprobaciones de estado, el registro y la telemetría correspondientes.

Comenzar

Para empezar a trabajar con la integración de .NET AspireAzure Key Vault, instale el paquete NuGet de 📦Aspire.Azure.Security.KeyVault en el proyecto consumidor client, es decir, el proyecto de la aplicación que utiliza el Azure Key Vaultclient.

dotnet add package Aspire.Azure.Security.KeyVault

Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.

Ejemplo de uso

En las secciones siguientes se describen varios usos de ejemplo.

Adición de secretos a la configuración

En el archivo Program.cs del proyecto que consume client, utilice la extensión AddAzureKeyVaultSecrets para agregar los secretos en el Azure Key Vault a la configuración de la aplicación. El método toma un parámetro de nombre de conexión.

builder.Configuration.AddAzureKeyVaultSecrets("secrets");

A continuación, puede recuperar un secreto a través de las API de IConfiguration normales. Por ejemplo, para recuperar un secreto de un servicio:

public class ExampleService(IConfiguration configuration)
{
    string secretValue = configuration["secretKey"];
    // Use secretValue ...
}

Uso de SecretClient

Como alternativa, puede usar un SecretClient para recuperar los secretos bajo demanda. En el archivo Program.cs de su proyecto que consume client, llame a la extensión AddAzureKeyVaultClient para registrar un SecretClient para su uso a través del contenedor de inyección de dependencias.

builder.AddAzureKeyVaultClient("secrets");

A continuación, puede recuperar la instancia de SecretClient mediante la inyección de dependencias. Por ejemplo, para recuperar el client de un servicio:

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

Uso del host de la aplicación

Para agregar compatibilidad con el hospedaje de a la , instale el . Hospitalidad.. KeyVault paquete NuGet en el proyecto host de la aplicación de .

dotnet add package Aspire.Hosting.Azure.KeyVault

En el proyecto host de la aplicación, registre la integración de Azure Key Vault y consuma el servicio mediante los métodos siguientes:

var builder = DistributedApplication.CreateBuilder(args);

var secrets = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureKeyVault("secrets")
    : builder.AddConnectionString("secrets");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(secrets)

El código anterior agrega condicionalmente el recurso Azure Key Vault al proyecto en función del contexto de ejecución. Si el host de la aplicación se está ejecutando en modo de publicación, el recurso se agrega; de otro modo, se agrega la cadena de conexión a un recurso existente.

Configuración

La integración de .NET AspireAzure Key Vault proporciona varias opciones para configurar el SecretClient en función de los requisitos y convenciones del proyecto.

Uso de proveedores de configuración

La integración de .NET AspireAzure Key Vault admite Microsoft.Extensions.Configuration. Carga el AzureSecurityKeyVaultSettings desde appsettings.json u otros archivos de configuración usando la clave Aspire:Azure:Security:KeyVault.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "VaultUri": "YOUR_VAULT_URI",
          "DisableHealthChecks": false,
          "DisableTracing": true,
          "ClientOptions": {
            "DisableChallengeResourceVerification": true
          }
        }
      }
    }
  }
}

Si ha configurado las configuraciones en la sección Aspire:Azure:Security:KeyVault del archivo appsettings.json, simplemente puede llamar al método AddAzureKeyVaultSecrets sin pasar ningún parámetro.

Use delegados en línea

También puede pasar el delegado de Action<AzureSecurityKeyVaultSettings> para configurar directamente algunas o todas las opciones, por ejemplo, para establecer el VaultUri:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static settings => settings.VaultUri = new Uri("YOUR_VAULTURI"));

Propina

El nombre de la API de AddAzureKeyVaultSecrets ha causado un poco de confusión. El método se usa para configurar el SecretClient y no para agregar secretos a la configuración.

También puede configurar el SecretClientOptions mediante el delegado Action<IAzureClientBuilder<SecretClient, SecretClientOptions>>, que es el segundo parámetro del método AddAzureKeyVaultSecrets. Por ejemplo, para establecer el identificador de KeyClientOptions.DisableChallengeResourceVerification para identificar el client:

builder.AddAzureKeyVaultSecrets(
    "secrets",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.DisableChallengeResourceVerification = true))

Opciones de configuración

Las siguientes opciones configurables se exponen a través de la clase AzureSecurityKeyVaultSettings:

Nombre Descripción
VaultUri Identificador URI de la bóveda en la que funciona el client. Aparece como "Nombre DNS" en el portal de Azure.
Credential Credencial usada para autenticarse en el Azure Key Vault.
DisableHealthChecks Valor booleano que indica si la comprobación de estado de Key Vault está deshabilitada o no.
DisableTracing Valor booleano que indica si el seguimiento de OpenTelemetry está deshabilitado o no.

Comprobaciones de estado

De forma predeterminada, las integraciones de .NET.NET Aspire habilitan las verificaciones de salud de para todos los servicios. Para obtener más información, consulte .NET.NET Aspire integrations overview.

La integración de .NET AspireAzure Key Vault incluye las siguientes verificaciones de salud:

  • Agrega la comprobación de estado AzureKeyVaultSecretsHealthCheck, que intenta conectarse a Key Vault y realizar consultas en él.
  • Se integra con el endpoint HTTP de /health, que especifica que todas las comprobaciones de estado registradas deben aprobarse para que la aplicación se considere lista para aceptar tráfico.

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las funciones de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección de configuración .

Registro

La integración de .NET AspireAzure Key Vault usa las siguientes categorías de registro:

  • Azure.Core
  • Azure.Identity

Rastrear

La integración de .NET AspireAzure Key Vault emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

  • "Azure.Security.KeyVault.Secrets.SecretClient"

Métricas

La integración de .NET AspireAzure Key Vault actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure.

Consulte también