在 ASP.NET Core 的開發中安全儲存應用程式秘密

作者：Rick Anderson 與 Kirk Larkin

檢視或下載範例程式碼 \(英文\) (如何下載)

本文說明如何在開發計算機上管理 ASP.NET Core 應用程式的敏感數據。 永遠不要將密碼或其他敏感數據儲存在原始程式碼或組態檔中。 生產秘密不應該用於開發或測試。 不應使用應用程式部署秘密。 生產秘密應該透過 Azure 金鑰保存庫 之類的受控制方式來存取。 您可以使用 Azure 金鑰保存庫 組態提供者來儲存及保護 Azure 測試和生產秘密。

如需已部署測試與實際執行應用程式驗證的詳細資訊，請參閱安全驗證流程。

若要在 .NET 主控台應用程式中使用使用者密碼，請參閱 此 GitHub 問題。

環境變數

環境變數可用來避免在程式碼或本機組態檔中儲存應用程式秘密。 環境變數會覆寫所有先前指定之組態來源的設定值。

請考慮啟用個別使用者帳戶安全性的 ASP.NET Core Web 應用程式。 預設資料庫連接字串包含在專案的 appsettings.json 檔案中，索引鍵為 DefaultConnection。 預設連接字串適用於 LocalDB，其會在使用者模式中執行，而且不需要密碼。 在應用程式部署期間，可以使用環境變數值覆寫 DefaultConnection 索引鍵值。 環境變數可能會使用敏感性認證來儲存完整的連接字串。

警告

環境變數通常會以純文字、未加密的文字儲存。 如果電腦或流程遭到入侵，則不受信任的合作對象可以存取環境變數。 可能需要額外的措施，以防止洩漏使用者秘密。

: 分隔符號不適用於所有平台上的環境變數階層式機碼。 例如，Bash 不支援 : 分隔符號。 雙底線， __，為：

• 所有平台都支援。
• 自動替換為冒號， :。

秘密管理員

秘密管理員工具會在應用程式開發期間儲存敏感性資料。 在此內容中，機密資料片段是應用程式秘密。 應用程式秘密會儲存在專案樹狀目錄的個別位置。 應用程式秘密會與特定專案相關聯，或跨數個專案共用。 應用程式秘密不會簽入原始檔控制。

警告

秘密管理員工具不會加密儲存的秘密，不應被視為受信任的存放區。 僅供開發之用。 索引鍵和值會儲存在使用者設定檔目錄中 JSON 設定檔中。

秘密管理員工具的運作方式

秘密管理員工具會隱藏實作詳細資料，例如儲存值的位置和方式。 您可以在不知道這些實作詳細資料的情況下使用此工具。 這些值會儲存在本機電腦使用者設定檔資料夾中的 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 工具會針對儲存在使用者設定檔中的專案特定組態設定運作。

使用 CLI

秘密管理員工具組含 init 命令。 若要使用使用者密碼，請在專案目錄中執行下列命令：

dotnet user-secrets init

上述命令會在專案檔 PropertyGroup 內新增 UserSecretsId 元素。 根據預設，UserSecretsId 的內部文字是 GUID。 內部文字是任意的，但對專案而言是唯一的。

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

使用 Visual Studio

在 Visual Studio 中，以滑鼠右鍵按一下 [方案總管] 中的專案，然後從操作功能表中選取 [管理使用者密碼]。 此手勢會將填入 GUID 的 UserSecretsId 元素新增至專案檔。

如果 GenerateAssemblyInfo 為 false

如果已停用組件資訊屬性的產生，請在 AssemblyInfo.cs 中手動新增 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 管理使用者密碼手勢會在文字編輯器中開啟 secrets.json 檔案。 將 secrets.json 的內容取代為要儲存的機碼值組。 例如：

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

透過 dotnet user-secrets remove 或 dotnet user-secrets set 修改之後，JSON 結構會扁平化。 例如，執行 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. 透過組態 API 讀取秘密

註冊使用者秘密組態來源

使用者密碼組態提供者向 .NET 組態 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) 提供預設組態，當 EnvironmentName 為 Development 時呼叫 AddUserSecrets：

透過設定 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 頁面頁面模型：

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 檔案包含下列兩個秘密：

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

若要將上述秘密對應至 POCO，請使用 .NET 組態 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> 上述範例中的佔位元取代為密碼值。 在物件的 Password 屬性上SqlConnectionStringBuilder設定秘密的值，使其包含在 連接字串 中的密碼值：

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 檔案包含下列兩個秘密：

{
  "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 中的物件階層。

移除單一秘密

假設應用程式的 secrets.json 檔案包含下列兩個秘密：

{
  "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 檔案包含下列兩個秘密：

{
  "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 中管理使用者密碼，請以滑鼠右鍵按一下方案總管中的專案，然後選取 [管理使用者密碼]：

將使用者秘密從 ASP.NET Framework 移轉至 ASP.NET Core

請參閱這個 GitHub 問題。

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

其他資源

• 如需從 IIS 存取使用者密碼的相關資訊，請參閱 此問題 和 此問題。
• ASP.NET Core 中的組態
• ASP.NET Core 中的 Azure Key Vault 組態提供者