ASP.NET Core での開発におけるアプリシークレットの安全な保存Safe storage of app secrets in development in ASP.NET Core

Rick AndersonKirk LarkinDaniel RothScott addieBy Rick Anderson, Kirk Larkin, Daniel Roth, and Scott Addie

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

このドキュメントでは、開発用コンピューターで ASP.NET Core アプリの機密データを管理する方法について説明します。This document explains how to manage sensitive data for an ASP.NET Core app on a development machine. パスワードやその他の機密データをソースコードに格納しないでください。Never store passwords or other sensitive data in source code. 運用環境のシークレットは、開発またはテストには使用しないでください。Production secrets shouldn't be used for development or test. シークレットはアプリと一緒にデプロイしないでください。Secrets shouldn't be deployed with the app. 代わりに、運用環境のシークレットには、環境変数や Azure Key Vault などの制御された手段を使用してアクセスする必要があります。Instead, production secrets should be accessed through a controlled means like environment variables or Azure Key Vault. Azure Key Vault 構成プロバイダーにより、Azure テストと運用のシークレットを格納し、保護することが可能です。You can store and protect Azure test and production secrets with the Azure Key Vault configuration provider.

環境変数Environment variables

環境変数は、コードまたはローカル構成ファイルにアプリシークレットを格納しないようにするために使用されます。Environment variables are used to avoid storage of app secrets in code or in local configuration files. 環境変数は、以前に指定したすべての構成ソースの構成値を上書きします。Environment variables override configuration values for all previously specified configuration sources.

個々のユーザーアカウント のセキュリティが有効になっている ASP.NET Core web アプリを考えてみましょう。Consider an ASP.NET Core web app in which Individual User Accounts security is enabled. 既定のデータベース接続文字列は、プロジェクトのファイル内の appsettings.json キーと共に含まれ DefaultConnection ます。A default database connection string is included in the project's appsettings.json file with the key DefaultConnection. 既定の接続文字列は LocalDB 用であり、ユーザーモードで実行され、パスワードは必要ありません。The default connection string is for LocalDB, which runs in user mode and doesn't require a password. アプリの展開時に、 DefaultConnection キー値は環境変数の値でオーバーライドできます。During app deployment, the DefaultConnection key value can be overridden with an environment variable's value. 環境変数には、機密性の高い資格情報を持つ完全な接続文字列が格納される場合があります。The environment variable may store the complete connection string with sensitive credentials.

警告

環境変数は通常、暗号化されていないプレーンテキストで格納されます。Environment variables are generally stored in plain, unencrypted text. コンピューターまたはプロセスが侵害された場合、信頼されていない相手から環境変数にアクセスできます。If the machine or process is compromised, environment variables can be accessed by untrusted parties. ユーザーシークレットが漏えいしないようにするための追加の手段が必要な場合があります。Additional measures to prevent disclosure of user secrets may be required.

: の区切り記号は、すべてのプラットフォームの環境変数階層キーには対応していません。The : separator doesn't work with environment variable hierarchical keys on all platforms. __(ダブルアンダースコア)は、__, the double underscore, is:

  • すべてのプラットフォームに対応しています。Supported by all platforms. たとえば、Bash: の区切り記号には対応していませんが、__ には対応しています。For example, the : separator is not supported by Bash, but __ is.
  • 自動で : に置換されます。Automatically replaced by a :

シークレットマネージャーSecret Manager

Secret Manager ツールは、ASP.NET Core プロジェクトの開発中に機微なデータを保存します。The Secret Manager tool stores sensitive data during the development of an ASP.NET Core project. このコンテキストでは、機密データの一部がアプリシークレットになります。In this context, a piece of sensitive data is an app secret. アプリシークレットは、プロジェクトツリーとは別の場所に格納されます。App secrets are stored in a separate location from the project tree. アプリシークレットは、特定のプロジェクトに関連付けられているか、複数のプロジェクト間で共有されています。The app secrets are associated with a specific project or shared across several projects. アプリシークレットがソース管理にチェックインされていません。The app secrets aren't checked into source control.

警告

シークレットマネージャーツールは、保存されているシークレットを暗号化せず、信頼されたストアとして扱わないでください。The Secret Manager tool doesn't encrypt the stored secrets and shouldn't be treated as a trusted store. 開発目的でのみ使用されます。It's for development purposes only. キーと値は、ユーザープロファイルディレクトリの JSON 構成ファイルに格納されます。The keys and values are stored in a JSON configuration file in the user profile directory.

