integratie AspireAzure Key Vault

Inclusief: —&— Client integratie

Azure Key Vault is een cloudservice voor het veilig opslaan en openen van geheimen. Met de 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 voor het uitdrukken ervan binnen uw AppHost-project , installeert u het 📦Aspire. Hosting.Azure. KeyVault NuGet-pakket:

dotnet add package Aspire.Hosting.Azure.KeyVault

<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 AppHost-project AddAzureKeyVault het builder-exemplaar aan 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".

Verbinding maken met een bestaand Azure Key Vault-exemplaar

Mogelijk hebt u een bestaand Azure AI Key Vault-exemplaar waarmee u verbinding wilt maken. U kunt een aanroep aaneenschakelen om aan te geven dat uw AzureKeyVaultResource een bestaande resource is.

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

Zie Gebruik bestaande resources voor meer informatie over het behandelen van Azure Key Vault resources als bestaande Azure resources.

Provisioning-gegenereerde Bicep

Als je nieuw bent met Bicep, is dit een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met Aspire hoeft u Bicep niet handmatig te schrijven, omdat de voorzienings-API's Bicep voor u genereren. 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

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

De voorgaande Bicep is een module die een Azure Key Vault resource configureert. Daarnaast worden roltoewijzingen gemaakt voor de Azure resource in een afzonderlijke module:

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

De gegenereerde Bicep is een beginpunt en wordt beïnvloed door wijzigingen aan de voorzieningsinfrastructuur in C#. Aanpassingen aan het Bicep-bestand zullen direct overschreven worden, dus breng wijzigingen aan via de C#-inrichtings-API's zodat ze weerspiegeld worden in de gegenereerde bestanden.

Voorzieningsinfrastructuur personaliseren

Alle 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 nieuwe KeyVaultSku instantie.
  • 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.

Client integratie

Installeer de Aspire 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 📦Aspire-clientintegratie.

dotnet add package Aspire.Azure.Security.KeyVault

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

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

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

Voor het volledige Azure Key Vault clientintegratieschema JSON, zie Aspire.Azure.Security.KeyVault/ConfigurationSchema.json.

Benoemde configuratie gebruiken

De AspireAzure Key Vault integratie ondersteunt benoemde configuratie, waarmee u meerdere exemplaren van hetzelfde resourcetype met verschillende instellingen kunt configureren. De benoemde configuratie maakt gebruik van de verbindingsnaam als een sleutel in het hoofdgedeelte van de configuratie.

{
  "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"
              }
            }
          }
        }
      }
    }
  }
}

In dit voorbeeld kunnen de vault1 en vault2 verbindingsnamen worden gebruikt wanneer AddAzureKeyVaultSecrets wordt aangeroepen:

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

Benoemde configuratie heeft voorrang op de configuratie op het hoogste niveau. Als beide zijn opgegeven, overschrijven de instellingen van de benoemde configuratie de instellingen op het hoogste niveau.

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:

Gezondheidscontroles voor Client-integratie

Aspire hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Op dezelfde manier maken veel Aspirehostingintegraties ook statuscontrole-eindpunten mogelijk. Zie voor meer informatie:

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

De 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

Aspire Integraties stellen automatisch configuraties voor logboekregistratie, tracering en metrische gegevens in, die ook wel de pijlers van waarneembaarheid worden genoemd. Zie het overzicht van integratieobserveerbaarheid en telemetrie voor meer informatie over integratieobserveerbaarheid en telemetrieAspire. 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 AspireAzure Key Vault-integratie maakt gebruik van de volgende logboekcategorieën:

• Azure.Core
• Azure.Identity

Traceren

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

• Azure.Security.KeyVault.Secrets.SecretClient

Statistieken

De 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 Aspire
• overzicht van AspireAzure integraties
• Aspire overzicht van integraties
• Aspire GitHub Repo