ASP.NET Core での開発におけるアプリ シークレットの安全な保存

作成者: Rick Anderson および Kirk Larkin

この記事では、開発用コンピューター上の ASP.NET Core アプリの機密データを管理する方法について説明します。 パスワードやその他の機密データをソース コードや構成ファイルに保存しないでください。 運用環境のシークレットは、開発またはテストには使用しないでください。 アプリと一緒にシークレットを展開しないでください。 運用シークレットには、Azure Key Vault などの制御された手段を使用してアクセスする必要があります。 Azure のテストシークレットと運用シークレットは、 Azure Key Vault 構成プロバイダーで格納および保護できます。

サンプル コードを表示またはダウンロードする (ダウンロード方法)

デプロイされたテスト アプリと運用アプリの認証の詳細については、「セキュリティで保護された認証フロー」をご覧ください。

.NET コンソール アプリでユーザー シークレットを使用するには、GitHub dotnet/entityframework.docs の問題 #3939 を参照してください。

環境変数を操作する

環境変数は、コードやローカル構成ファイルにアプリのシークレットを格納しないようにするために使用されます。 環境変数によって、以前に指定したすべての構成ソースの構成値がオーバーライドされます。

個々のアカウントのセキュリティが有効になっている ASP.NET Core Web アプリについて考えてみましょう。 プロジェクトの appsettings.json ファイルには、DefaultConnection キーを使用した既定のデータベース接続文字列が含まれています。 既定の接続文字列は、ユーザー モードで実行され、パスワードを必要としない LocalDB 用です。 アプリのデプロイ中に、 DefaultConnection キーの値を環境変数の値でオーバーライドできます。 環境変数には、機密性の高い資格情報を持つ完全な接続文字列が格納される場合があります。

Warning

環境変数は通常、プレーンで暗号化されていないテキストとして格納されます。 マシンまたはプロセスが侵害された場合、環境変数には信頼されていない関係者がアクセスできます。 ユーザー シークレットの漏えいを防ぐための追加の対策が必要になる場合があります。

コロン (:) の区切り記号は、すべてのプラットフォームの環境変数階層キーには対応していません。 たとえば、 Bash では、区切り記号としてコロン (:) はサポートされていません。 すべてのプラットフォームで、二重アンダースコア (__) 構文がサポートされ、自動的にコロン (:) に置き換えられます。

Secret Manager ツールを使用する

Secret Manager は、アプリケーションの開発中に機密データを格納するツールです。 このコンテキストでは、機密データの一部は アプリ シークレットです。

• アプリのシークレットは、プロジェクト ツリーとは別の場所に格納されます。
• 特定のプロジェクトに関連付けられているか、複数のプロジェクト間で共有されます。
• ソース管理システムにはチェックインされていません。

Warning

シークレット マネージャーは、保存されているシークレットを暗号化しないため、信頼できるストアとして扱うべきではありません。 それは開発のみを目的としたものです。 キーと値は、ユーザー プロファイルのディレクトリの JSON 構成ファイルに格納されます。

Secret Manager では、値の格納場所や格納方法など、実装の詳細が非表示になります。 これらの実装の詳細について知らなくても、このツールを使用できます。 値は、ローカル コンピューターのユーザー プロファイル フォルダー内の JSON ファイルに格納されます。

Windows

ファイル システム パス:

%APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json

Linux/macOS

ファイル システム パス:

~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

ファイル システム パスで、 <user_secrets_id> 部分をプロジェクト ファイルで指定した UserSecretsId 値に置き換えます。

Secret Manager で保存されたデータの場所または形式に依存するコードを記述しないでください。 これらの実装の詳細は変更される可能性があります。 たとえば、シークレットの値は暗号化されません。

シークレット ストレージを有効にする

Secret Manager は、ユーザー プロファイルに格納されているプロジェクト固有の構成設定に対して動作します。

CLI の使用

シークレット マネージャーには、 init コマンドが含まれています。 ユーザー シークレットを使うには、プロジェクト ディレクトリで次のコマンドを実行します。

dotnet user-secrets init

このコマンドは、プロジェクト ファイルのUserSecretsId内にPropertyGroup要素を追加します。 既定では、UserSecretsId の内部テキストは GUID です。 内部テキストは任意ですが、プロジェクトに固有です。 次の例は、 0000a1a1-b2b2-c3c3-d4d4-eeeeee555555の GUID 値を示しています。

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <UserSecretsId>0000a1a1-b2b2-c3c3-d4d4-eeeeee555555</UserSecretsId>
  </PropertyGroup>

</Project>

Visual Studio を使用する

Visual Studio のソリューション エクスプローラーでプロジェクトを右クリックし、コンテキスト メニューから [ユーザー シークレットの管理] を選びます。 これにより、UserSecretsId 要素が GUID を含んだ状態でプロジェクト ファイルに追加されます。

'GenerateAssemblyInfo' が 'false' の場合