Secret Manager ツールの動作How the Secret Manager tool works

Secret Manager ツールは、値の格納場所や方法などの実装の詳細を非表示にします。The Secret Manager tool hides implementation details, such as where and how the values are stored. このツールは、実装の詳細を把握していなくても使用できます。You can use the tool without knowing these implementation details. 値は、ローカルコンピューターのユーザープロファイルフォルダー内の JSON ファイルに格納されます。The values are stored in a JSON file in the local machine's user profile folder:

ファイルシステムのパス:File system path:

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

上記のファイルパスで、を <user_secrets_id> UserSecretsId プロジェクトファイルで指定された値に置き換えます。In the preceding file paths, replace <user_secrets_id> with the UserSecretsId value specified in the project file.

シークレットマネージャーツールで保存したデータの場所または形式に依存するコードは記述しないでください。Don't write code that depends on the location or format of data saved with the Secret Manager tool. これらの実装の詳細は変更される可能性があります。These implementation details may change. たとえば、シークレット値は暗号化されませんが、将来の可能性があります。For example, the secret values aren't encrypted, but could be in the future.

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

Secret Manager ツールは、ユーザープロファイルに格納されているプロジェクト固有の構成設定を操作します。The Secret Manager tool operates on project-specific configuration settings stored in your user profile.

Secret Manager ツールには .NET Core SDK 3.0.100 以降のコマンドが含まれてい init ます。The Secret Manager tool includes an init command in .NET Core SDK 3.0.100 or later. ユーザーシークレットを使用するには、プロジェクトディレクトリで次のコマンドを実行します。To use user secrets, run the following command in the project directory:

dotnet user-secrets init

上記のコマンドは、 UserSecretsId プロジェクトファイルの内に要素を追加し PropertyGroup ます。The preceding command adds a UserSecretsId element within a PropertyGroup of the project file. 既定では、の内部テキスト UserSecretsId は GUID です。By default, the inner text of UserSecretsId is a GUID. 内部テキストは任意ですが、プロジェクトに固有です。The inner text is arbitrary, but is unique to the project.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>

Visual Studio で、ソリューションエクスプローラーでプロジェクトを右クリックし、コンテキストメニューから [ ユーザーシークレットの管理 ] を選択します。In Visual Studio, right-click the project in Solution Explorer, and select Manage User Secrets from the context menu. このジェスチャは、GUID が設定された UserSecretsId 要素をプロジェクトファイルに追加します。This gesture adds a UserSecretsId element, populated with a GUID, to the project file.

シークレットを設定するSet a secret

キーとその値で構成されるアプリシークレットを定義します。Define an app secret consisting of a key and its value. シークレットは、プロジェクトの値に関連付けられ UserSecretsId ます。The secret is associated with the project's UserSecretsId value. たとえば、プロジェクトファイルが存在するディレクトリから次のコマンドを実行します。For example, run the following command from the directory in which the project file exists:

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

前の例では、コロンは、がプロパティを持つオブジェクトリテラルであることを示して MoviesServiceApiKey ます。In the preceding example, the colon denotes that Movies is an object literal with a ServiceApiKey property.

シークレットマネージャーツールは、他のディレクトリからも使用できます。The Secret Manager tool can be used from other directories too. オプションを使用して、 --project プロジェクトファイルが存在するファイルシステムパスを指定します。Use the --project option to supply the file system path at which the project file exists. 次に例を示します。For example:

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

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

Visual Studio の [ ユーザーシークレットの管理 ] ジェスチャでは、テキストエディターでファイル のsecrets.js が開きます。Visual Studio's Manage User Secrets gesture opens a secrets.json file in the text editor. secrets.js の内容を、格納されるキーと値のペアに置き換えます。Replace the contents of secrets.json with the key-value pairs to be stored. 次に例を示します。For example:

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

JSON 構造体は、またはを使用した変更後にフラット化され dotnet user-secrets remove dotnet user-secrets set ます。The JSON structure is flattened after modifications via dotnet user-secrets remove or dotnet user-secrets set. たとえば、を実行 dotnet user-secrets remove "Movies:ConnectionString" すると、 Movies オブジェクトリテラルが折りたたまれます。For example, running dotnet user-secrets remove "Movies:ConnectionString" collapses the Movies object literal. 変更されたファイルは、次の JSON のようになります。The modified file resembles the following JSON:

