.NET AspireAzure Key Vault integración

Incluye: Integración de alojamiento —&— Client integración

Azure Key Vault es un servicio en la nube para almacenar y acceder a secretos de forma segura. La integración de .NET AspireAzure Key Vault permite conectarse a instancias de Azure Key Vault desde las aplicaciones de .NET.

Integración de hospedaje

La integración de alojamiento Azure Key Vault modela un recurso de Key Vault como el tipo AzureKeyVaultResource. Para acceder a este tipo y a las API para expresarlas dentro de su proyecto app host, instale el paquete 📦Aspire.Hosting.Azure.KeyVault NuGet:

dotnet add package Aspire.Hosting.Azure.KeyVault

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

Para obtener más información, consulte dotnet add package (Agregar paquete ) o Manage package dependencies in applications (Administrar dependencias de paquetes en .NET aplicaciones).

Agregar Azure Key Vault recurso

En el proyecto host de la aplicación, llame a AddAzureKeyVault en la instancia del constructor para agregar un recurso 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...

El método WithReference configura una conexión en el ExampleProject denominado "key-vault".

Bicep generado por el aprovisionamiento

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir Azure recursos. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar la aplicación, el Bicep generado se muestra junto con el archivo de manifiesto. Cuando añades un recurso Azure Key Vault, se genera el siguiente 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

El módulo Bicep anterior proporciona un recurso Azure Key Vault. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

@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
}

El Bicep generado es un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo que los cambios deben realizarse a través de las API de aprovisionamiento de C# para garantizar que se reflejen en los archivos generados.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado proporcionando una API fluida para configurar los recursos Azure mediante la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el sku, RBAC, tags, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de 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");
    });

El código anterior:

• Encadena una llamada a API ConfigureInfrastructure:
  • El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
  • Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
  • Se recupera el único recurso KeyVaultService.
  • La propiedad Sku se establece en una nueva instancia KeyVaultSku.
  • La propiedad KeyVaultProperties.EnableRbacAuthorization se configura como true.
  • Se agrega una etiqueta al recurso con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso de Key Vault. Para obtener más información, vea Azure.Provisioning.KeyVault y Azure. Personalización del aprovisionamiento.

Conexión a una instancia de Azure Key Vault existente

Es posible que tenga una existente instancia de AI Key Vault Azure a la cual desee conectarse. Puede encadenar una llamada para anotar que su AzureKeyVaultResource es un recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingKeyVaultName = builder.AddParameter("existingKeyVaultName");
var existingKeyVaultResourceGroup = builder.AddParameter("existingKeyVaultResourceGroup");

var keyvault = builder.AddAzureKeyVault("ke-yvault")
                    .AsExisting(existingKeyVaultName, existingKeyVaultResourceGroup);

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

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

Para obtener más información sobre cómo tratar Azure Key Vault los recursos como recursos existentes, consulte Uso de recursos existentesAzure.

Integración con Client

Para comenzar con la integración de cliente .NET AspireAzure Key Vault, instale el paquete 📦Aspire.AzureSecurity.KeyVault NuGet en el proyecto que consume el cliente, es decir, el proyecto para la aplicación que utiliza el cliente Azure Key Vault.

dotnet add package Aspire.Azure.Security.KeyVault

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

La integración de cliente proporciona dos maneras de acceder a los secretos desde Azure Key Vault:

• Agregue secretos a la configuración de la aplicación mediante el IConfiguration o el patrón IOptions<T>.
• Use un SecretClient para recuperar secretos a petición.

Adición de secretos a la configuración

En el archivo Program.cs de su proyecto consumidor de clientes, llama al método de extensión AddAzureKeyVaultSecrets en el IConfiguration para añadir los secretos como parte de la configuración de su aplicación. El método toma un parámetro de nombre de conexión.

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

A continuación, puede recuperar un valor de configuración basado en secretos a través de las API normales IConfiguration, o incluso mediante la vinculación a clases fuertemente tipadas con el patrón de opciones. Para recuperar un secreto de una clase de servicio de ejemplo que se ha registrado con el contenedor de inserción de dependencias, tenga en cuenta los fragmentos de código siguientes:

