Condividi tramite

integrazione di .NET AspireAzure Key Vault

  • Articolo

include integrazione dell'hosting e integrazione di Client

Azure Key Vault è un servizio cloud per archiviare e accedere ai segreti in modo sicuro. L'integrazione .NET AspireAzure Key Vault consente di connettersi alle istanze di Azure Key Vault dalle applicazioni .NET.

Integrazione del servizio di hosting

L'integrazione di hosting Azure Key Vault modella una risorsa di Key Vault come tipo AzureKeyVaultResource. Per accedere a questi tipi e alle relative API all'interno del progetto dell'host dell'app , installare il pacchetto NuGet 📦Aspire.Hosting.Azure.KeyVault.

dotnet add package Aspire.Hosting.Azure.KeyVault

Per ulteriori informazioni, vedere dotnet add package oppure Gestisci le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungi la risorsa Azure Key Vault

Nel progetto host dell'app chiamare AddAzureKeyVault nell'istanza del generatore per aggiungere una risorsa 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...

Il metodo WithReference configura una connessione nel ExampleProject denominato "key-vault".

Importante

Per impostazione predefinita, AddAzureKeyVault configura un ruolo di amministratore predefinito di Key Vault .

Consiglio

Quando si chiama AddAzureKeyVault, chiama in modo implicito AddAzureProvisioning, che aggiunge il supporto per la generazione di risorse Azure in modo dinamico durante l'avvio dell'app. L'app deve configurare l'abbonamento e la località appropriate. Per ulteriori informazioni, consultare Approvisionnement locale: Configurazione.

Generazione dell'approvvigionamento Bicep

Se sei nuovo a Bicep, si tratta di un linguaggio specifico per definire le risorse Azure. Con .NET.NET Aspire, non è necessario scrivere manualmente Bicep, poiché le API di provisioning generano automaticamente Bicep per te. Quando pubblichi la tua app, il Bicep generato viene visualizzato insieme al file manifesto. Quando si aggiunge una risorsa Azure Key Vault, viene generato il Bicep seguente:

@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

Il bicep precedente è un modulo che effettua il provisioning di una risorsa Azure Key Vault con le impostazioni predefinite seguenti:

  • location: posizione del gruppo di risorse.
  • principalId: L'ID principale dell'utente o del servizio principale.
  • principalType: Il tipo principale dell'utente o del servizio principale.
  • key_vault: risorsa Azure Key Vault:
    • name: nome univoco per l'Azure Key Vault.
    • properties: proprietà Azure Key Vault:
      • tenantId: ID tenant del Azure Key Vault.
      • sku: SKU Azure Key Vault:
        • family: la famiglia di SKU.
        • name: il nome dello SKU.
      • enableRbacAuthorization: valore booleano che indica se l'Azure Key Vault dispone dell'autorizzazione di controllo degli accessi in base al ruolo abilitata.
    • tags: i tag di Azure Key Vault.
  • key_vault_KeyVaultAdministrator: L'assegnazione del ruolo di amministratore Azure Key Vault
    • name: nome univoco per l'assegnazione di ruolo.
    • properties: Proprietà dell'assegnazione dei ruoli:
      • principalId: ID principale dell'utente o dell'entità servizio.
      • roleDefinitionId: ID della definizione del ruolo di amministratore Azure Key Vault.
      • principalType: Il tipo principale dell'utente o del servizio principale.
    • scope: ambito dell'assegnazione di ruolo.
  • output: URI di Azure Key Vault.

Il Bicep generato è un punto di partenza e può essere personalizzato per soddisfare i requisiti specifici.

Personalizzare l'infrastruttura di provisioning

Tutte le risorse .NET AspireAzure sono sottoclassi del tipo di AzureProvisioningResource. Questo tipo consente la personalizzazione del Bicep generato fornendo un'API fluente per configurare le risorse Azure usando l'API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Ad esempio, è possibile configurare il sku, RBAC, tagse altro ancora. L'esempio seguente illustra come personalizzare la risorsa 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");
    });

Il codice precedente:

