Aspire Azure Key Vault integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure Key Vault är en molntjänst för säker lagring och åtkomst till hemligheter. Med integreringen AspireAzure Key Vault kan du ansluta till Azure Key Vault instanser från dina .NET program.

Integrering av värdtjänster

Hostingintegreringen modellerar en Key Vault-resurs av typen Azure Key Vault. Om du vill komma åt den här typen och API:er för att uttrycka dem i ditt AppHost-projekt installerar du 📦Aspire. Hosting.Azure. KeyVault NuGet-paket:

dotnet add package Aspire.Hosting.Azure.KeyVault

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

Mer information finns i dotnet add package eller i Hantera paketberoenden i .NET applikationer.

Lägga till Azure Key Vault resurs

I ditt AppHost-projekt anropar du AddAzureKeyVault builder-instansen för att lägga till en Azure Key Vault resurs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Metoden WithReference konfigurerar en anslutning i ExampleProject med namnet "key-vault".

Ansluta till en befintlig Azure Key Vault-instans

Du kan ha en befintlig Azure AI Key Vault-instans som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureKeyVaultResource är en befintlig resurs:

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

Mer information om hur du behandlar Azure Key Vault resurser som befintliga resurser finns i Använda befintliga Azure resurser.

Konfigurationsgenererad Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en Azure Key Vault resurs genereras följande Bicep:

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

resource key_vault 'Microsoft.KeyVault/vaults@2024-11-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

Den föregående Bicep är en modul som tillhandahåller en Azure Key Vault resurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

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

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa infrastruktur för provisionering

Alla AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör anpassning av det genererade Bicep genom att tillhandahålla ett flytande API för att konfigurera resurserna Azure med hjälp av API:et ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Du kan till exempel konfigurera sku, RBAC, tagsoch mycket mer. I följande exempel visas hur du anpassar Azure Key Vault resursen:

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");
    });

Föregående kod:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Den enda KeyVaultService resursen hämtas.
  • Egenskapen Sku tilldelas ett nytt KeyVaultSku-exemplar.
  • Egenskapen KeyVaultProperties.EnableRbacAuthorization är inställd på true.
  • En tagg läggs till i resursen med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa Key Vault-resursen. Mer information finns i Azure.Provisioning.KeyVault och Azure. Anpassning av provisionering.

Client integration

Kom igång med AspireAzure Key Vault-klientintegrering genom att installera 📦Aspire.Azure. Security.KeyVault NuGet-paket i det klientkrävande projektet, dvs. projektet för programmet som använder Azure Key Vault-klienten.

dotnet add package Aspire.Azure.Security.KeyVault

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

Klientintegrering ger två sätt att komma åt hemligheter från Azure Key Vault:

• Lägg till hemligheter i appkonfigurationen med hjälp av antingen IConfiguration eller IOptions<T>-mönstret.
• Använd en SecretClient för att hämta hemligheter på begäran.

Lägga till hemligheter i konfigurationen

I den Program.cs-filen för ditt klientkonsumerande projekt anropar du AddAzureKeyVaultSecrets-tilläggsmetoden på IConfiguration för att lägga till hemligheter som en del av appens konfiguration. Metoden tar en parameter för anslutningsnamn.

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

Du kan sedan hämta ett hemligt baserat konfigurationsvärde via de normala IConfiguration-API:erna, eller till och med genom att binda till starkt skrivna klasser med alternativmönstret. Om du vill hämta en hemlighet från en exempeltjänstklass som har registrerats med containern för beroendeinmatning bör du överväga följande kodfragment:

Hämta IConfiguration instans

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

I föregående exempel förutsätts att du också har registrerat IConfiguration-instansen för beroendeinjektion. Mer information finns i Beroendeinmatning i .NET.

Hämta IOptions<T> instans

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

I föregående exempel förutsätts att du har konfigurerat en SecretOptions-klass för användning med alternativmönstret. För mer information, se Alternativmönstret i .NET.

Ytterligare AddAzureKeyVaultSecrets API-parametrar är tillgängliga om du vill för följande scenarier:

• Action<AzureSecurityKeyVaultSettings>? configureSettings: Konfigurera vissa eller alla alternativ direkt.
• Action<SecretClientOptions>? configureClientOptions: För att konfigurera SecretClientOptions i linje.
• AzureKeyVaultConfigurationOptions? options: Konfigurera AzureKeyVaultConfigurationOptions direkt i linje.

Lägga till en Azure Secret-klient

Du kan också använda SecretClient direkt för att hämta hemligheterna på begäran. Detta kräver ett något annorlunda registrerings-API.

