Udostępnij za pośrednictwem

integracja .NET AspireAzure Key Vault

Obejmuje:integracja hostingu obejmuje integrację hostingu — Client integracja dołączonaClient

Azure Key Vault to usługa w chmurze umożliwiająca bezpieczne przechowywanie i dostęp do tajemnic. Integracja .NET AspireAzure Key Vault umożliwia łączenie aplikacji Azure Key Vault z instancjami .NET.

Integracja hostingu

Hostowanie integracji Azure Key Vault modeluje zasób usługi Key Vault jako typ AzureKeyVaultResource. Aby uzyskać dostęp do tego typu i interfejsów API do wyrażania ich w projekcie hosta aplikacji , zainstaluj pakiet NuGet 📦Aspire.Hosting.Azure.KeyVault:

dotnet add package Aspire.Hosting.Azure.KeyVault

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzaj zależnościami pakietów w aplikacjach .NET.

Dodawanie zasobu Azure Key Vault

W projekcie hosta aplikacji wywołaj AddAzureKeyVault na instancji konstruktora, aby dodać zasób 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...

Metoda WithReference konfiguruje połączenie w ExampleProject o nazwie "key-vault".

Ważne

Domyślnie AddAzureKeyVault konfiguruje wbudowaną rolę administratora Key Vault.

Napiwek

Podczas wywoływania AddAzureKeyVaultniejawnie wywołuje AddAzureProvisioning, co wprowadza obsługę dynamicznego generowania zasobów Azure podczas uruchamiania aplikacji. Aplikacja musi skonfigurować odpowiednią subskrypcję i lokalizację. Aby uzyskać więcej informacji, zobacz Lokalna konfiguracja: Konfiguracja.

Bicep wygenerowany przez prowizjonowanie

Jeśli jesteś nowy w korzystaniu z Bicep, jest to język specyficzny dla domeny wykorzystywany do definiowania zasobów Azure. W przypadku .NET.NET Aspirenie musisz pisać Bicep ręcznie, ponieważ interfejsy API do aprowizacji generują Bicep za Ciebie. Podczas publikowania aplikacji, wygenerowany plik Bicep zostaje wyeksportowany razem z plikiem manifestu. Po dodaniu zasobu Azure Key Vault jest generowany następujący kod Bicep:

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

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

output vaultUri string = key_vault.properties.vaultUri

output name string = key_vault.name

Poprzedzający Bicep to moduł, który zapewnia zasób Azure Key Vault. Ponadto w osobnym module tworzone są przypisania ról dla zasobu Azure.

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

Wygenerowany Bicep jest punktem wyjścia i ulega wpływom zmian w infrastrukturze aprowizacji w języku C#. Modyfikacje pliku Bicep, które zostaną wprowadzone bezpośrednio, będą nadpisane. Dlatego należy wprowadzać je za pośrednictwem interfejsów API aprowizowania w języku C#, aby zapewnić, że zostaną odzwierciedlone w wygenerowanych plikach.

Dostosowywanie infrastruktury aprowizacji

Wszystkie zasoby .NET AspireAzure to podklasy typu AzureProvisioningResource. Ten typ umożliwia dostosowanie wygenerowanego elementu Bicep przez zapewnienie płynnego interfejsu API do konfigurowania zasobów Azure przy użyciu interfejsu API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Można na przykład skonfigurować sku, RBAC, tagsi więcej. W poniższym przykładzie pokazano, jak dostosować zasób 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");
    });

Powyższy kod:

Dostępnych jest wiele opcji konfiguracji umożliwiających dostosowanie zasobu usługi Key Vault. Aby uzyskać więcej informacji, zobacz Azure.Provisioning.KeyVault i Azure. Dostosowywanie konfiguracji.

Połącz się z istniejącym wystąpieniem Azure Key Vault

Być może masz istniejące Azure wystąpienie usługi Key Vault sztucznej inteligencji, z którym chcesz nawiązać połączenie. Możesz łańcuchować wywołanie, aby wskazać, że AzureKeyVaultResource jest istniejącym zasobem:

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

Ważne

Podczas wywoływania metod RunAsExisting, PublishAsExisting lub AsExisting w celu pracy z zasobami, które są już obecne w subskrypcji Azure, należy dodać wartości konfiguracji do Hosta Aplikacji, aby .NET Aspire mógł je zlokalizować. Wymagane wartości konfiguracji obejmują SubscriptionId, AllowResourceGroupCreation, ResourceGroup i Location. Jeśli ich nie ustawisz, na pulpicie nawigacyjnym .NET.NET Aspire pojawią się błędy "Brak konfiguracji". Aby uzyskać więcej informacji na temat sposobu ich ustawiania, zobacz Konfiguracja.

