integratie .NET AspireAzure Key Vault

Omvat: Hosting-integratie en Client-integratie

Azure Key Vault is een cloudservice voor het veilig opslaan en openen van geheimen. Met de .NET AspireAzure Key Vault-integratie kunt u vanuit uw Azure Key Vault toepassingen verbinding maken met .NET exemplaren.

Hostingintegratie

De Azure Key Vault-hosting integreert Key Vault-bronnen als het AzureKeyVaultResource-type. Als u toegang wilt krijgen tot dit type en API's om ze te gebruiken binnen uw app host project, installeert u de 📦Aspire.Hosting.Azure.KeyVault NuGet-pakket.

.NET CLI

dotnet add package Aspire.Hosting.Azure.KeyVault

PackageReference

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

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Azure Key Vault-resource toevoegen

Roep in uw app-hostproject AddAzureKeyVault aan op het builder-exemplaar om een Azure Key Vault resource toe te voegen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

De methode WithReference configureert een verbinding in de ExampleProject met de naam "key-vault".

Belangrijk

Standaard configureert AddAzureKeyVault een ingebouwde rol van Key Vault-beheerder.

Tip

Wanneer u AddAzureKeyVaultaanroept, wordt impliciet AddAzureProvisioningaangeroepen, waardoor ondersteuning wordt toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokale inrichting: Configuratievoor meer informatie.

Gegenereerde implementatie Bicep

Als je nieuw bent met Bicep, is dit een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met .NET.NET Aspirehoeft u bicep niet handmatig te schrijven, in plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, wordt de gegenereerde Bicep samen met het manifestbestand weergegeven. Wanneer u een Azure Key Vault resource toevoegt, wordt de volgende Bicep gegenereerd:

@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

De voorgaande Bicep is een module die een Azure Key Vault resource in richt met de volgende standaardwaarden:

• location: de locatie van de resourcegroep.
• principalId: De hoofdid van de gebruiker of serviceprincipal.
• principalType: het principal-type van de gebruiker of service-principal.
• key_vault: de Azure Key Vault-bron
  • name: Een unieke naam voor de Azure Key Vault.
  • properties: de eigenschappen van de Azure Key Vault:
    • tenantId: de huurder-ID van de Azure Key Vault.
    • sku: de Azure Key Vault-SKU:
      • family: de SKU-familie.
      • name: de SKU-naam.
    • enableRbacAuthorization: een Booleaanse waarde die aangeeft of de Azure Key Vault RBAC-autorisatie (op rollen gebaseerd toegangsbeheer) heeft ingeschakeld.
  • tags: de Azure Key Vault tags.
• key_vault_KeyVaultAdministrator: de roltoewijzing van de Azure Key Vault beheerder:
  • name: een unieke naam voor de roltoewijzing.
  • properties: de eigenschappen van de roltoewijzing:
    • principalId: de principal-id van de gebruiker of service-principal.
    • roleDefinitionId: de roldefinitie-id van de Azure Key Vault-beheerdersrol.
    • principalType: Het hoofdtype van de gebruiker of service-principal.
  • scope: De omvang van een roltoewijzing.
• output: de Azure Key Vault-URI.

De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningsinfrastructuur personaliseren

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een vloeiende API te gebruiken om de Azure-resources te configureren met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de sku, RBAC, tagsen meer configureren. In het volgende voorbeeld ziet u hoe u de Azure Key Vault resource kunt aanpassen:

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

De voorgaande code:

• Koppelt een aanroep naar de ConfigureInfrastructure-API:
  • De parameter infra is een exemplaar van het AzureResourceInfrastructure type.
  • De voorzienbare resources worden opgehaald door middel van de GetProvisionableResources() methode.
  • De enkele resource KeyVaultService wordt opgehaald.
  • De eigenschap Sku is ingesteld op een nieuw KeyVaultSku exemplaar.
  • De eigenschap KeyVaultProperties.EnableRbacAuthorization is ingesteld op true.
  • Er wordt een tag toegevoegd aan de resource met een sleutel van ExampleKey en een waarde van Example value.

Er zijn nog veel meer configuratieopties beschikbaar om de Key Vault-resource aan te passen. Voor meer informatie, zie Azure.Provisioning.KeyVault en Azure. Aanpassing van voorzieningen.

Verbinding maken met een bestaand Azure Key Vault-exemplaar

