Sejf úložiště 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 dokument 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. 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í. Místo toho by se k produkčním tajným kódům mělo přistupovat prostřednictvím kontrolovaných prostředků, jako jsou proměnné prostředí nebo Azure Key Vault. Testovací a produkční tajné kódy v Azure můžete ukládat a chránit pomocí zprostředkovatele konfigurace služby Azure Key Vault.

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řepisují 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 uživatelský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.

Upozorňující

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. Dvojité podtržítko (__) se:

• Podporuje všemi platformami. Například Bash nepodporuje oddělovač :, ale oddělovač __ ano.
• Automaticky nahrazeno dvojtečkou (:).

Správce tajných kódů

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. Tajné kódy aplikací se ukládají do samostatného umístění od stromu projektu. Tajné kódy aplikace jsou přidružené ke konkrétnímu projektu nebo jsou sdíleny napříč několika projekty. Tajné kódy aplikace se nezaškrtnou do správy zdrojového kódu.

Upozorňující

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 JSsouboru ON v adresáři profilů uživatelů.

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 JSsouboru ON ve složce profilu uživatele místního počítače:

Windows

Cesta k systému souborů:

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

Linux / macOS

Cesta k systému souborů:

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

V předchozích cestách k souborům UserSecretsId nahraďte <user_secrets_id> hodnotou 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é, ale můžou být v budoucnu.

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žití 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á UserSecretsId prvek v souboru PropertyGroup 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.

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

Použití sady Visual Studio

V sadě Visual Studio klikněte pravým tlačítkem myši na projekt v Průzkumník řešení a v místní nabídce vyberte Spravovat tajné kódy uživatelů. Toto gesto přidá UserSecretsId do souboru projektu prvek 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.cssouboru . Příklad:

[assembly: UserSecretsId("your_user_secrets_id")]

Při ručním přidání atributu UserSecretsId do AssemblyInfo.cssouboru UserSecretsId projektu 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. Tajný kód je přidružený k hodnotě 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 literál objektu ServiceApiKey s vlastností.

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. Příklad:

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

JSZploštění struktury ON v sadě 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. Příklad:

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

Konstrukce 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í literál objektu Movies . Upravený soubor se podobá následujícímu JSZAPNUTO:

{
  "Movies:ServiceApiKey": "12345"
}

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

Dávku tajných kódů lze nastavit tak JS, že k set příkazu použijete funkci ON. 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 tajných klíčů uživatele
2. Čtení tajného kódu prostřednictvím konfiguračního rozhraní API

Registrace zdroje konfigurace tajných klíčů uživatele

Poskytovatel konfigurace tajných kódů uživatelů 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áníAddUserSecrets, pokud jeDevelopment:EnvironmentName

Č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í tajných kódů 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í tajné kódy 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ě ServiceApiKey vlastnosti:

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

Tajné kódy Movies:ConnectionStringMovies:ServiceApiKey jsou mapovány na příslušné vlastnosti v MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Výměna řetězců tajnými kódy

Ukládání hesel ve formátu prostého textu je nezabezpečené. Například databáze připojovací řetězec uložená v appsettings.json zadaném uživateli může obsahovat heslo:

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

Bezpečnějším přístupem je uložení hesla jako tajného kódu. Příklad:

dotnet user-secrets set "DbPassword" "pass123"

Odeberte dvojici Password klíč-hodnota z připojovací řetězec v appsettings.jsonsouboru . Příklad:

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

Hodnotu tajného klíče lze nastavit u SqlConnectionStringBuilder vlastnosti objektu Password a dokončit připojovací řetězec:

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é cílí Microsoft.NET.Sdk.Web automaticky, zahrnují podporu tajných kódů uživatelů. Pro projekty, které cílí Microsoft.NET.Sdk, jako jsou konzolové aplikace, nainstalujte rozšíření konfigurace a tajné kódy uživatelů Balíčky NuGet explicitně.

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

Další materiály

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