{
  "Movies:ServiceApiKey": "12345"
}

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

シークレットのバッチは、JSON をコマンドにパイプすることによって設定でき set ます。A batch of secrets can be set by piping JSON to the set command. 次の例では、ファイルの内容の input.js がコマンドにパイプされてい set ます。In the following example, the input.json file's contents are piped to the set command.

コマンドシェルを開き、次のコマンドを実行します。Open a command shell, and execute the following command:

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

シークレットへのアクセスAccess a secret

シークレットにアクセスするには、次の手順を実行します。To access a secret, complete the following steps:

  1. ユーザーシークレットの構成ソースを登録するRegister the user secrets configuration source
  2. 構成 API を使用してシークレットを読み取るRead the secret via the Configuration API

ユーザーシークレットの構成ソースを登録するRegister the user secrets configuration source

ユーザーシークレット 構成プロバイダー は、適切な構成ソースを .NET 構成 APIに登録します。The user secrets configuration provider registers the appropriate configuration source with the .NET Configuration API.

ユーザーシークレットの構成ソースは、プロジェクトがを呼び出すときに、開発モードで自動的に追加され CreateDefaultBuilder ます。The user secrets configuration source is automatically added in Development mode when the project calls CreateDefaultBuilder. CreateDefaultBuilderAddUserSecretsがの場合、 EnvironmentName を呼び出し Development ます。CreateDefaultBuilder calls AddUserSecrets when the EnvironmentName is Development:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

CreateDefaultBuilderが呼び出されない場合は、でを呼び出してユーザーシークレットの構成ソースを明示的に追加し AddUserSecrets ConfigureAppConfiguration ます。When CreateDefaultBuilder isn't called, add the user secrets configuration source explicitly by calling AddUserSecrets in ConfigureAppConfiguration. AddUserSecrets次の例に示すように、アプリが開発環境で実行されている場合にのみ、を呼び出します。Call AddUserSecrets only when the app runs in the Development environment, as shown in the following example:

public class Program
{
    public static void Main(string[] args)
    {
        var host = new HostBuilder()
            .ConfigureAppConfiguration((hostContext, builder) =>
            {
                // Add other providers for JSON, etc.

                if (hostContext.HostingEnvironment.IsDevelopment())
                {
                    builder.AddUserSecrets<Program>();
                }
            })
            .Build();
        
        host.Run();
    }
}

構成 API を使用してシークレットを読み取るRead the secret via the Configuration API

ユーザーシークレットの構成ソースが登録されている場合、.NET 構成 API はシークレットを読み取ることができます。If the user secrets configuration source is registered, the .NET Configuration API can read the secrets. コンストラクターインジェクション を使用して、.NET 構成 API にアクセスできます。Constructor injection can be used to gain access to the .NET Configuration API. 次のキーの読み取り例を考えてみましょう Movies:ServiceApiKeyConsider the following examples of reading the Movies:ServiceApiKey key:

スタートアップクラス:Startup class:

public class Startup
{
    private string _moviesApiKey = null;

    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        _moviesApiKey = Configuration["Movies:ServiceApiKey"];
    }

    public void Configure(IApplicationBuilder app)
    {
        app.Run(async (context) =>
        {
            var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
            await context.Response.WriteAsync($"Secret is {result}");
        });
    }
}

Razor ページページモデル:Razor Pages page model:

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

詳細については、ページの「スタートアップとアクセスの Razor 構成アクセス構成」を参照してください。For more information, see Access configuration in Startup and Access configuration in Razor Pages.

シークレットを POCO にマップするMap secrets to a POCO

オブジェクトリテラル全体を POCO (プロパティを持つ単純な .NET クラス) にマップすると、関連するプロパティを集計するのに役立ちます。Mapping an entire object literal to a POCO (a simple .NET class with properties) is useful for aggregating related properties.

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

上記のシークレットを POCO にマップするには、.NET 構成 API の オブジェクトグラフバインド 機能を使用します。To map the preceding secrets to a POCO, use the .NET Configuration API's object graph binding feature. 次のコードは、カスタム POCO にバインド MovieSettings し、 ServiceApiKey プロパティ値にアクセスします。The following code binds to a custom MovieSettings POCO and accesses the ServiceApiKey property value:

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

Movies:ConnectionStringMovies:ServiceApiKey シークレットは、のそれぞれのプロパティにマップされ MovieSettings ます。The Movies:ConnectionString and Movies:ServiceApiKey secrets are mapped to the respective properties in MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