Mogelijk hebt u een bestaand Azure Key Vault exemplaar waarmee u verbinding wilt maken. In plaats van een nieuwe Azure Key Vault resource weer te geven, kunt u een verbindingsreeks toevoegen aan de app-host. Als u een verbinding wilt toevoegen aan een bestaande Azure Key Vault-resource, roept u de methode AddConnectionString aan:

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

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks is geconfigureerd in de configuratie van de app-host, meestal onder gebruikersgeheimen, onder de sectie ConnectionStrings. De app-host injecteert deze verbindingsreeks als een omgevingsvariabele in alle afhankelijke resources, bijvoorbeeld:

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

De afhankelijke resource heeft toegang tot de geïnjecteerde verbindingsreeks door de methode GetConnectionString aan te roepen en de verbindingsnaam door te geven als de parameter, in dit geval "key-vault". De GetConnectionString-API is een afkorting voor IConfiguration.GetSection("ConnectionStrings")[name].

Client integratie

Installeer de 📦AspireAzure.Security.KeyVault NuGet-pakket in het client-consumerende project, dat wil zeggen het project voor de toepassing die gebruikmaakt van de Azure Key Vault-client, om aan de slag te gaan met de .NET AspireAzure Key Vault-clientintegratie.

.NET CLI

dotnet add package Aspire.Azure.Security.KeyVault

PackageReference

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

De clientintegratie biedt twee manieren om toegang te krijgen tot geheimen vanuit Azure Key Vault:

• Voeg geheimen toe aan de app-configuratie met behulp van de IConfiguration of het IOptions<T> patroon.
• Gebruik een SecretClient om geheimen op aanvraag op te halen.

Geheimen toevoegen aan configuratie

Roep in het Program.cs bestand van het clientintensieve project de AddAzureKeyVaultSecrets-extensiemethode aan op de IConfiguration om de geheimen toe te voegen als onderdeel van de configuratie van uw app. De methode gebruikt een verbindingsnaamparameter.

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

Notitie

De AddAzureKeyVaultSecrets API-naam heeft enige verwarring veroorzaakt. De methode wordt gebruikt om de SecretClient te configureren op basis van de opgegeven verbindingsnaam en deze niet wordt gebruikt om geheimen toe te voegen aan de configuratie.

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Azure Key Vault resource in het app-hostproject. Zie voor meer informatie Azure Key Vault bron toevoegen.

Vervolgens kunt u een configuratiewaarde op basis van een geheim ophalen via de normale IConfiguration API's, of zelfs door te binden aan sterk getypte klassen met het optiespatroon . Als u een geheim wilt ophalen uit een voorbeeldserviceklasse die is geregistreerd bij de container voor afhankelijkheidsinjectie, kunt u de volgende codefragmenten overwegen:

IConfiguration exemplaar ophalen

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

In het voorgaande voorbeeld wordt ervan uitgegaan dat u ook het exemplaar IConfiguration voor dependency injection hebt geregistreerd. Zie Afhankelijkheidsinjectie in .NETvoor meer informatie.

IOptions<T> exemplaar ophalen

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

In het voorgaande voorbeeld wordt ervan uitgegaan dat u een SecretOptions-klasse hebt geconfigureerd voor gebruik met het optiespatroon. Zie Options-patroon in .NETvoor meer informatie.

Aanvullende AddAzureKeyVaultSecrets API-parameters zijn optioneel beschikbaar voor de volgende scenario's:

• Action<AzureSecurityKeyVaultSettings>? configureSettings: als u enkele of alle opties inline wilt instellen.
• Action<SecretClientOptions>? configureClientOptions: De SecretClientOptions inline instellen.
• AzureKeyVaultConfigurationOptions? options: De AzureKeyVaultConfigurationOptions inline configureren.

Een Azure Secret-client toevoegen

U kunt de SecretClient ook rechtstreeks gebruiken om de geheimen op aanvraag op te halen. Hiervoor is een iets andere registratie-API vereist.

Roep in het Program.cs bestand van het clientgebruikte project de AddAzureKeyVaultClient-extensie aan op het IHostApplicationBuilder-exemplaar om een SecretClient te registreren voor gebruik via de afhankelijkheidsinjectiecontainer.

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

Tip

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Azure Key Vault resource in het app-hostproject. Zie voor meer informatie Azure Key Vault bron toevoegen.

Nadat u de SecretClient aan de builder hebt toegevoegd, kunt u de SecretClient instantie verkrijgen met behulp van afhankelijkheidsinjectie. Als u bijvoorbeeld de client wilt ophalen uit een voorbeeldservice, definieert u deze als een constructorparameter en zorgt u ervoor dat de klasse ExampleService is geregistreerd bij de container voor afhankelijkheidsinjectie:

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

Voor meer informatie over afhankelijkheidsinjectie, zie .NET.

Keyed Azure Key Vault-client toevoegen

