.NET AspireAzure Key Vault 統合

含まれているもの: ホスティング統合 —および— Client 統合

Azure Key Vault は、シークレットを安全に格納してアクセスするためのクラウド サービスです。 .NET AspireAzure Key Vault 統合により、Azure Key Vault アプリケーションから .NET インスタンスに接続できます。

ホスティング統合

Azure Key Vault ホスティング統合は、Key Vault リソースを AzureKeyVaultResource の種類としてモデル化します。 この種類とAPIにアクセスし、アプリホストプロジェクト内でそれらを表現するには、📦Aspire.Hosting.Azure.KeyVault NuGetパッケージをインストールしてください。

dotnet add package Aspire.Hosting.Azure.KeyVault

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

詳細については、「dotnet パッケージ の追加」または「.NET アプリケーションでのパッケージの依存関係の管理」を参照してください。

リソース Azure Key Vault を追加する

アプリ ホスト プロジェクトで、ビルダー インスタンスの AddAzureKeyVault を呼び出して、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...

WithReference メソッドは、ExampleProjectという名前の "key-vault" で接続を構成します。

プロビジョニングによって生成されたBicep

Bicep を初めて使う場合、これは Azure リソースを定義するためのドメイン固有の言語です。 .NET.NET Aspireでは、Bicep を手動で記述する必要はありません。代わりに、プロビジョニング API によって Bicep が生成されます。 アプリを発行すると、生成された Bicep がマニフェスト ファイルと共に出力されます。 Azure Key Vault リソースを追加すると、次の 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

上記の Bicep は、 Azure Key Vault リソースをプロビジョニングするモジュールです。 さらに、ロールの割り当ては、別のモジュールで 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
}

生成された Bicep は開始点であり、C# のプロビジョニング インフラストラクチャへの変更の影響を受ける。 Bicep ファイルのカスタマイズは直接上書きされるため、C# プロビジョニング API を通じて変更を加えて、生成されたファイルに反映されるようにします。

プロビジョニング インフラストラクチャをカスタマイズする

すべての .NET AspireAzure リソースは、AzureProvisioningResource 型のサブクラスです。 この型では、Azure API を使用して ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>) リソースを構成する fluent API を提供することで、生成された Bicep をカスタマイズできます。 たとえば、sku、RBAC、tagsなどを構成できます。 次の例では、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");
    });

上記のコード:

• ConfigureInfrastructure API への呼び出しを連鎖させます。
  • infra パラメーターは、AzureResourceInfrastructure 型のインスタンスです。
  • プロビジョニング可能なリソースは、GetProvisionableResources() メソッドを呼び出すことによって取得されます。
  • 単一の KeyVaultService リソースが取得されます。
  • Sku プロパティは、新しい KeyVaultSku インスタンスに設定されます。
  • KeyVaultProperties.EnableRbacAuthorization プロパティが true に設定されている。
  • ExampleKey のキーと値が Example valueのタグがリソースに追加されます。

Key Vault リソースをカスタマイズするために使用できる構成オプションは他にも多数あります。 詳細については、「Azure.Provisioning.KeyVault と Azure」およびカスタマイズのプロビジョニングを参照してください。

既存の Azure Key Vault インスタンスに接続する

接続する既存の Azure AI Key Vault インスタンスがある場合があります。 呼び出しをチェーンして、AzureKeyVaultResource が既存のリソースであることを注釈付けることができます。

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

Azure Key Vault リソースを既存のリソースとして扱う方法の詳細については、「既存のAzure リソースを使用する」を参照してください。

Client 統合

.NET AspireAzure Key Vault クライアント統合を開始するには、クライアントが使用されるプロジェクト、つまり 📦 クライアントを使用するアプリケーションのプロジェクトに、Aspire NuGet パッケージをインストールします。

dotnet add package Aspire.Azure.Security.KeyVault

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

クライアント統合には、Azure Key Vaultからシークレットにアクセスする 2 つの方法が用意されています。

• IConfiguration または IOptions<T> パターンを使用して、アプリ構成にシークレットを追加します。
• SecretClient を使用して、必要に応じてシークレットを取得します。

構成にシークレットを追加する

クライアントを使用するプロジェクトの Program.cs ファイルで、AddAzureKeyVaultSecrets の IConfiguration 拡張メソッドを呼び出して、アプリの構成の一部としてシークレットを追加します。 このメソッドは、接続名パラメーターを受け取ります。

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

その後、通常の IConfiguration API を使用するか、オプション パターンを使用して厳密に型指定されたクラスにバインドすることによっても、シークレットベースの構成値を取得できます。 依存関係挿入コンテナーに登録されているサービス クラスの例からシークレットを取得するには、次のスニペットを検討してください。

インスタンス IConfiguration 取得する

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

前の例では、依存関係の挿入用に IConfiguration インスタンスも登録していることを前提としています。 詳細については、.NETにおけるの依存関係の挿入を参照してください。

インスタンス IOptions<T> 取得する

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

前の例では、オプション パターンで使用する SecretOptions クラスを構成していることを前提としています。 詳細については、「.NETのオプション パターン」を参照してください。

追加 AddAzureKeyVaultSecrets API パラメーターは、必要に応じて次のシナリオで使用できます。

