.NET Aspire Azure Key Vault integráció

2025-06-18

Tartalmazza: hosting-integráció —&— Client integráció

Azure Key Vault a titkos kódok biztonságos tárolására és elérésére szolgáló felhőszolgáltatás. A .NET AspireAzure Key Vault integráció lehetővé teszi, hogy a Azure Key Vault alkalmazásokból csatlakozzon a .NET példányokhoz.

Üzemeltetési integráció

Az Azure Key Vault integrációs modellezés a Key Vault-erőforrást AzureKeyVaultResource típusként modellezi. Ahhoz, hogy hozzáférjen ehhez a típushoz és az API-khoz az alkalmazásgazda projektjében való kifejezéshez, telepítse a 📦Aspire.Hosting.Azure.KeyVault NuGet-csomagot.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.KeyVault

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

További információkért lásd: dotnet add package vagy Csomagfüggőségek kezelése .NET alkalmazásokban.

Azure Key Vault erőforrás hozzáadása

Az alkalmazásgazdaprojektben hívja meg a AddAzureKeyVault a szerkesztőpéldányon egy Azure Key Vault erőforrás hozzáadásához:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

A WithReference metódus konfigurál egy kapcsolatot a ExampleProject-ben, amelyet "key-vault"-nek hívnak.

Fontos

Alapértelmezés szerint AddAzureKeyVault egy beépített Key Vault-rendszergazdai szerepkört konfigurál.

Borravaló

Amikor meghívja a AddAzureKeyVault-t, az implicit módon meghívja a AddAzureProvisioning-et, amely hozzáadja a támogatást a Azure erőforrások dinamikus generálásához az alkalmazás indulásakor. Az alkalmazásnak konfigurálnia kell a megfelelő előfizetést és helyet. További információ: Helyi kiépítés: Konfiguráció.

Kiépítés által előállított Bicep

Ha még nem ismerkedik a Bicepvel, az egy tartományspecifikus nyelv az erőforrások definiálásához Azure . A .NET.NET Aspirehasználatával nem kell kézzel megírnia a Bicepet, mert a kiépítési API-k generálják azt ön helyett. Az alkalmazás közzétételekor a létrehozott Bicep fájl kimenetként a jegyzékfájl mellett jelenik meg. Azure Key Vault erőforrás hozzáadásakor a következő Bicep jön létre:

@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

Az előző Bicep egy erőforrást Azure Key Vault kiosztó modul. Emellett egy külön modulban is létrejönnek szerepkör-hozzárendelések az Azure erőforráshoz:

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

Az elkészített Bicep egy kiindulási pont, amelyet a C# kiépítési infrastruktúrájának változásai befolyásolnak. A Bicep-fájl közvetlen módosításai felülíródnak, ezért elengedhetetlen, hogy a C# kiépítési API-kkal végezzen módosításokat, hogy azok megjelenjenek a létrehozott fájlokban.

Az ellátási infrastruktúra testreszabása

Minden .NET AspireAzure erőforrás a AzureProvisioningResource típusú alosztály. Ez a típus lehetővé teszi a létrehozott Bicep testreszabását azáltal, hogy egy folyékony API-val konfigurálja a Azure erőforrásokat a ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) API használatával. Konfigurálhatja például a sku, RBAC, tagsstb. Az alábbi példa bemutatja, hogyan szabhatja testre a Azure Key Vault erőforrást:

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

Az előző kód:

A hívást az ConfigureInfrastructure API-hoz láncolja:
- A infra paraméter a AzureResourceInfrastructure típusú példány.
- A kiosztható erőforrások a GetProvisionableResources() metódus meghívásával kérhetők le.
- Az egyetlen KeyVaultService erőforrást lekérik.
- A Sku tulajdonság egy új KeyVaultSku-példányra van állítva.
- A KeyVaultProperties.EnableRbacAuthorization tulajdonság be van állítva true-re.
- A rendszer hozzáad egy címkét az erőforráshoz egy ExampleKey kulccsal és egy Example valueértékkel.

A Key Vault-erőforrás testreszabásához több konfigurációs lehetőség is rendelkezésre áll. További információkért lásd: Azure.Provisioning.KeyVault és Azure. Kiépítés testreszabása.

Csatlakozás meglévő Azure Key Vault-példányhoz

Előfordulhat, hogy rendelkezik egy meglévő Azure AI Key Vault-példánysal, amelyhez csatlakozni szeretne. A hívásláncban megjegyzésként jelezheti, hogy a AzureKeyVaultResource egy meglévő erőforrás:

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

Fontos

Amikor meghívja a RunAsExisting, PublishAsExisting vagy AsExisting metódusokat, és az Azure előfizetésében már meglévő erőforrásokkal dolgozik, bizonyos konfigurációs értékeket kell hozzáadnia az alkalmazásgazdának, hogy a .NET Aspire megtalálja őket. A szükséges konfigurációs értékek közé tartozik az SubscriptionId, az AllowResourceGroupCreation, a ResourceGroup és a Location. Ha nem állítja be őket, "Hiányzó konfiguráció" hibák jelennek meg az .NET.NET Aspire irányítópulton. A beállításukról további információt a Konfiguráció című témakörben talál.