Er kunnen situaties zijn waarin u meerdere SecretClient exemplaren met verschillende verbindingsnamen wilt registreren. Om kliënten met sleutel Azure Key Vault te registreren, roept u de methode AddKeyedAzureKeyVaultClient op.

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

Vervolgens kunt u de SecretClient instanties ophalen via afhankelijkheidsinjectie. Als u bijvoorbeeld de client wilt ophalen uit een voorbeeldservice:

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

Voor meer informatie over op sleutels gebaseerde services, zie .NET afhankelijkheidsinjectie: Keyed services.

Configuratie

De .NET AspireAzure Key Vault-integratie biedt meerdere opties voor het configureren van de SecretClient op basis van de vereisten en conventies van uw project.

Configuratieproviders gebruiken

De .NET AspireAzure Key Vault-integratie ondersteunt Microsoft.Extensions.Configuration. Het laadt de AzureSecurityKeyVaultSettings uit appsettings.json of andere configuratiebestanden met behulp van Aspire:Azure:Security:KeyVault sleutel.

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

Zie Aspirevoor het volledige Azure Key Vault clientintegratieschema JSON.Azure. Security.KeyVault/ConfigurationSchema.json.

Als u uw configuraties hebt ingesteld in de sectie Aspire:Azure:Security:KeyVault van uw appsettings.json-bestand, kunt u de methode AddAzureKeyVaultSecrets aanroepen zonder parameters door te geven.

Gebruik inline delegates

U kunt ook de Action<AzureSecurityKeyVaultSettings> delegate doorgeven om enkele of alle opties direct in te stellen, bijvoorbeeld om de AzureSecurityKeyVaultSettings.VaultUriin te stellen:

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

U kunt de SecretClientOptions ook instellen met behulp van Action<SecretClientOptions> gemachtigde. Dit is een optionele parameter van de AddAzureKeyVaultSecrets-methode. Als u bijvoorbeeld de KeyClientOptions.DisableChallengeResourceVerification-id wilt instellen om de client te identificeren:

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

Configuratieopties

De volgende configureerbare opties worden weergegeven via de AzureSecurityKeyVaultSettings klasse:

Naam	Beschrijving
AzureSecurityKeyVaultSettings.Credential	Het authenticatiemiddel dat wordt gebruikt voor verificatie bij het Azure Key Vault-systeem.
AzureSecurityKeyVaultSettings.DisableHealthChecks	Een Booleaanse waarde die aangeeft of de Key Vault-statuscontrole is uitgeschakeld of niet.
AzureSecurityKeyVaultSettings.DisableTracing	Een booleaanse waarde die aangeeft of de OpenTelemetry tracering is uitgeschakeld of niet.
AzureSecurityKeyVaultSettings.VaultUri	Een URI naar de kluis waarop de client werkt. Wordt weergegeven als 'DNS-naam' in de Azure-portal.

Gezondheidscontroles voor Client-integratie

.NET .NET Aspire clientintegraties hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Evenzo, schakelen veel .NET.NET Aspirehostingintegraties ook eindpunten voor gezondheidscontrole in. Zie voor meer informatie:

• .NET app-gezondheidscontroles in C#
• Gezondheidscontroles in ASP.NET Core

De .NET AspireAzure Key Vault-integratie bevat de volgende statuscontroles:

• Hiermee voegt u de AzureKeyVaultSecretsHealthCheck statuscontrole toe, waarmee verbinding wordt gemaakt met de Key Vault en er query's op wordt uitgevoerd
• Kan worden geïntegreerd met het /health HTTP-eindpunt, waarbij alle geregistreerde gezondheidscontroles moeten slagen voordat de app als gereed wordt beschouwd om verkeer te accepteren.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties configureren automatisch logging-, tracing- en metrische configuraties, die ook wel bekend zijn als de pijlers van waarneembaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De .NET AspireAzure Key Vault-integratie maakt gebruik van de volgende logboekcategorieën:

• Azure.Core
• Azure.Identity

Traceren

De .NET AspireAzure Key Vault-integratie verzendt de volgende traceringsactiviteiten met behulp van OpenTelemetry:

• Azure.Security.KeyVault.Secrets.SecretClient

Statistieken

De .NET AspireAzure Key Vault-integratie biedt momenteel geen ondersteuning voor metrische gegevens vanwege beperkingen met de Azure SDK.

Zie ook

• Azure Key Vault documenten
• Video: Inleiding tot Azure Key Vault en .NET Aspire
• overzicht van .NET AspireAzure integraties
• overzicht van .NET.NET Aspire integraties
• .NET Aspire GitHub repo