Recuperar instancia IConfiguration

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

El ejemplo anterior asume que también has registrado la instancia IConfiguration para inyección de dependencias. Para obtener más información, consulte Inyección de dependencias en .NET.

Recuperar instancia IOptions<T>

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

En el ejemplo anterior se supone que ha configurado una clase SecretOptions para su uso con el patrón de opciones. Para obtener más información, vea Patrón de opciones en .NET.

Los parámetros de API de AddAzureKeyVaultSecrets adicionales están disponibles opcionalmente para los escenarios siguientes:

• Action<AzureSecurityKeyVaultSettings>? configureSettings: Para configurar algunas o todas las opciones en línea.
• Action<SecretClientOptions>? configureClientOptions: Para configurar SecretClientOptions en línea.
• AzureKeyVaultConfigurationOptions? options: Para configurar AzureKeyVaultConfigurationOptions en línea.

Agregar un Azure cliente secreto

Como alternativa, puede usar el SecretClient directamente para recuperar los secretos a petición. Esto requiere una API de registro ligeramente diferente.

En el archivo Program.cs de su proyecto consumidor de clientes, llame a la extensión AddAzureKeyVaultClient en la instancia IHostApplicationBuilder para registrar un SecretClient para su uso a través del contenedor de inyección de dependencias.

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

Después de añadir el SecretClient al compilador, puede obtener la instancia SecretClient utilizando la inyección de dependencia. Por ejemplo, para recuperar el cliente de un servicio de ejemplo, definalo como parámetro de constructor y asegúrese de que la clase ExampleService está registrada con el contenedor de inserción de dependencias:

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

Para obtener más información sobre la inserción de dependencias, consulte .NET Inserción de dependencias.

Adición de un cliente de Azure Key Vault con clave

Puede haber situaciones en las que quiera registrar varias instancias de SecretClient con nombres de conexión diferentes. Para registrar clientes de Azure Key Vault con clave, llame al método AddKeyedAzureKeyVaultClient:

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

Luego puede recuperar las instancias SecretClient usando inyección de dependencias. Por ejemplo, para recuperar el cliente de un servicio de ejemplo:

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

Para obtener más información sobre los servicios con claves, consulte .NET Inserción de dependencias: Servicios con claves.

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": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Diagnostics": {
              "ApplicationId": "myapp"
            }
          }
        }
      }
    }
  }
}

Para obtener el esquema completo Azure Key Vault de integración de clientes JSON, consulte Aspire.Azure.Security.KeyVault/ConfigurationSchema.json.

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.

Utilice delegados en línea

También puede pasar el delegado Action<AzureSecurityKeyVaultSettings> para configurar algunas o todas las opciones en línea, por ejemplo, para configurar el AzureSecurityKeyVaultSettings.VaultUri:

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

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

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

Opciones de configuración

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

Client comprobaciones de estado de la integración

De forma predeterminada, las integraciones de cliente .NET.NET Aspire tienen las comprobaciones de estado habilitadas para todos los servicios. Del mismo modo, muchas .NET.NET Aspireintegraciones de hosting también permiten puntos finales de comprobación de estado. Para obtener más información, consulte:

• .NET comprobaciones de estado de la aplicación en C#
• Comprobaciones de mantenimiento en ASP.NET Core

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

• Añade la comprobación de estado AzureKeyVaultSecretsHealthCheck, que intenta conectarse y consultar la Key Vault
• Se integra con el punto de conexión HTTP /health, que especifica que todas las comprobaciones de estado registradas deben superarse para que la aplicación se considere lista para aceptar tráfico

Observabilidad y telemetría

.NET.NET Aspire las 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 y la telemetría de integración, consulte .NET.NET Aspire La introducción a las integraciones. 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

Seguimiento

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

• Azure Key Vault Docs
• Vídeo: Introducción a Azure Key Vault y .NET Aspire
• .NET AspireAzure Introducción a las integraciones
• .NET.NET Aspire Introducción a las integraciones
• .NET Aspire GitHub repositorio