Az erőforrások meglévő erőforrásokként való kezeléséről Azure Key Vault további információt a Meglévő Azure erőforrások használata című témakörben talál.

Megjegyzés

Alternatív megoldásként hozzáadhat egy kapcsolati sztringet az alkalmazás szerveréhez, az erőforrás helyett. Ez a megközelítés gyenge típusú, és nem működik szerepkör-hozzárendelésekkel vagy infrastruktúra-testreszabásokkal. További információkért lásd: Meglévő Azure erőforrások hozzáadása kapcsolati karakterláncokkal.

Client integráció

A .NET AspireAzure Key Vault ügyfélintegráció elkezdéséhez telepítse a 📦Aspire.Azure.Security.KeyVault NuGet-csomagot abban a projektben, amely a Azure Key Vault ügyfelet használó alkalmazásé.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Security.KeyVault

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

Az ügyfelek integrációja két módszert kínál a titkos kódok Azure Key Vault eléréséhez:

Titkos kulcsok hozzáadása az alkalmazáskonfigurációhoz a IConfiguration vagy a IOptions<T> mintával.
Használjon SecretClient a titkos kódok igény szerinti lekéréséhez.

Titkos kódok hozzáadása a konfigurációhoz

Az ügyfélfogyasztó projekt Program.cs fájljában hívja meg a AddAzureKeyVaultSecrets bővítménymetódust a IConfiguration-en, hogy az alkalmazás konfigurációjának részeként adja hozzá a titkokat. A metódus egy kapcsolatnévparamétert használ.

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

Megjegyzés

A AddAzureKeyVaultSecrets API neve némi félreértést okozott. A metódus a SecretClient megadott kapcsolatnév alapján történő konfigurálásra szolgál, és nem használható titkos kulcsok hozzáadására a konfigurációhoz.

Borravaló

A connectionName paraméternek meg kell egyeznie a Azure Key Vault erőforrás alkalmazásgazdaprojektben való hozzáadásakor használt névvel. További információ: Erőforrás hozzáadásaAzure Key Vault.

Ezután lekérhet egy titkos konfigurációs értéket a normál IConfiguration API-kon keresztül, vagy akár úgy is, hogy a beállítási mintával erősen gépelt osztályokhoz köti. A függőséginjektálási tárolóban regisztrált példaszolgáltatás-osztály titkos kódjának lekéréséhez vegye figyelembe a következő kódrészleteket:

`IConfiguration` példány lekérése

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

Az előző példa feltételezi, hogy regisztrálta a IConfiguration példányt a függőséginjektáláshoz is. További információért, lásd: függőség-injektálás a .NET.

`IOptions<T>` példány lekérése

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

Az előző példa feltételezi, hogy konfigurált egy SecretOptions osztályt a beállítási mintával való használatra. További információ: Beállítások minta a .NET.

A következő forgatókönyvekhez további AddAzureKeyVaultSecrets API-paraméterek érhetők el:

** Action<AzureSecurityKeyVaultSettings>? configureSettings: Néhány vagy az összes beállítás közvetlen beállítása.
Action<SecretClientOptions>? configureClientOptions: A SecretClientOptions soros beállítása.
AzureKeyVaultConfigurationOptions? options: A AzureKeyVaultConfigurationOptions közvetlen konfigurálása.

Azure Titkos ügyfél hozzáadása

Másik lehetőségként közvetlenül a SecretClient-t is használhatja a titkok igény szerinti lekérésére. Ehhez kissé eltérő regisztrációs API szükséges.

Az ügyfél által használt projekt Program.cs fájljában hívja meg a AddAzureKeyVaultClient bővítményt a IHostApplicationBuilder példányon, hogy regisztráljon egy SecretClient a függőséginjektáló tartály segítségével való használathoz.

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

Borravaló

Miután hozzáadta az SecretClient-t az építőhöz, függőséginjektálással lekérheti a SecretClient példányt. Ha például egy példaszolgáltatásból szeretné lekérni az ügyfelet, konstruktorparaméterként határozza meg, és győződjön meg arról, hogy a ExampleService osztály regisztrálva van a függőséginjektáló tárolóban:

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

A függőséginjektálással kapcsolatos további információkért lásd .NET a függőséginjektálást.

Adja hozzá azonosított Azure Key Vault-ügyfelet

Előfordulhatnak olyan helyzetek, amikor több SecretClient instance-t szeretne regisztrálni különböző kapcsolatnevekkel. A kulcsos Azure Key Vault ügyfelek regisztrálásához hívja meg a AddKeyedAzureKeyVaultClient metódust:

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

Ezután függőséginjektálással lekérheti a SecretClient példányokat. Példaként, egy példaszolgáltatásból történő ügyféladatok lekérése:

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

További információ a kulcsos szolgáltatásokról: .NET függőséginjektálás: Kulcsos szolgáltatások.

Konfiguráció

A .NET AspireAzure Key Vault integráció több lehetőséget is kínál a SecretClient konfigurálásához a projekt követelményei és konvenciói alapján.

Konfigurációs szolgáltatók használata

