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

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.

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

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

Informace o používání uživatelských tajných údajů v konzolové aplikaci .NET najdete v problému GitHub dotnet/entityframework.docs č. 3939.

Práce s proměnnými 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 obsažen v souboru appsettings.json projektu pod 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í aplikace můžete hodnotu klíče DefaultConnection přepsat hodnotou z 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í se běžně ukládají jako prostý, nešifrovaný text. Pokud dojde k ohrožení zabezpečení počítače nebo procesu, jsou proměnné prostředí přístupné nedůvěryhodným stranám. Může se vyžadovat další opatření, která brání zpřístupnění tajných kódů uživatelů.

Oddělovač dvojtečky (:) nefunguje u hierarchických klíčů proměnných prostředí na všech platformách. Například Bash nepodporuje dvojtečku (:) jako oddělovač. Všechny platformy podporují syntaxi dvojitého podtržítka (__) a automaticky ji nahradí dvojtečkam (:).

Použití nástroje Secret Manager

Secret Manager je nástroj, který 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.
• Jsou přidružené ke konkrétnímu projektu nebo jsou sdíleny napříč několika projekty.
• Nejsou zařazeny do systému správy zdrojového kódu.

Warning

Správce tajných kódů neš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.

Správce tajných kódů 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 cestě k souborovému systému nahraďte část <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 ve Správci tajných kódů. Tyto podrobnosti implementace se můžou změnit. Například tajné hodnoty nejsou šifrované.

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

Správce tajných kódů pracuje s nastavením konfigurace pro konkrétní projekt uloženými ve vašem profilu uživatele.

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

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

dotnet user-secrets init

Tento příkaz přidá UserSecretsId prvek 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. Následující příklad ukazuje hodnotu identifikátoru GUID 0000a1a1-b2b2-c3c3-d4d4-eeeeee555555.

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

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

</Project>

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 je „GenerateAssemblyInfo“ „false“

Pokud je generování atributů informací o sestavení (GenerateAssemblyInfo) zakázané (nastaveno na false), přidejte UserSecretsIdAttribute ručně do souboru AssemblyInfo.cs . Například:

[assembly: UserSecretsId("your_user_secrets_id")]

Při ručním přidání UserSecretsId atributu do souboru UserSecretsId musí hodnota odpovídat hodnotě 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 tomto příkladu dvojtečka označuje, že Movies je objektový literál s vlastností ServiceApiKey.

Můžete také použít Secret Manager z jiných adresářů. --project Zahrňte možnost zadat cestu k systému souborů, ve které existuje soubor projektu. 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 Visual Studio Manage User Secrets otevře v textovém editoru soubor secrets.json. Obsah souboru secrets.json nahraďte páry klíč–hodnota určenými k uložení. Například:

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

Struktura JSON je po úpravách zploštěna pomocí dotnet user-secrets remove příkazu nebo dotnet user-secrets set příkazu. 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 se obsah souboru input.json předá do set příkazu.

Windows

Spusťte následující příkaz:

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

Linux / macOS

V terminálu 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. Zaregistrujte zdroj konfigurace tajných kódů uživatele.

2. Přečtěte si tajný klíč 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.

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

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

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

app.Run();

Metoda WebApplication.CreateBuilder inicializuje novou instanci WebApplicationBuilder třídy s předkonfigurovanými výchozími nastaveními. Inicializovaná WebApplicationBuilder (builder) poskytuje výchozí konfiguraci a volá metodu AddUserSecrets, pokud má vlastnost EnvironmentName hodnotu Development.

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

Následující příklady ukazují, jak přečíst Movies:ServiceApiKey klíč:

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

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 souborsecrets.json 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; }
}

Použijte nahrazování řetězců pomocí tajných údajů

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

Například databáze připojovací řetězec uložená v souboru appsettings.json by neměla 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říkladu nahraďte hodnotou hesla. Nastavte hodnotu tajemství na vlastnost SqlConnectionStringBuilder objektu Password, 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 souborsecrets.json 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říkladu dvojtečka (:) v názvech klíčů označuje hierarchii objektů v souboru secrets.json .

Odebrání jednoho tajného kódu

Předpokládejme, že souborsecrets.json 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 secrets.json aplikace se upraví tak, aby odebral dvojici klíč-hodnota přidruženou ke klíči Movies:ConnectionString :

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

Příkaz 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 souborsecrets.json 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

Ze souboru secrets.json se odstraní všechny tajné kódy uživatelů aplikace:

{}

Spuštěním dotnet user-secrets list příkazu 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 Visual Studio, klikněte pravým tlačítkem na projekt v Průzkumník řešení a vyberte Manage User Secrets:

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

Uložené tajné kódy uživatelů můžete migrovat z rozhraní ASP.NET Framework do ASP.NET Core. Další informace najdete v tématu GitHub problém s dotnet/aspnetcore.docs #27611 - Dokumentace tajných kódů uživatelů nezmiňuje nekompatibilitu s AssemblyInfo.cs.

Práce s tajnými 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í.

PowerShell

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

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

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

Po instalaci balíčků inicializujete projekt a nastavíte tajné kódy stejným způsobem jako u webové aplikace. Následující příklad ukazuje konzolovou aplikaci, která načte hodnotu sady tajných kódů pomocí AppSecret klíče:

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Související obsah

• Problém č. 30378 v GitHub repozitáři dotnet/aspnetcore.docs (Ladění v Internetové Informační Služby (IIS))
• Problém GitHub dotnet/aspnetcore.docs č. 16328 (Spuštění v IIS)
• Konfigurace v ASP.NET Core
• poskytovatele konfigurace služby Azure Key Vault