I Program.cs-filen för ditt klientanvändande projekt anropar du AddAzureKeyVaultClient-tillägget på IHostApplicationBuilder-instansen för att registrera en SecretClient för användning via beroendeinjektionscontainern.

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

När du har lagt till SecretClient i byggaren kan du hämta SecretClient-instansen med hjälp av beroendeinjektion. Om du till exempel vill hämta klienten från en exempeltjänst definierar du den som en konstruktorparameter och kontrollerar att klassen ExampleService har registrerats med containern för beroendeinmatning:

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

Mer information om beroendeinmatning finns i .NET beroendeinmatning.

Lägg till nycklad Azure Key Vault-klient

Det kan finnas situationer där du vill registrera flera SecretClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Azure Key Vault klienter anropar du metoden AddKeyedAzureKeyVaultClient:

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

Sedan kan du hämta SecretClient-instans genom dependency injection. Om du till exempel vill hämta klienten från en exempeltjänst:

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

Mer information om nyckelade tjänster finns i .NET beroendeinjektion: Nyckelade tjänster.

Konfiguration

Aspire Azure Key Vault-integreringen innehåller flera alternativ för att konfigurera SecretClient baserat på kraven och konventionerna i projektet.

Använda konfigurationsprovidrar

Aspire Azure Key Vault-integreringen stöder Microsoft.Extensions.Configuration. Den läser in AzureSecurityKeyVaultSettings från appsettings.json eller andra konfigurationsfiler med hjälp av Aspire:Azure:Security:KeyVault nyckel.

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

Det fullständiga Azure Key Vault klientintegreringsschemat JSON finns i Aspire.Azure. Security.KeyVault/ConfigurationSchema.json.

Använda namngiven konfiguration

Integreringen AspireAzure Key Vault stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma resurstyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under huvudkonfigurationsavsnittet.

{
  "Aspire": {
    "Azure": {
      "Security": {
        "KeyVault": {
          "vault1": {
            "VaultUri": "https://myvault1.vault.azure.net/",
            "DisableHealthChecks": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp1"
              }
            }
          },
          "vault2": {
            "VaultUri": "https://myvault2.vault.azure.net/",
            "DisableTracing": true,
            "ClientOptions": {
              "Diagnostics": {
                "ApplicationId": "myapp2"
              }
            }
          }
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen vault1 och vault2 användas när du anropar AddAzureKeyVaultSecrets:

builder.AddAzureKeyVaultSecrets("vault1");
builder.AddAzureKeyVaultSecrets("vault2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

Om du har konfigurerat konfigurationerna i avsnittet Aspire:Azure:Security:KeyVault i filen appsettings.json kan du bara anropa metoden AddAzureKeyVaultSecrets utan att skicka några parametrar.

Använd inline-delegater

Du kan också använda Action<AzureSecurityKeyVaultSettings> delegering för att konfigurera vissa eller alla alternativ direkt, till exempel för att ange AzureSecurityKeyVaultSettings.VaultUri:

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

Du kan också konfigurera SecretClientOptions med hjälp av Action<SecretClientOptions> delegerare, vilket är en valfri parameter i metoden AddAzureKeyVaultSecrets. Du kan till exempel ange KeyClientOptions.DisableChallengeResourceVerification ID för att identifiera klienten:

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

Konfigurationsalternativ

Följande konfigurerbara alternativ exponeras via klassen AzureSecurityKeyVaultSettings:

Client hälsokontroller för integrering

Som standard Aspire har klientintegreringarhälsokontroller aktiverade för alla tjänster. På samma sätt möjliggör många Aspirehostingintegrationer även hälsokontrolländpunkter. Mer information finns i:

• .NET apphälsokontroller i C#
• Hälsokontroller i ASP.NET Core

Integreringen AspireAzure Key Vault innehåller följande hälsokontroller:

• Lägger till AzureKeyVaultSecretsHealthCheck hälsotest, som försöker ansluta till och utföra frågor mot Key Vault.
• Integrerar med /health HTTP-slutpunkt, som anger att alla registrerade hälsokontroller måste godkännas för att appen ska betraktas som redo att ta emot trafik

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Aspire Azure Key Vault-integreringen använder följande loggkategorier:

• Azure.Core
• Azure.Identity

Spårning

Aspire Azure Key Vault-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Azure.Security.KeyVault.Secrets.SecretClient

Mått

Den AspireAzure Key Vault integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK.

Se även

• Azure Key Vault dokument
• Video: Introduktion till Azure Key Vault och Aspire
• översikt över AspireAzure integreringar
• Aspire översikt över integreringar
• Aspire GitHub Repo