• Action<AzureSecurityKeyVaultSettings>? configureSettings: 一部またはすべてのオプションをインラインで設定します。
• Action<SecretClientOptions>? configureClientOptions: SecretClientOptions をインラインで設定します。
• AzureKeyVaultConfigurationOptions? options: AzureKeyVaultConfigurationOptions をインラインで構成します。

Azure シークレット クライアントを追加する

または、SecretClient を直接使用して、オンデマンドでシークレットを取得することもできます。 これには、少し異なる登録 API が必要です。

クライアントを使用するプロジェクトの Program.cs ファイルで、AddAzureKeyVaultClient インスタンスの IHostApplicationBuilder 拡張機能を呼び出して、依存関係挿入コンテナー経由で使用する SecretClient を登録します。

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

ビルダーに SecretClient を追加した後、依存関係の挿入を使用して SecretClient インスタンスを取得できます。 たとえば、サンプル サービスからクライアントを取得するには、それをコンストラクター パラメーターとして定義し、ExampleService クラスが依存関係挿入コンテナーに登録されていることを確認します。

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

依存関係の挿入に関する詳細については、.NET 依存関係の挿入を参照してください。

キー付き Azure Key Vault クライアントを追加する

接続名が異なる複数の SecretClient インスタンスを登録する場合があります。 キー付き Azure Key Vault クライアントを登録するには、AddKeyedAzureKeyVaultClient メソッドを呼び出します。

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

その後、依存関係の挿入を使用して SecretClient インスタンスを取得できます。 たとえば、サービスの例からクライアントを取得するには、次のようにします。

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

キー付きサービスの詳細については、「.NET 依存関係の挿入: キー付きサービスの」を参照してください。

構成

.NET AspireAzure Key Vault 統合には、プロジェクトの要件と規則に基づいて SecretClient を構成するための複数のオプションが用意されています。

構成プロバイダーを使用する

.NET AspireAzure Key Vault 統合では、Microsoft.Extensions.Configurationがサポートされます。 AzureSecurityKeyVaultSettings キーを使用して、appsettings.json またはその他の構成ファイルから Aspire:Azure:Security:KeyVault を読み込みます。

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

完全な Azure Key Vault クライアント統合 JSON スキーマについては、Aspireを参照してください。Azure.Security.KeyVault/ConfigurationSchema.json.

Aspire:Azure:Security:KeyVault ファイルの appsettings.json セクションで構成を設定した場合は、パラメーターを渡さずにメソッド AddAzureKeyVaultSecrets を呼び出すことができます。

インライン デリゲートを使用する

Action<AzureSecurityKeyVaultSettings> デリゲートを渡して、一部またはすべてのオプションをインラインで設定することもできます。たとえば、AzureSecurityKeyVaultSettings.VaultUriを設定します。

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

SecretClientOptions メソッドの省略可能なパラメーターである Action<SecretClientOptions> デリゲートを使用して、AddAzureKeyVaultSecrets を設定することもできます。 たとえば、KeyClientOptions.DisableChallengeResourceVerification ID を設定してクライアントを識別するには、次のようにします。

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

構成オプション

次の構成可能なオプションは、AzureSecurityKeyVaultSettings クラスを介して公開されます。

Client 統合健康診断

既定では、.NET.NET Aspireクライアント統合 すべてのサービスで 正常性チェック 有効になっています。 同様に、多くの .NET.NET Aspireホスティング統合 もヘルスチェックエンドポイントを有効にします。 詳細については、以下を参照してください。

• アプリの正常性チェックを C# で行う
• ASP.NET Core における健康診断

.NET AspireAzure Key Vault 統合には、次の正常性チェックが含まれています。

• AzureKeyVaultSecretsHealthCheck 正常性チェックを追加します。これは、Key Vault に接続してクエリを実行しようとします。
• /health HTTP エンドポイントと統合します。このエンドポイントは、アプリがトラフィックを受け入れる準備ができていると見なされるために、登録されているすべての正常性チェックに合格する必要があります

可観測性とテレメトリ

統合により、ログ記録、トレース、メトリックの構成が自動的に設定されます。これは、監視の柱 とも呼ばれます。 統合の可観測性とテレメトリの詳細については、統合の概要 参照してください。 バッキング サービスによっては、一部の統合でこれらの機能の一部のみがサポートされる場合があります。 たとえば、一部の統合ではログ記録とトレースがサポートされますが、メトリックはサポートされません。 テレメトリ機能は、「構成」セクションに記載されている手法を使用して無効にすることもできます。

伐採

.NET AspireAzure Key Vault 統合では、次のログ カテゴリが使用されます。

• Azure.Core
• Azure.Identity

トレース

.NET AspireAzure Key Vault 統合では、OpenTelemetryを使用して次のトレース アクティビティが出力されます。

• Azure.Security.KeyVault.Secrets.SecretClient

メトリック

.NET AspireAzure Key Vault 統合では現在、Azure SDK の制限により、既定ではメトリックがサポートされていません。

関連項目

• Azure Key Vault ドキュメント
• ビデオ: Azure Key Vault と .NET Aspire の概要
• .NET AspireAzure 統合の概要
• .NET.NET Aspire 統合の概要
• .NET AspireGitHub リポジトリ