Bezpečné ukládání tajných kódů aplikací při vývoji v ASP.NET Core

Autoři: Rick Anderson a Kirk Larkin

Zobrazení nebo stažení ukázkového kódu (postup stažení)

Tento článek vysvětluje, jak spravovat citlivá data pro aplikaci ASP.NET Core na vývojovém počítači. Nikdy neukládejte hesla ani jiná citlivá data ve zdrojovém kódu nebo konfiguračních souborech. Produkční tajné kódy by se neměly používat pro vývoj ani testování. Tajné kódy by se neměly nasazovat s aplikací. Produkční tajné kódy by měly být přístupné prostřednictvím kontrolovaných prostředků, jako je Azure Key Vault. Testovací a produkční tajné kódy Azure je možné ukládat a chránit pomocí poskytovatele konfigurace služby Azure Key Vault.

Další informace o ověřování nasazených testovacích a produkčních aplikacích naleznete v Bezpečné toky autentizace.

Pokud chcete používat tajné kódy uživatelů v aplikaci konzoly .NET, podívejte se na tento problém na GitHubu.

Proměnné prostředí

Proměnné prostředí se používají k tomu, aby se zabránilo ukládání tajných kódů aplikací v kódu nebo v místních konfiguračních souborech. Proměnné prostředí převyšují hodnoty konfigurace pro všechny dříve zadané zdroje konfigurace.

Zvažte ASP.NET základní webovou aplikaci, ve které je povolené zabezpečení jednotlivých účtů . Výchozí připojovací řetězec databáze je součástí souboru projektu appsettings.json s klíčem DefaultConnection. Výchozí připojovací řetězec je pro LocalDB, která běží v uživatelském režimu a nevyžaduje heslo. Během nasazování DefaultConnection aplikace je možné hodnotu klíče přepsat hodnotou proměnné prostředí. Proměnná prostředí může uložit kompletní připojovací řetězec s citlivými přihlašovacími údaji.

Warning

Proměnné prostředí jsou obecně uložené ve formátu prostého a nešifrovaného textu. Pokud dojde k ohrožení zabezpečení počítače nebo procesu, můžou k proměnným prostředí přistupovat nedůvěryhodné strany. Mohou být vyžadována další opatření, která brání zpřístupnění tajných kódů uživatelů.

Oddělovač : nefunguje s hierarchickými klíči proměnných prostředí na všech platformách. Například oddělovač : není podporován v Bashi. Dvojité podtržítko, __ je podporováno všemi platformami a automaticky nahrazeno dvojtečkou, :.

Správce tajemství

Nástroj Secret Manager ukládá citlivá data během vývoje aplikací. V tomto kontextu je část citlivých dat tajným kódem aplikace. Tajemství aplikací jsou ukládána na samostatné umístění než strom projektu. Tajné kódy aplikace jsou přidružené ke konkrétnímu projektu nebo jsou sdíleny napříč několika projekty. Tajemství aplikace nejsou ukládána do správy verzí.

Warning

Nástroj Secret Manager nezašifruje uložené tajné kódy a neměl by se považovat za důvěryhodné úložiště. Slouží pouze pro účely vývoje. Klíče a hodnoty jsou uloženy v konfiguračním souboru JSON v adresáři profilu uživatele.

Jak funguje nástroj Secret Manager

Nástroj Secret Manager skryje podrobnosti implementace, například kde a jak se hodnoty ukládají. Nástroj můžete použít bez znalosti těchto podrobností implementace. Hodnoty se ukládají do souboru JSON ve složce profilu uživatele místního počítače:

Windows

Cesta souborového systému

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

Linux / macOS

Cesta souborového systému

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

V uvedených cestách k souborům nahraďte <user_secrets_id> hodnotou UserSecretsId zadanou v souboru projektu.

Nezapisujte kód, který závisí na umístění nebo formátu dat uložených pomocí nástroje Secret Manager. Tyto podrobnosti implementace se můžou změnit. Například tajné hodnoty nejsou šifrované.

Povolení úložiště tajných kódů

Nástroj Secret Manager pracuje s nastavením konfigurace specifického pro projekt uloženým ve vašem profilu uživatele.