シークレットを使用した文字列の置換String replacement with secrets

プレーンテキストでのパスワードの保存は安全ではありません。Storing passwords in plain text is insecure. たとえば、に格納されているデータベース接続文字列には、 appsettings.json 指定されたユーザーのパスワードが含まれる場合があります。For example, a database connection string stored in appsettings.json may include a password for the specified user:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;Password=pass123;MultipleActiveResultSets=true"
  }
}

より安全な方法は、パスワードをシークレットとして保存することです。A more secure approach is to store the password as a secret. 次に例を示します。For example:

dotnet user-secrets set "DbPassword" "pass123"

Passwordの接続文字列からキーと値のペアを削除 appsettings.json します。Remove the Password key-value pair from the connection string in appsettings.json. 次に例を示します。For example:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;MultipleActiveResultSets=true"
  }
}

シークレットの値は、オブジェクトのプロパティに設定して、接続文字列を完成させることができ SqlConnectionStringBuilder Password ます。The secret's value can be set on a SqlConnectionStringBuilder object's Password property to complete the connection string:

public class Startup
{
    private string _connection = null;

    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var builder = new SqlConnectionStringBuilder(
            Configuration.GetConnectionString("Movies"));
        builder.Password = Configuration["DbPassword"];
        _connection = builder.ConnectionString;

        // code omitted for brevity
    }

    public void Configure(IApplicationBuilder app)
    {
        app.Run(async (context) =>
        {
            await context.Response.WriteAsync($"DB Connection: {_connection}");
        });
    }
}

シークレットを一覧表示するList the secrets

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets list

次のような出力が表示されます。The following output appears:

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

前の例では、キー名のコロンは secrets.js 内のオブジェクト階層を表しています。In the preceding example, a colon in the key names denotes the object hierarchy within secrets.json.

1つのシークレットを削除するRemove a single secret

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets remove "Movies:ConnectionString"

ファイルのアプリの secrets.js は、キーに関連付けられているキーと値のペアを削除するように変更されました MoviesConnectionStringThe app's secrets.json file was modified to remove the key-value pair associated with the MoviesConnectionString key:

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

dotnet user-secrets list 次のメッセージが表示されます。dotnet user-secrets list displays the following message:

Movies:ServiceApiKey = 12345

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

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets clear

アプリのすべてのユーザーシークレットは、ファイルの secrets.js から削除されています。All user secrets for the app have been deleted from the secrets.json file:

{}

dotnet user-secrets listを実行すると、次のメッセージが表示されます。Running dotnet user-secrets list displays the following message:

No secrets configured for this application.

その他のリソースAdditional resources

Rick AndersonDaniel RothScott addieBy Rick Anderson, Daniel Roth, and Scott Addie

サンプル コードを表示またはダウンロードします (ダウンロード方法)。View or download sample code (how to download)

このドキュメントでは、開発用コンピューターで ASP.NET Core アプリの機密データを管理する方法について説明します。This document explains how to manage sensitive data for an ASP.NET Core app on a development machine. パスワードやその他の機密データをソースコードに格納しないでください。Never store passwords or other sensitive data in source code. 運用環境のシークレットは、開発またはテストには使用しないでください。Production secrets shouldn't be used for development or test. シークレットはアプリと一緒にデプロイしないでください。Secrets shouldn't be deployed with the app. 代わりに、運用環境のシークレットには、環境変数や Azure Key Vault などの制御された手段を使用してアクセスする必要があります。Instead, production secrets should be accessed through a controlled means like environment variables or Azure Key Vault. Azure Key Vault 構成プロバイダーにより、Azure テストと運用のシークレットを格納し、保護することが可能です。You can store and protect Azure test and production secrets with the Azure Key Vault configuration provider.

環境変数Environment variables

環境変数は、コードまたはローカル構成ファイルにアプリシークレットを格納しないようにするために使用されます。Environment variables are used to avoid storage of app secrets in code or in local configuration files. 環境変数は、以前に指定したすべての構成ソースの構成値を上書きします。Environment variables override configuration values for all previously specified configuration sources.