Sono disponibili molte altre opzioni di configurazione per personalizzare la risorsa Key Vault. Per ulteriori informazioni, vedere e . Personalizzazione del provisioning.

Collegarsi a un'istanza di Azure Key Vault esistente

Potrebbe essere disponibile un'istanza di Azure Key Vault esistente a cui connettersi. Anziché rappresentare una nuova risorsa Azure Key Vault, è possibile aggiungere una stringa di connessione all'host dell'app. Per aggiungere una connessione a una risorsa di Azure Key Vault esistente, chiamare il metodo 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

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI degli endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" è utilizzato per rappresentare qualsiasi tipo di informazioni di connessione.

La stringa di connessione viene configurata nella configurazione dell'host dell'app, in genere sotto User Secrets, nella sezione ConnectionStrings. L'host dell'app inserisce questa stringa di connessione come variabile di ambiente in tutte le risorse dipendenti, ad esempio:

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

La risorsa dipendente può accedere alla stringa di connessione inserita chiamando il metodo GetConnectionString e passando il nome della connessione come parametro, in questo caso "key-vault". L'API GetConnectionString è un'abbreviazione di IConfiguration.GetSection("ConnectionStrings")[name].

integrazione Client

Per iniziare a usare l'integrazione client .NET AspireAzure Key Vault, installare il pacchetto NuGet 📦Aspire.Azure. Security.KeyVault nel progetto che consuma il client, ovvero il progetto per l'applicazione che utilizza il client Azure Key Vault.

dotnet add package Aspire.Azure.Security.KeyVault

L'integrazione del client offre due modi per accedere ai segreti da Azure Key Vault:

  • Aggiungere segreti alla configurazione dell'app usando il pattern IConfiguration o IOptions<T>.
  • Usa un SecretClient per recuperare i segreti a richiesta.

Aggiungere segreti alla configurazione

Nel file Program.cs del progetto cliente, chiama il metodo di estensione AddAzureKeyVaultSecrets su IConfiguration per aggiungere i segreti nella configurazione dell'app. Il metodo accetta un parametro del nome di connessione.

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

Nota

Il nome dell'API AddAzureKeyVaultSecrets ha causato un po' di confusione. Il metodo viene usato per configurare il SecretClient in base al nome di connessione specificato e non viene usato per aggiungere segreti alla configurazione.

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Azure Key Vault nel progetto host dell'app. Per altre informazioni, vedere Aggiungere Azure Key Vault risorsa.

È quindi possibile recuperare un valore di configurazione basato su segreto tramite le normali API di IConfiguration o anche tramite l'associazione a classi fortemente tipate con il modello di opzioni . Per recuperare un segreto da una classe di servizio di esempio registrata con il contenitore di iniezione delle dipendenze, considera i frammenti di codice seguenti:

Recuperare l'istanza IConfiguration

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

Nell'esempio precedente si presuppone che sia stata registrata anche l'istanza di IConfiguration per l'iniezione delle dipendenze. Per altre informazioni, vedere iniezione delle dipendenze in .NET.

Recuperare l'istanza IOptions<T>

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

L'esempio precedente presuppone che sia stata configurata una classe SecretOptions da usare con il modello di opzioni. Per altre informazioni, vedere Modello opzioni in .NET.

Altri parametri api AddAzureKeyVaultSecrets sono disponibili facoltativamente per gli scenari seguenti:

  • Action<AzureSecurityKeyVaultSettings>? configureSettings: per configurare alcune o tutte le opzioni inline.
  • Action<SecretClientOptions>? configureClientOptions: per configurare il SecretClientOptions inline.
  • AzureKeyVaultConfigurationOptions? options: per configurare il AzureKeyVaultConfigurationOptions inline.

Aggiungere un client segreto Azure

In alternativa, è possibile usare il SecretClient direttamente per recuperare i segreti su richiesta. Ciò richiede un'API di registrazione leggermente diversa.

Nel file Program.cs del progetto che utilizza il client, chiama l'estensione AddAzureKeyVaultClient sull'istanza IHostApplicationBuilder per registrare un SecretClient da utilizzare tramite il contenitore per l'inserimento delle dipendenze.

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