Použijte rozhraní příkazového řádku

Nástroj Secret Manager obsahuje init příkaz. Pokud chcete používat tajné kódy uživatelů, spusťte v adresáři projektu následující příkaz:

dotnet user-secrets init

Předchozí příkaz přidá prvek UserSecretsId do PropertyGroup souboru projektu. Ve výchozím nastavení je vnitřní text UserSecretsId identifikátoru GUID. Vnitřní text je libovolný, ale je jedinečný pro projekt.

Použití sady Visual Studio

V sadě Visual Studio klikněte pravým tlačítkem myši na projekt v Průzkumníku řešení a v místní nabídce vyberte Spravovat tajnosti uživatele. Toto gesto přidá do souboru projektu prvek UserSecretsId, který je naplněný identifikátorem GUID.

Pokud GenerateAssemblyInfo je false

Pokud je generování atributů informací o sestavení zakázáno, ručně přidejte UserSecretsIdAttribute do AssemblyInfo.cs souboru. Například:

[assembly: UserSecretsId("your_user_secrets_id")]

Při ručním přidání atributu UserSecretsId k AssemblyInfo.cs musí hodnota UserSecretsId odpovídat té v souboru projektu.

Nastavení tajného kódu

Definujte tajný klíč aplikace, který se skládá z klíče a jeho hodnoty. Tajemství je spojeno s hodnotou projektu UserSecretsId. Například z adresáře, ve kterém existuje soubor projektu, spusťte následující příkaz:

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

V předchozím příkladu dvojtečka označuje, že Movies je objektový literál s vlastností ServiceApiKey.

Nástroj Secret Manager lze použít i z jiných adresářů. --project Pomocí možnosti zadejte cestu k systému souborů, ve které soubor projektu existuje. Například:

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

Zploštění struktury JSON v prostředí Visual Studio

Gesto Správa tajných kódů uživatelů sady Visual Studio otevře secrets.json soubor v textovém editoru. Nahraďte obsah secrets.json dvojicemi klíč-hodnota, které se mají uložit. Například:

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

Struktura JSON je zploštěna po úpravách prostřednictvím dotnet user-secrets remove nebo dotnet user-secrets set. Například spuštění dotnet user-secrets remove "Movies:ConnectionString" sbalí objektový literál Movies. Upravený soubor se podobá následujícímu formátu JSON:

{
  "Movies:ServiceApiKey": "12345"
}

Nastavení více tajných kódů

Dávku tajných kódů lze nastavit tak, že do set příkazu prodáte kód JSON. V následujícím příkladu input.json se obsah souboru předá do set příkazu.

Windows

Otevřete příkazové prostředí a spusťte následující příkaz:

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

Linux / macOS

Otevřete příkazové prostředí a spusťte následující příkaz:

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

Přístup k tajnému kódu

Pokud chcete získat přístup k tajnému kódu, proveďte následující kroky:

1. Registrace zdroje konfigurace uživatelských tajemství
2. Čtení tajného kódu prostřednictvím konfiguračního rozhraní API

Registrace zdroje konfigurace uživatelských tajemství

Poskytovatel konfigurace uživatelských tajemství zaregistruje příslušný zdroj konfigurace v rozhraní .NET Configuration API.

Webové aplikace ASP.NET Core vytvořené pomocí příkazu dotnet new nebo sady Visual Studio generují následující kód:

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

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

app.Run();

WebApplication.CreateBuilder inicializuje novou instanci třídy WebApplicationBuilder s předkonfigurovanými výchozími hodnotami. Inicializovaná WebApplicationBuilder (builder) poskytuje výchozí konfiguraci a volá AddUserSecrets, když je EnvironmentNameDevelopment.

Čtení tajného kódu prostřednictvím konfiguračního rozhraní API

Podívejte se na následující příklady čtení Movies:ServiceApiKey klíče:

Program.cs soubor:

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

var app = builder.Build();

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

app.Run();

Razor Model stránky stránky:

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

Další informace najdete v tématu Konfigurace v ASP.NET Core.

Mapování tajností na POCO

Mapování celého literálu objektu na POCO (jednoduchá třída .NET s vlastnostmi) je užitečné pro agregaci souvisejících vlastností.