個々のユーザーアカウント のセキュリティが有効になっている ASP.NET Core web アプリを考えてみましょう。Consider an ASP.NET Core web app in which Individual User Accounts security is enabled. 既定のデータベース接続文字列は、プロジェクトのファイル内の appsettings.json キーと共に含まれ DefaultConnection ます。A default database connection string is included in the project's appsettings.json file with the key DefaultConnection. 既定の接続文字列は LocalDB 用であり、ユーザーモードで実行され、パスワードは必要ありません。The default connection string is for LocalDB, which runs in user mode and doesn't require a password. アプリの展開時に、 DefaultConnection キー値は環境変数の値でオーバーライドできます。During app deployment, the DefaultConnection key value can be overridden with an environment variable's value. 環境変数には、機密性の高い資格情報を持つ完全な接続文字列が格納される場合があります。The environment variable may store the complete connection string with sensitive credentials.

警告

環境変数は通常、暗号化されていないプレーンテキストで格納されます。Environment variables are generally stored in plain, unencrypted text. コンピューターまたはプロセスが侵害された場合、信頼されていない相手から環境変数にアクセスできます。If the machine or process is compromised, environment variables can be accessed by untrusted parties. ユーザーシークレットが漏えいしないようにするための追加の手段が必要な場合があります。Additional measures to prevent disclosure of user secrets may be required.

: の区切り記号は、すべてのプラットフォームの環境変数階層キーには対応していません。The : separator doesn't work with environment variable hierarchical keys on all platforms. __(ダブルアンダースコア)は、__, the double underscore, is:

  • すべてのプラットフォームに対応しています。Supported by all platforms. たとえば、Bash: の区切り記号には対応していませんが、__ には対応しています。For example, the : separator is not supported by Bash, but __ is.
  • 自動で : に置換されます。Automatically replaced by a :

シークレットマネージャーSecret Manager

Secret Manager ツールは、ASP.NET Core プロジェクトの開発中に機微なデータを保存します。The Secret Manager tool stores sensitive data during the development of an ASP.NET Core project. このコンテキストでは、機密データの一部がアプリシークレットになります。In this context, a piece of sensitive data is an app secret. アプリシークレットは、プロジェクトツリーとは別の場所に格納されます。App secrets are stored in a separate location from the project tree. アプリシークレットは、特定のプロジェクトに関連付けられているか、複数のプロジェクト間で共有されています。The app secrets are associated with a specific project or shared across several projects. アプリシークレットがソース管理にチェックインされていません。The app secrets aren't checked into source control.

警告

シークレットマネージャーツールは、保存されているシークレットを暗号化せず、信頼されたストアとして扱わないでください。The Secret Manager tool doesn't encrypt the stored secrets and shouldn't be treated as a trusted store. 開発目的でのみ使用されます。It's for development purposes only. キーと値は、ユーザープロファイルディレクトリの JSON 構成ファイルに格納されます。The keys and values are stored in a JSON configuration file in the user profile directory.

Secret Manager ツールの動作How the Secret Manager tool works

Secret Manager ツールは、値の格納場所や方法などの実装の詳細を非表示にします。The Secret Manager tool hides implementation details, such as where and how the values are stored. このツールは、実装の詳細を把握していなくても使用できます。You can use the tool without knowing these implementation details. 値は、ローカルコンピューターのユーザープロファイルフォルダー内の JSON ファイルに格納されます。The values are stored in a JSON file in the local machine's user profile folder:

ファイルシステムのパス:File system path:

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

上記のファイルパスで、を <user_secrets_id> UserSecretsId プロジェクトファイルで指定された値に置き換えます。In the preceding file paths, replace <user_secrets_id> with the UserSecretsId value specified in the project file.

シークレットマネージャーツールで保存したデータの場所または形式に依存するコードは記述しないでください。Don't write code that depends on the location or format of data saved with the Secret Manager tool. これらの実装の詳細は変更される可能性があります。These implementation details may change. たとえば、シークレット値は暗号化されませんが、将来の可能性があります。For example, the secret values aren't encrypted, but could be in the future.

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

Secret Manager ツールは、ユーザープロファイルに格納されているプロジェクト固有の構成設定を操作します。The Secret Manager tool operates on project-specific configuration settings stored in your user profile.

ユーザーシークレットを使用するには、 UserSecretsId プロジェクトファイルの内に要素を定義し PropertyGroup ます。To use user secrets, define a UserSecretsId element within a PropertyGroup of the project file. の内部テキスト UserSecretsId は任意ですが、プロジェクトに固有です。The inner text of UserSecretsId is arbitrary, but is unique to the project. 通常、開発者はの GUID を生成 UserSecretsId します。Developers typically generate a GUID for the UserSecretsId.