アセンブリ情報属性 (GenerateAssemblyInfo) の生成が無効になっている (falseに設定されている) 場合は、UserSecretsIdAttributeを手動で追加します。 例えば次が挙げられます。

[assembly: UserSecretsId("your_user_secrets_id")]

UserSecretsId属性をAssemblyInfo.cs ファイルに手動で追加する場合、UserSecretsIdの値はプロジェクト ファイル内の値と一致する必要があります。

シークレットを設定する

キーとその値で構成されるアプリ シークレットを定義します。 シークレットは、プロジェクトの UserSecretsId の値に関連付けられます。 たとえば、プロジェクト ファイルが存在するディレクトリから次のコマンドを実行します。

dotnet user-secrets set "Movies:ServiceApiKey" "12345"

この例では、コロンは、 Movies が ServiceApiKey プロパティを持つオブジェクト リテラルであることを示します。

他のディレクトリからシークレット マネージャーを使用することもできます。 プロジェクト ファイルが存在するファイル システム パスを指定する --project オプションを含めます。 例えば次が挙げられます。

dotnet user-secrets set "Movies:ServiceApiKey" "12345" --project "C:\apps\WebApp1\src\WebApp1"

Visual Studio での JSON 構造のフラット化

Visual Studio Manage User Secrets ジェスチャは、テキスト エディターで secrets.json ファイルを開きます。 secrets.json ファイルの内容を、格納するキーと値のペアに置き換えます。 例えば次が挙げられます。

{
  "Movies": {
    "ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
    "ServiceApiKey": "12345"
  }
}

JSON 構造は、 dotnet user-secrets remove または dotnet user-secrets set コマンドを使用して変更した後にフラット化されます。 たとえば、dotnet user-secrets remove "Movies:ConnectionString" を実行すると、Movies オブジェクト リテラルが折りたたまれます。 変更後のファイルは、次の JSON のようになります。

{
  "Movies:ServiceApiKey": "12345"
}

複数のシークレットを設定する

JSON を set コマンドにパイプすると、シークレットのバッチを設定できます。 次の例では、 input.json ファイルの内容が set コマンドにパイプ処理されます。

Windows

次のコマンドを実行します。

type .\input.json | dotnet user-secrets set

Linux/macOS

ターミナルで次のコマンドを実行します。

cat ./input.json | dotnet user-secrets set

シークレットにアクセスする

シークレットにアクセスするには、次の手順を実行します。

1. ユーザー シークレット構成ソースを登録します。

2. Configuration API を使用してシークレットを読み取ります。

ユーザー シークレットの構成ソースを登録する

ユーザー シークレットの構成プロバイダーにより、適切な構成ソースが .NET の Configuration API に登録されます。

dotnet new コマンドまたは Visual Studio で作成された ASP.NET Core Web アプリでは、次のコードが生成されます。

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

WebApplication.CreateBuilder メソッドは、構成済みの既定値を使用して、WebApplicationBuilder クラスの新しいインスタンスを初期化します。 初期化されたWebApplicationBuilder (builder) は、既定の構成を提供し、AddUserSecrets プロパティがEnvironmentNameされたときにDevelopment メソッドを呼び出します。

Configuration API を使用してシークレットを読み取る

次の例では、 Movies:ServiceApiKey キーを読み取る方法を示します。

Program.cs ファイル

var builder = WebApplication.CreateBuilder(args);
var movieApiKey = builder.Configuration["Movies:ServiceApiKey"];

var app = builder.Build();

app.MapGet("/", () => movieApiKey);

app.Run();

Razor Pages ページ モデル

public class IndexModel : PageModel
{
    private readonly IConfiguration _config;

    public IndexModel(IConfiguration config)
    {
        _config = config;
    }

    public void OnGet()
    {
        var moviesApiKey = _config["Movies:ServiceApiKey"];

        // call Movies service with the API key
    }
}

詳細については、「ASP.NET Core の構成」を参照してください。

シークレットを POCO にマップする

オブジェクト リテラル全体を POCO (プロパティを持つ単純な .NET クラス) にマップすると、関連するプロパティを集計するのに役立ちます。

アプリケーション secrets.json ファイルに次の 2 つのシークレットが含まれているとします。

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

前のシークレットを POCO にマップするには、.NET Configuration API のオブジェクト グラフ バインド機能を使います。 次のコードは、カスタム MovieSettings POCO にバインドされていて、ServiceApiKey プロパティ値にアクセスします。

var moviesConfig = 
    Configuration.GetSection("Movies").Get<MovieSettings>();
_moviesApiKey = moviesConfig.ServiceApiKey;

シークレット Movies:ConnectionString と Movies:ServiceApiKey は、MovieSettings のそれぞれのプロパティにマップされます。

public class MovieSettings
{
    public string ConnectionString { get; set; }

    public string ServiceApiKey { get; set; }
}

シークレットを使用した文字列置換を行う