A .NET AspireAzure Key Vault integráció támogatja a Microsoft.Extensions.Configuration. Betölti a AzureSecurityKeyVaultSettings-t a appsettings.json-ből vagy más konfigurációs fájlokból a Aspire:Azure:Security:KeyVault kulcs segítségével.

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

A teljes Azure Key Vault ügyfélintegrációs JSON séma megtekintéséhez lásd Aspire.Azure.Security.KeyVault/ConfigurationSchema.json.

Ha beállította a konfigurációkat a Aspire:Azure:Security:KeyVault fájl appsettings.json szakaszában, egyszerűen meghívhatja a metódust AddAzureKeyVaultSecrets paraméterek átadása nélkül.

Beágyazott delegáltak használata

A Action<AzureSecurityKeyVaultSettings> delegáltat is átadhatja a beágyazott beállítások egy részének vagy mindegyikének beállításához, például a AzureSecurityKeyVaultSettings.VaultUribeállításához:

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

A SecretClientOptions beállítható a Action<SecretClientOptions> delegált használatával is, amely a AddAzureKeyVaultSecrets metódus opcionális paramétereként szerepel. Például az ügyfél azonosításához állítsa be a KeyClientOptions.DisableChallengeResourceVerification azonosítóját:

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

Konfigurációs beállítások

A következő konfigurálható beállítások érhetők el az AzureSecurityKeyVaultSettings osztályon keresztül:

Név	Leírás
AzureSecurityKeyVaultSettings.Credential	Az Azure Key Vaulthitelesítéséhez használt hitelesítő adat.
AzureSecurityKeyVaultSettings.DisableHealthChecks	Logikai érték, amely azt jelzi, hogy a Key Vault állapotellenőrzése le van-e tiltva.
AzureSecurityKeyVaultSettings.DisableTracing	Egy logikai érték, amely jelezheti, hogy a OpenTelemetry nyomkövetés le van-e tiltva.
AzureSecurityKeyVaultSettings.VaultUri	Annak a tárolónak a URI-je, amelyen az ügyfél működik. A Azure portálon "DNS-névként" jelenik meg.

Client integrációs egészségügyi ellenőrzések

Alapértelmezés szerint .NET.NET Aspireügyfélintegrációkállapotellenőrzések engedélyezve vannak az összes szolgáltatáshoz. Hasonlóképpen számos .NET.NET Aspireüzemeltetési integráció is lehetővé teszi az állapot-ellenőrzési végpontokat. További információ:

Az .NET AspireAzure Key Vault integráció a következő állapotellenőrzéseket tartalmazza:

Hozzáadja a AzureKeyVaultSecretsHealthCheck állapot-ellenőrzést, amely próbál csatlakozni és lekérdezni a Key Vault-ot
Integrálható a /health HTTP-végponttal, amely meghatározza, hogy az összes regisztrált állapot-ellenőrzésnek át kell mennie ahhoz, hogy az alkalmazás készen álljon a forgalom elfogadására

Megfigyelhetőség és telemetria

.NET .NET Aspire az integrációk automatikusan beállítják a naplózási, nyomkövetési és metrikakonfigurációkat, amelyeket néha a megfigyelhetőség pillérének is neveznek. Az integráció megfigyelhetőségéről és telemetriáiról további információt az integrációk áttekintésében talál.NET.NET Aspire. A háttérszolgáltatástól függően egyes integrációk csak bizonyos funkciókat támogatnak. Egyes integrációk például támogatják a naplózást és a nyomkövetést, a metrikákat azonban nem. A telemetriai funkciók a Konfiguráció szakaszban bemutatott technikákkal is letilthatók.

Fakitermelés

Az .NET AspireAzure Key Vault integráció a következő naplókategóriákat használja:

Azure.Core
Azure.Identity

Nyomkövetés

Az .NET AspireAzure Key Vault integráció a következő nyomkövetési tevékenységeket bocsátja ki a OpenTelemetryhasználatával:

Azure.Security.KeyVault.Secrets.SecretClient

Metrikák

A .NET AspireAzure Key Vault integráció jelenleg nem támogatja alapértelmezés szerint a metrikákat a Azure SDK korlátozásai miatt.

Megosztás a következőn keresztül:

.NET Aspire Azure Key Vault integráció

Üzemeltetési integráció

Azure Key Vault erőforrás hozzáadása

Kiépítés által előállított Bicep

Az ellátási infrastruktúra testreszabása

Csatlakozás meglévő Azure Key Vault-példányhoz

Client integráció

Titkos kódok hozzáadása a konfigurációhoz

IConfiguration példány lekérése

IOptions<T> példány lekérése

Azure Titkos ügyfél hozzáadása

Adja hozzá azonosított Azure Key Vault-ügyfelet

Konfiguráció

Konfigurációs szolgáltatók használata

Beágyazott delegáltak használata

Konfigurációs beállítások

Client integrációs egészségügyi ellenőrzések

Megfigyelhetőség és telemetria

Fakitermelés

Nyomkövetés

Metrikák

Lásd még:

Visszajelzés

További források

`IConfiguration` példány lekérése

`IOptions<T>` példány lekérése