<PropertyGroup>
  <TargetFramework>netcoreapp2.1</TargetFramework>
  <UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>

ヒント

Visual Studio で、ソリューションエクスプローラーでプロジェクトを右クリックし、コンテキストメニューから [ ユーザーシークレットの管理 ] を選択します。In Visual Studio, right-click the project in Solution Explorer, and select Manage User Secrets from the context menu. このジェスチャは、GUID が設定された UserSecretsId 要素をプロジェクトファイルに追加します。This gesture adds a UserSecretsId element, populated with a GUID, to the project file.

シークレットを設定するSet a secret

キーとその値で構成されるアプリシークレットを定義します。Define an app secret consisting of a key and its value. シークレットは、プロジェクトの値に関連付けられ UserSecretsId ます。The secret is associated with the project's UserSecretsId value. たとえば、プロジェクトファイルが存在するディレクトリから次のコマンドを実行します。For example, run the following command from the directory in which the project file exists:

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

前の例では、コロンは、がプロパティを持つオブジェクトリテラルであることを示して MoviesServiceApiKey ます。In the preceding example, the colon denotes that Movies is an object literal with a ServiceApiKey property.

シークレットマネージャーツールは、他のディレクトリからも使用できます。The Secret Manager tool can be used from other directories too. オプションを使用して、 --project プロジェクトファイルが存在するファイルシステムパスを指定します。Use the --project option to supply the file system path at which the project file exists. 次に例を示します。For example:

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

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

Visual Studio の [ ユーザーシークレットの管理 ] ジェスチャでは、テキストエディターでファイル のsecrets.js が開きます。Visual Studio's Manage User Secrets gesture opens a secrets.json file in the text editor. secrets.js の内容を、格納されるキーと値のペアに置き換えます。Replace the contents of secrets.json with the key-value pairs to be stored. 次に例を示します。For example:

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

JSON 構造体は、またはを使用した変更後にフラット化され dotnet user-secrets remove dotnet user-secrets set ます。The JSON structure is flattened after modifications via dotnet user-secrets remove or dotnet user-secrets set. たとえば、を実行 dotnet user-secrets remove "Movies:ConnectionString" すると、 Movies オブジェクトリテラルが折りたたまれます。For example, running dotnet user-secrets remove "Movies:ConnectionString" collapses the Movies object literal. 変更されたファイルは、次の JSON のようになります。The modified file resembles the following JSON:

{
  "Movies:ServiceApiKey": "12345"
}

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

シークレットのバッチは、JSON をコマンドにパイプすることによって設定でき set ます。A batch of secrets can be set by piping JSON to the set command. 次の例では、ファイルの内容の input.js がコマンドにパイプされてい set ます。In the following example, the input.json file's contents are piped to the set command.

コマンドシェルを開き、次のコマンドを実行します。Open a command shell, and execute the following command:

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

シークレットへのアクセスAccess a secret

構成 APIは、ユーザーシークレットへのアクセスを提供します。The Configuration API provides access to user secrets.

プロジェクトが .NET Framework 対象である場合は、Microsoft.Extensions.Configuration をインストールし ます。UserSecrets NuGet パッケージ。If your project targets .NET Framework, install the Microsoft.Extensions.Configuration.UserSecrets NuGet package.

ASP.NET Core 2.0 以降では、プロジェクトがを呼び出すときに、ユーザーシークレットの構成ソースが開発モードで自動的に追加され CreateDefaultBuilder ます。In ASP.NET Core 2.0 or later, the user secrets configuration source is automatically added in development mode when the project calls CreateDefaultBuilder. CreateDefaultBuilderAddUserSecretsがの場合、 EnvironmentName を呼び出し Development ます。CreateDefaultBuilder calls AddUserSecrets when the EnvironmentName is Development:

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

CreateDefaultBuilderが呼び出されない場合は、コンストラクターでを呼び出すことによって、ユーザーシークレット構成ソースを明示的に追加し AddUserSecrets Startup ます。When CreateDefaultBuilder isn't called, add the user secrets configuration source explicitly by calling AddUserSecrets in the Startup constructor. AddUserSecrets次の例に示すように、アプリが開発環境で実行されている場合にのみ、を呼び出します。Call AddUserSecrets only when the app runs in the Development environment, as shown in the following example:

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", 
                     optional: false, 
                     reloadOnChange: true)
        .AddEnvironmentVariables();

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    Configuration = builder.Build();
}