プレーンテキストでのパスワードの保存は安全ではありません。 appsettings.jsonなどの構成ファイルにシークレットを格納しないでください。このファイルは、ソース コード リポジトリにチェックインされる可能性があります。

たとえば、appsettings.json ファイルに保存されたデータベース接続文字列には、パスワードを含めるべきではありません。 代わりに、パスワードをシークレットとして格納し、実行時に接続文字列にパスワードを含めます。 例えば次が挙げられます。

dotnet user-secrets set "DbPassword" "`<secret value>`"

例の <secret value> プレースホルダーをパスワード値に置き換えます。 SqlConnectionStringBuilder オブジェクトの Password プロパティにシークレットの値を設定して、接続文字列にパスワード値として含めます。

using System.Data.SqlClient;

var builder = WebApplication.CreateBuilder(args);

var conStrBuilder = new SqlConnectionStringBuilder(
        builder.Configuration.GetConnectionString("Movies"));
conStrBuilder.Password = builder.Configuration["DbPassword"];
var connection = conStrBuilder.ConnectionString;

var app = builder.Build();

app.MapGet("/", () => connection);

app.Run();

シークレットの一覧を表示する

アプリケーション secrets.json ファイルに次の 2 つのシークレットが含まれているとします。

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

プロジェクト ファイルが存在するディレクトリから、次のコマンドを実行します。

dotnet user-secrets list

次のような出力が表示されます。

Movies:ConnectionString = Server=(localdb)\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true
Movies:ServiceApiKey = 12345

この例では、キー名のコロン (:) は 、secrets.json ファイル内のオブジェクト階層を示しています。

1 つのシークレットを削除する

アプリケーション secrets.json ファイルに次の 2 つのシークレットが含まれているとします。

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

プロジェクト ファイルが存在するディレクトリから、次のコマンドを実行します。

dotnet user-secrets remove "Movies:ConnectionString"

アプリケーション secrets.json ファイルが変更され、 Movies:ConnectionString キーに関連付けられているキーと値のペアが削除されます。

{
  "Movies": {
    "ServiceApiKey": "12345"
  }
}

dotnet user-secrets list コマンドは、次のメッセージを表示します。

Movies:ServiceApiKey = 12345

すべてのシークレットを削除する

アプリケーション secrets.json ファイルに次の 2 つのシークレットが含まれているとします。

{
  "Movies:ConnectionString": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;Trusted_Connection=True;MultipleActiveResultSets=true",
  "Movies:ServiceApiKey": "12345"
}

プロジェクト ファイルが存在するディレクトリから、次のコマンドを実行します。

dotnet user-secrets clear

アプリのすべてのユーザー シークレットは、 secrets.json ファイルから削除されます。

{}

dotnet user-secrets list コマンドを実行すると、次のメッセージが表示されます。

No secrets configured for this application.

Visual Studio でユーザー シークレットを管理する

Visual Studioでユーザー シークレットを管理するには、ソリューション エクスプローラーでプロジェクトを右クリックし、Manage ユーザー シークレット:

ASP.NET Framework から ASP.NET Core にユーザー シークレットを移行する

保存されているユーザー シークレットを ASP.NET Framework から ASP.NET Core に移行できます。 詳細については、「GitHub dotnet/aspnetcore.docs issue #27611 - User Secrets のドキュメントでは、AssemblyInfo.cs との非互換性については説明しません。

Web 以外のアプリケーションでユーザー シークレットを操作する

Microsoft.NET.Sdk.Web をターゲットとするプロジェクトには、ユーザー シークレットのサポートが自動的に含まれます。 コンソール アプリケーションなど、Microsoft.NET.Sdk をターゲットとするプロジェクトの場合は、構成拡張機能とユーザー シークレット NuGet パッケージを明示的にインストールします。

PowerShell

Install-Package Microsoft.Extensions.Configuration
Install-Package Microsoft.Extensions.Configuration.UserSecrets

.NET CLI

dotnet add package Microsoft.Extensions.Configuration
dotnet add package Microsoft.Extensions.Configuration.UserSecrets

パッケージをインストールしたら、 プロジェクトを初期化 し、Web アプリの場合と同じ方法で シークレットを設定 します。 次の例は、 AppSecret キーを使用してシークレット セットの値を取得するコンソール アプリケーションを示しています。

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

class Program
{
    static void Main(string[] args)
    {
        IConfigurationRoot config = new ConfigurationBuilder()
            .AddUserSecrets<Program>()
            .Build();

        Console.WriteLine(config["AppSecret"]);
    }
}

関連するコンテンツ

• GitHub dotnet/aspnetcore.docs の問題 #30378 (インターネット インフォメーション サービス (IIS) でのデバッグ))
• GitHub dotnet/aspnetcore.docs 問題 #16328 (IIS で実行)
• ASP.NET Core での構成
• Azure Key Vault 構成プロバイダー