Aby uzyskać więcej informacji na temat traktowania Azure Key Vault zasobów jako istniejących zasobów, zobacz Korzystanie z istniejących Azure zasobów.

Uwaga

Alternatywnie, zamiast reprezentować zasób Azure Key Vault, można dodać ciąg połączenia do hosta aplikacji. Takie podejście jest słabo typizowane i nie działa z przypisaniami ról ani dostosowaniami infrastruktury. Aby uzyskać więcej informacji, zobacz Dodaj istniejące zasoby Azure z parametrami połączenia.

Client integracja

Aby rozpocząć integrację klienta .NET AspireAzure Key Vault, zainstaluj pakiet NuGet 📦Aspire.Azure.Security.KeyVault w projekcie, który korzysta z klienta Azure Key Vault, czyli w projekcie aplikacji używającej klienta.

dotnet add package Aspire.Azure.Security.KeyVault

Integracja klienta zapewnia dwa sposoby dostępu do tajemnic z Azure Key Vault:

  • Dodaj tajne informacje do konfiguracji aplikacji, używając wzorca IConfiguration lub IOptions<T>.
  • Użyj SecretClient, aby pobierać tajemnice na żądanie.

Dodawanie sekretów do konfiguracji

W pliku Program.cs projektu, który korzysta z klienta, wywołaj metodę rozszerzenia AddAzureKeyVaultSecrets na IConfiguration, aby dodać sekrety do konfiguracji aplikacji. Metoda przyjmuje parametr nazwy połączenia.

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

Uwaga

Nazwa interfejsu API AddAzureKeyVaultSecrets spowodowała nieco zamieszanie. Metoda służy do konfigurowania SecretClient na podstawie podanej nazwy połączenia i nie jest używana do dodawania tajemnic do konfiguracji.

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Azure Key Vault w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodaj zasób Azure Key Vault.

Następnie można pobrać wartość konfiguracji opartą na tajnych danych za pomocą normalnych interfejsów API IConfiguration, a nawet przez powiązanie z silnie typowanymi klasami zgodnie ze wzorcem opcji . Aby pobrać tajny klucz z przykładowej klasy usługi zarejestrowanej w kontenerze wstrzykiwania zależności, rozważ poniższe przykłady:

Pobierz wystąpienie IConfiguration

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

W poprzednim przykładzie przyjęto założenie, że zarejestrowano również wystąpienie IConfiguration na potrzeby wstrzykiwania zależności. Aby uzyskać więcej informacji, zobacz Wstrzykiwanie zależności w .NET.

Pobierz wystąpienie IOptions<T>

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

W poprzednim przykładzie przyjęto założenie, że skonfigurowano klasę SecretOptions do użycia ze wzorcem opcji. Aby uzyskać więcej informacji, zobacz wzorzec opcji w .NET.

Dodatkowe parametry interfejsu API AddAzureKeyVaultSecrets są dostępne opcjonalnie w następujących scenariuszach:

  • Action<AzureSecurityKeyVaultSettings>? configureSettings: aby skonfigurować niektóre lub wszystkie opcje wbudowane.
  • Action<SecretClientOptions>? configureClientOptions: aby skonfigurować funkcję SecretClientOptions w trybie inline.
  • AzureKeyVaultConfigurationOptions? options: aby skonfigurować wstawkę AzureKeyVaultConfigurationOptions.

Dodaj klienta tajnego Azure

Alternatywnie możesz użyć SecretClient bezpośrednio, aby pobrać sekrety na żądanie. Wymaga to nieco innego interfejsu API rejestracji.

W pliku Program.cs swojego projektu korzystającego z klienta wywołaj rozszerzenie AddAzureKeyVaultClient na instancji IHostApplicationBuilder, aby zarejestrować SecretClient do użycia przez kontener wstrzykiwania zależności.

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

Napiwek

Parametr connectionName musi być zgodny z nazwą używaną podczas dodawania zasobu Azure Key Vault w projekcie hosta aplikacji. Aby uzyskać więcej informacji, zobacz Dodaj zasób Azure Key Vault.

Po dodaniu SecretClient do buildera, można uzyskać wystąpienie SecretClient przy użyciu wstrzykiwania zależności. Na przykład aby pobrać klienta z przykładowej usługi, zdefiniuj go jako parametr konstruktora i upewnij się, że klasa ExampleService jest zarejestrowana w kontenerze iniekcji zależności:

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