ユーザーシークレットは、.NET 構成 API を使用して取得できます。User secrets can be retrieved via the .NET Configuration API:

public class Startup
{
    private string _moviesApiKey = null;

    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        _moviesApiKey = Configuration["Movies:ServiceApiKey"];
    }

    public void Configure(IApplicationBuilder app)
    {
        app.Run(async (context) =>
        {
            var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
            await context.Response.WriteAsync($"Secret is {result}");
        });
    }
}

シークレットを POCO にマップするMap secrets to a POCO

オブジェクトリテラル全体を POCO (プロパティを持つ単純な .NET クラス) にマップすると、関連するプロパティを集計するのに役立ちます。Mapping an entire object literal to a POCO (a simple .NET class with properties) is useful for aggregating related properties.

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

上記のシークレットを POCO にマップするには、.NET 構成 API の オブジェクトグラフバインド 機能を使用します。To map the preceding secrets to a POCO, use the .NET Configuration API's object graph binding feature. 次のコードは、カスタム POCO にバインド MovieSettings し、 ServiceApiKey プロパティ値にアクセスします。The following code binds to a custom MovieSettings POCO and accesses the ServiceApiKey property value:

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

Movies:ConnectionStringMovies:ServiceApiKey シークレットは、のそれぞれのプロパティにマップされ MovieSettings ます。The Movies:ConnectionString and Movies:ServiceApiKey secrets are mapped to the respective properties in MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

シークレットを使用した文字列の置換String replacement with secrets

プレーンテキストでのパスワードの保存は安全ではありません。Storing passwords in plain text is insecure. たとえば、に格納されているデータベース接続文字列には、 appsettings.json 指定されたユーザーのパスワードが含まれる場合があります。For example, a database connection string stored in appsettings.json may include a password for the specified user:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;Password=pass123;MultipleActiveResultSets=true"
  }
}

より安全な方法は、パスワードをシークレットとして保存することです。A more secure approach is to store the password as a secret. 次に例を示します。For example:

dotnet user-secrets set "DbPassword" "pass123"

Passwordの接続文字列からキーと値のペアを削除 appsettings.json します。Remove the Password key-value pair from the connection string in appsettings.json. 次に例を示します。For example:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;MultipleActiveResultSets=true"
  }
}

シークレットの値は、オブジェクトのプロパティに設定して、接続文字列を完成させることができ SqlConnectionStringBuilder Password ます。The secret's value can be set on a SqlConnectionStringBuilder object's Password property to complete the connection string:

public class Startup
{
    private string _connection = null;

    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        var builder = new SqlConnectionStringBuilder(
            Configuration.GetConnectionString("Movies"));
        builder.Password = Configuration["DbPassword"];
        _connection = builder.ConnectionString;
    }

    public void Configure(IApplicationBuilder app)
    {
        app.Run(async (context) =>
        {
            await context.Response.WriteAsync($"DB Connection: {_connection}");
        });
    }
}

シークレットを一覧表示するList the secrets

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets list

次のような出力が表示されます。The following output appears:

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

前の例では、キー名のコロンは secrets.js 内のオブジェクト階層を表しています。In the preceding example, a colon in the key names denotes the object hierarchy within secrets.json.

1つのシークレットを削除するRemove a single secret

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets remove "Movies:ConnectionString"

ファイルのアプリの secrets.js は、キーに関連付けられているキーと値のペアを削除するように変更されました MoviesConnectionStringThe app's secrets.json file was modified to remove the key-value pair associated with the MoviesConnectionString key:

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

dotnet user-secrets listを実行すると、次のメッセージが表示されます。Running dotnet user-secrets list displays the following message:

Movies:ServiceApiKey = 12345

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

アプリの秘密情報の jsonファイルには、次の2つのシークレットが含まれているとします。Assume the app's secrets.json file contains the following two secrets:

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

プロジェクトファイルが存在するディレクトリから、次のコマンドを実行します。Run the following command from the directory in which the project file exists:

dotnet user-secrets clear

アプリのすべてのユーザーシークレットは、ファイルの secrets.js から削除されています。All user secrets for the app have been deleted from the secrets.json file:

{}

dotnet user-secrets listを実行すると、次のメッセージが表示されます。Running dotnet user-secrets list displays the following message:

No secrets configured for this application.

その他のリソースAdditional resources