Předpokládejme, že secrets.json soubor aplikace obsahuje následující dva tajné kódy:

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

Pokud chcete namapovat předchozí tajemství na POCO, použijte funkci vazby objektového grafu rozhraní .NET Configuration API. Následující kód vytvoří vazbu na vlastní MovieSettings POCO a přistupuje k hodnotě vlastnosti ServiceApiKey:

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

Tajemství Movies:ConnectionStringMovies:ServiceApiKey jsou namapována na příslušné vlastnosti v MovieSettings.

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

    public string ServiceApiKey { get; set; }
}

Nahrazování řetězců tajemstvími

Ukládání hesel ve formátu prostého textu je nezabezpečené. Nikdy neukládejte tajemství do konfiguračního souboru, jako je například appsettings.json, který by mohl být omylem zahrnut do úložiště zdrojového kódu.

Například připojovací řetězec databáze uložený v appsettings.json by neměl obsahovat heslo. Místo toho heslo uložte jako tajný klíč a zahrňte ho do připojovacího řetězce za běhu. Například:

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

<secret value> Zástupný symbol v předchozím příkladu nahraďte hodnotou hesla. Nastavte hodnotu tajemství na vlastnost Password objektu SqlConnectionStringBuilder, aby byla zahrnuta jako hodnota hesla v připojovacím řetězci.

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();

Výpis tajných kódů

Předpokládejme, že secrets.json soubor aplikace obsahuje následující dva tajné kódy:

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

Z adresáře, ve kterém existuje soubor projektu, spusťte následující příkaz:

dotnet user-secrets list

Objeví se následující výstup:

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

V předchozím příkladu dvojtečka v názvech klíčů označuje hierarchii objektů v rámci secrets.json.

Odebrání jednoho tajného kódu

Předpokládejme, že secrets.json soubor aplikace obsahuje následující dva tajné kódy:

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

Z adresáře, ve kterém existuje soubor projektu, spusťte následující příkaz:

dotnet user-secrets remove "Movies:ConnectionString"

Soubor aplikace secrets.json byl upraven tak, aby odebral pár klíč-hodnota přidružený ke klíči Movies:ConnectionString :

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

dotnet user-secrets list zobrazí následující zprávu:

Movies:ServiceApiKey = 12345

Odebrání všech tajných kódů

Předpokládejme, že secrets.json soubor aplikace obsahuje následující dva tajné kódy:

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

Z adresáře, ve kterém existuje soubor projektu, spusťte následující příkaz:

dotnet user-secrets clear

Z souboru byly odstraněny secrets.json všechny tajné kódy uživatelů pro aplikaci:

{}

Při spuštění dotnet user-secrets list se zobrazí následující zpráva:

No secrets configured for this application.

Správa tajných kódů uživatelů pomocí sady Visual Studio

Pokud chcete spravovat tajné kódy uživatelů v sadě Visual Studio, klikněte pravým tlačítkem na projekt v Průzkumníku řešení a vyberte Spravovat tajné kódy uživatelů:

Migrace tajných kódů uživatelů z architektury ASP.NET na ASP.NET Core

Podívejte se na tento problém na GitHubu.

Tajné kódy uživatelů v jiných než webových aplikacích

Projekty, které Microsoft.NET.Sdk.Web cíli, automaticky zahrnují podporu uživatelských tajemství. Pro projekty, které cílí Microsoft.NET.Sdk, jako jsou konzolové aplikace, explicitně nainstalujte balíčky NuGet pro rozšíření konfigurace a uživatelská tajemství.

Pomocí PowerShellu:

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

Pomocí rozhraní příkazového řádku .NET:

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

Po instalaci balíčků inicializujte projekt a nastavte tajné kódy stejným způsobem jako u webové aplikace. Následující příklad ukazuje konzolovou aplikaci, která načte hodnotu tajného klíče nastaveného klíčem "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"]);
    }
}

Dodatečné zdroje

• Informace o přístupu k uživatelským tajemstvím ze služby IIS najdete v tomto problému a v tomto problému.
• Konfigurace v ASP.NET Core
• Zprostředkovatel konfigurace služby Azure Key Vault v ASP.NET Core