Consiglio

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Azure Key Vault nel progetto host dell'app. Per altre informazioni, vedere Aggiungere Azure Key Vault risorsa.

Dopo aver aggiunto il *SecretClient* al *builder*, è possibile ottenere l'istanza di *SecretClient* usando il *dependency injection*. Ad esempio, per recuperare il client da un servizio di esempio, definirlo come parametro del costruttore e assicurarsi che la classe ExampleService sia registrata con il contenitore di inserimento delle dipendenze:

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

Per ulteriori informazioni sull'iniezione di dipendenze, vedere .NET iniezione di dipendenze.

Aggiungere un cliente con chiave Azure Key Vault

In alcuni casi potrebbe essere necessario registrare più istanze di SecretClient con nomi di connessione diversi. Per registrare i client Azure Key Vault con chiave, chiamare il metodo AddKeyedAzureKeyVaultClient:

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

È quindi possibile recuperare le istanze SecretClient usando l'iniezione di dipendenze. Ad esempio, per recuperare il client da un servizio di esempio:

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

Per ulteriori informazioni sui servizi con chiave, consultare la sezione .NET Inserimento delle Dipendenze: Servizi con Chiave.

Configurazione

L'integrazione .NET AspireAzure Key Vault offre più opzioni per configurare l'SecretClient in base ai requisiti e alle convenzioni del progetto.

Usare i Provider di Configurazione

L'integrazione .NET AspireAzure Key Vault supporta Microsoft.Extensions.Configuration. Carica il AzureSecurityKeyVaultSettings da appsettings.json o da altri file di configurazione usando la chiave Aspire:Azure:Security:KeyVault.

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

Per lo schema di integrazione client completo Azure Key VaultJSON, vedere Aspire.Azure. Security.KeyVault/ConfigurationSchema.json.

Se sono state configurate le configurazioni nella sezione Aspire:Azure:Security:KeyVault del file di appsettings.json, è sufficiente chiamare il metodo AddAzureKeyVaultSecrets senza passare alcun parametro.

Usare delegati inline

È anche possibile passare il delegato Action<AzureSecurityKeyVaultSettings> per configurare alcune o tutte le opzioni direttamente, ad esempio per definire il AzureSecurityKeyVaultSettings.VaultUri:

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

È anche possibile configurare il SecretClientOptions usando il delegato Action<SecretClientOptions>, che è un parametro facoltativo della funzione AddAzureKeyVaultSecrets. Ad esempio, per impostare l'ID KeyClientOptions.DisableChallengeResourceVerification per identificare il client:

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

Opzioni di configurazione

Le opzioni configurabili seguenti vengono esposte tramite la classe AzureSecurityKeyVaultSettings:

Nome Descrizione
AzureSecurityKeyVaultSettings.Credential La credenziale usata per eseguire l'autenticazione al Azure Key Vault.
AzureSecurityKeyVaultSettings.DisableHealthChecks Valore booleano che indica se la verifica dello stato del Key Vault è disabilitata o meno.
AzureSecurityKeyVaultSettings.DisableTracing Valore booleano che indica se la traccia OpenTelemetry è disabilitata o meno.
AzureSecurityKeyVaultSettings.VaultUri URI del caveau su cui opera il client. Viene visualizzato come "Nome DNS" nel portale di Azure.

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

L'integrazione .NET AspireAzure Key Vault include le verifiche dello stato di salute seguenti:

  • Aggiunge il controllo di integrità AzureKeyVaultSecretsHealthCheck, che prova a connettersi ed eseguire query sul Key Vault
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta ad accettare il traffico

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente i log, il tracciamento e le metriche, talvolta noti come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzure Key Vault usa le categorie di log seguenti:

  • Azure.Core
  • Azure.Identity

Tracciamento

L'integrazione .NET AspireAzure Key Vault genererà le attività di traccia seguenti usando OpenTelemetry:

  • Azure.Security.KeyVault.Secrets.SecretClient

Metriche

L'integrazione .NET AspireAzure Key Vault attualmente non supporta le metriche per impostazione predefinita a causa di limitazioni con Azure SDK.

Vedere anche