Aby uzyskać więcej informacji o wstrzykiwaniu zależności, zobacz .NETwstrzykiwanie zależności.

Dodaj klienta Azure Key Vault z kluczem

Mogą wystąpić sytuacje, w których chcesz zarejestrować wiele wystąpień SecretClient z różnymi nazwami połączeń. Aby zarejestrować klientów z kluczem Azure Key Vault, wywołaj metodę AddKeyedAzureKeyVaultClient.

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

Następnie można uzyskać wystąpienia SecretClient, korzystając z wstrzykiwania zależności. Na przykład aby pobrać klienta z przykładowej usługi:

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

Aby uzyskać więcej informacji na temat usług z kluczami, zobacz .NET wstrzykiwanie zależności: usługi z kluczami.

Konfiguracja

Integracja .NET AspireAzure Key Vault oferuje wiele opcji konfigurowania SecretClient na podstawie wymagań i konwencji projektu.

Korzystanie z dostawców konfiguracji

Integracja .NET AspireAzure Key Vault obsługuje Microsoft.Extensions.Configuration. Ładuje AzureSecurityKeyVaultSettings z appsettings.json lub z innych plików konfiguracyjnych przy użyciu klucza Aspire:Azure:Security:KeyVault.

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

Aby uzyskać pełny schemat integracji klienta Azure Key VaultJSON, zobacz Aspire.Azure. Security.KeyVault/ConfigurationSchema.json.

Jeśli konfiguracje zostały skonfigurowane w sekcji Aspire:Azure:Security:KeyVault pliku appsettings.json, możesz po prostu wywołać metodę AddAzureKeyVaultSecrets bez przekazywania żadnych parametrów.

Użyj delegatów wbudowanych

Możesz również przekazać delegata Action<AzureSecurityKeyVaultSettings>, aby skonfigurować niektóre lub wszystkie opcje w linii, na przykład w celu ustawienia AzureSecurityKeyVaultSettings.VaultUri:

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

Można również skonfigurować SecretClientOptions przy użyciu delegata Action<SecretClientOptions>, który jest opcjonalnym parametrem metody AddAzureKeyVaultSecrets. Aby na przykład ustawić identyfikator KeyClientOptions.DisableChallengeResourceVerification w celu zidentyfikowania klienta:

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

Opcje konfiguracji

Następujące konfigurowalne opcje są udostępniane za pośrednictwem klasy AzureSecurityKeyVaultSettings:

Nazwa Opis
AzureSecurityKeyVaultSettings.Credential Poświadczenie używane do uwierzytelniania w Azure Key Vault.
AzureSecurityKeyVaultSettings.DisableHealthChecks Wartość logiczna wskazująca, czy sprawdzanie kondycji usługi Key Vault jest wyłączone, czy nie.
AzureSecurityKeyVaultSettings.DisableTracing Wartość logiczna wskazująca, czy śledzenie OpenTelemetry jest wyłączone, czy nie.
AzureSecurityKeyVaultSettings.VaultUri Identyfikator URI do skarbca, w którym działa klient. Jest wyświetlana jako "Nazwa DNS" w portalu Azure.

Client kontrole stanu integracji

Domyślnie .NET.NET Aspireintegracje klienta mają kontrole stanu włączone dla wszystkich usług. Podobnie, wiele integracji hostingowych również umożliwia punkty końcowe sprawdzania kondycji. Aby uzyskać więcej informacji, zobacz:

Integracja .NET AspireAzure Key Vault obejmuje następujące kontrole kondycji:

  • Dodaje kontrolę kondycji AzureKeyVaultSecretsHealthCheck, która próbuje nawiązać połączenie z usługą Key Vault i wykonywać zapytania dotyczące tej usługi.
  • Integruje się z punktem końcowym HTTP /health, który określa, że wszystkie zarejestrowane kontrole kondycji muszą zostać pomyślnie zaliczone, aby aplikacja była uznana za gotową do przyjmowania ruchu.

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie konfigurują rejestrowanie, śledzenie i metryki, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Rejestrowanie

Integracja .NET AspireAzure Key Vault używa następujących kategorii dzienników:

  • Azure.Core
  • Azure.Identity

Śledzenie

Integracja .NET AspireAzure Key Vault spowoduje wykonywanie następujących procesów śledzenia z użyciem OpenTelemetry.

  • Azure.Security.KeyVault.Secrets.SecretClient

Wskaźniki

Integracja .NET AspireAzure Key Vault obecnie nie obsługuje metryk domyślnie z powodu ograniczeń SDK Azure.

Zobacz też