.NET Aspire Azure Key Vault integración

incluye: integración de hospedaje de e integración de Client

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 APIs para expresarlos en el host de la aplicación del proyecto, instale el paquete NuGet 📦Aspire.Hosting.Azure.KeyVault.

.NET CLI

dotnet add package Aspire.Hosting.Azure.KeyVault

PackageReference

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

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

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".

Importante

De forma predeterminada, AddAzureKeyVault configura un rol integrado administrador de Key Vault .

Propina

Al llamar a AddAzureKeyVault, llama implícitamente a AddAzureProvisioning, que agrega compatibilidad para generar recursos de Azure dinámicamente durante el inicio de la aplicación. La aplicación debe configurar la suscripción y la ubicación adecuadas. Para obtener más información, consulte aprovisionamiento local: Configuración.

Aprovisionamiento generado de Bicep

Si no está familiarizado con Bicep, es un lenguaje específico del dominio para definir los recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar tu aplicación, el Bicep generado se muestra junto al archivo de manifiesto. Al agregar un recurso Azure Key Vault, se genera el siguiente script de Bicep:

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

param principalType string

param principalId string

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

resource key_vault_KeyVaultAdministrator 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(key_vault.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '00482a5a-887f-4fb3-b363-3b7fe8e74483')
    principalType: principalType
  }
  scope: key_vault
}

output vaultUri string = key_vault.properties.vaultUri

Bicep anterior es un módulo que aprovisiona un recurso de Azure Key Vault con los valores predeterminados siguientes:

• location: ubicación del grupo de recursos.
• principalId: el identificador principal del usuario o del principal de servicio.
• principalType: el tipo principal del usuario o del principal de servicio.
• key_vault: recurso de Azure Key Vault:
  • name: un nombre único para el Azure Key Vault.
  • properties: las propiedades Azure Key Vault:
    • tenantId: El identificador de inquilino del Azure Key Vault.
    • sku: la SKU de Azure Key Vault:
      • family: familia SKU.
      • name: el nombre de la SKU.
    • enableRbacAuthorization: valor booleano que indica si el Azure Key Vault tiene habilitada la autorización de control de acceso basado en rol (RBAC).
  • tags: las etiquetas de Azure Key Vault.
• key_vault_KeyVaultAdministrator: La asignación del rol de administrador de Azure Key Vault:
  • name: un nombre único para la asignación de roles.
  • properties: las propiedades de asignación de roles:
    • principalId: El ID principal del usuario o del principal del servicio.
    • roleDefinitionId: el identificador de definición de rol del rol de administrador de Azure Key Vault.
    • principalType: El tipo principal del usuario o del principal del servicio.
  • scope: ámbito de la asignación de roles.
• output: el URI de Azure Key Vault.

El Bicep generado es solo un punto de partida y puede personalizarse para satisfacer sus requisitos específicos.

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 flexible para configurar los recursos de Azure mediante la API de 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 configura en una nueva instancia de 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, consulte Azure.Provisioning.KeyVault y Azure. Personalización del aprovisionamiento.

Conexión a una instancia de Azure Key Vault existente

Es posible que tenga una instancia de Azure Key Vault existente a la que desea conectarse. En lugar de representar un nuevo recurso de Azure Key Vault, puede agregar una cadena de conexión al host de la aplicación. Para agregar una conexión a un recurso de Azure Key Vault existente, llame al método 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...

Nota:

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

La cadena de conexión se configura en la configuración del host de la aplicación, normalmente en secretos de usuario, en la sección ConnectionStrings. El host de la aplicación inserta esta cadena de conexión como una variable de entorno en todos los recursos dependientes, por ejemplo:

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

El recurso dependiente puede acceder a la cadena de conexión insertada llamando al método GetConnectionString y pasando el nombre de conexión como parámetro, en este caso "key-vault". La API de GetConnectionString es una abreviación de IConfiguration.GetSection("ConnectionStrings")[name].

integración Client

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

.NET CLI

dotnet add package Aspire.Azure.Security.KeyVault

PackageReference

<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 del proyecto cliente, utilice el método de extensión AddAzureKeyVaultSecrets en el IConfiguration para agregar los secretos como parte de la configuración de tu aplicación. El método toma un parámetro de nombre de conexión.

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

Nota:

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

Propina

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Azure Key Vault en el proyecto host de la aplicación. Para obtener más información, consulte Agregar Azure Key Vault recurso.

A continuación, puede recuperar un valor de configuración basado en secretos a través de las API de IConfiguration normales o incluso enlazando a clases fuertemente tipadas con el patrón de opciones de . 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"];
}

En el ejemplo anterior se supone que también ha registrado la instancia de IConfiguration para la inyección de dependencias. Para obtener más información, consulte inyección de dependencias en .NET.

Recuperar la 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, consulte patrón de opciones de 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 el SecretClientOptions en línea.
• AzureKeyVaultConfigurationOptions? options: Configurar el AzureKeyVaultConfigurationOptions en línea.

Agregar un cliente secreto de Azure

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 del proyecto que consume el cliente, llame a la extensión AddAzureKeyVaultClient en la instancia de IHostApplicationBuilder para registrar un SecretClient para su uso a través del contenedor de inserción de dependencias.

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

Consejo (if 'Tip' refers to advice)

El parámetro connectionName debe coincidir con el nombre usado al agregar el recurso Azure Key Vault en el proyecto host de la aplicación. Para obtener más información, consulte Agregar Azure Key Vault recurso.

Después de agregar el SecretClient al generador, puede obtener la instancia de SecretClient mediante la inyección de dependencias. 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");

A continuación, puede recuperar las instancias de SecretClient mediante 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 consultar el esquema JSON de integración de cliente Azure Key Vault completo, diríjase a 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.

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 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:

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

Client pruebas 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 hospedaje también habilitan puntos de verificación de estado. Para obtener más información, consulte:

• .NET comprobaciones de estado de la aplicación en C#
• Controles de salud en ASP.NET Core

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 superarse 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

Rastreo

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 documentos
• Vídeo de : Introducción a Azure Key Vault y .NET Aspire
• resumen de las integraciones de .NET AspireAzure
• resumen de las integraciones de .NET.NET Aspire
• .NET Aspire GitHub repositorio