Bezpieczne przechowywanie tajemnic aplikacji podczas rozwoju w ASP.NET Core

Autorzy: Rick Anderson i Kirk Larkin

W tym artykule wyjaśniono, jak zarządzać poufnymi danymi dla aplikacji ASP.NET Core na maszynie dewelopera. Nigdy nie przechowuj haseł ani innych poufnych danych w kodzie źródłowym lub plikach konfiguracji. Wpisy tajne produkcyjne nie powinny być używane do programowania ani testowania. Tajne dane nie powinny być wdrażane razem z aplikacją. Dostęp do sekretów produkcyjnych należy uzyskać za pośrednictwem kontrolowanych środków, takich jak usługa Azure Key Vault. Tajemnice testowania i produkcji Azure można przechowywać i chronić za pomocą dostawcy konfiguracji Azure Key Vault.

Wyświetlanie lub pobieranie przykładowego kodu (jak pobrać)

Aby uzyskać więcej informacji na temat uwierzytelniania dla wdrożonych aplikacji testowych i produkcyjnych, zobacz Bezpieczne przepływy uwierzytelniania.

Aby skorzystać z wpisów tajnych użytkownika w aplikacji konsolowej .NET, zobacz zgłoszenie #3939 w repozytorium GitHub dotnet/entityframework.docs.

Praca ze zmiennymi środowiskowymi

Zmienne środowiskowe służą do unikania przechowywania tajnych danych aplikacji w kodzie lub w lokalnych plikach konfiguracji. Zmienne środowiskowe zastępują wartości konfiguracji dla wszystkich wcześniej określonych źródeł konfiguracji.

Rozważ aplikację internetową ASP.NET Core, w której włączone są zabezpieczenia Indywidualnych Kont. Domyślny ciąg połączenia z bazą danych jest zawarty w pliku projektu appsettings.json pod kluczem DefaultConnection. Domyślny ciąg połączenia to LocalDB, który działa w trybie użytkownika i nie wymaga hasła. Podczas wdrażania aplikacji można zastąpić DefaultConnection wartość klucza wartością ze zmiennej środowiskowej. Zmienna środowiskowa może przechowywać pełne parametry połączenia wraz z poufnymi poświadczeniami.

Warning

Zmienne środowiskowe są często przechowywane jako zwykły, niezaszyfrowany tekst. W przypadku naruszenia zabezpieczeń maszyny lub procesu zmienne środowiskowe są dostępne dla niezaufanych stron. Mogą być wymagane dodatkowe środki, aby zapobiec ujawnieniu wpisów tajnych użytkownika.

Separator dwukropkowy (:) nie działa z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. Na przykład Bash nie obsługuje dwukropka (:) jako separatora. Wszystkie platformy obsługują składnię podwójnego znaku podkreślenia (__) i automatycznie zastępują go dwukropkiem (:).

Korzystanie z narzędzia Secret Manager

Secret Manager to narzędzie, które przechowuje poufne dane podczas tworzenia aplikacji. W tym kontekście jednym z poufnych danych jest klucz tajny aplikacji.

• Tajne dane aplikacji są przechowywane w lokalizacji oddzielonej od drzewa projektu.
• Są one skojarzone z określonym projektem lub współużytkowane w kilku projektach.
• Nie są one zaewidencjonowane w kontroli źródła.

Warning

Secret Manager nie szyfruje przechowywanych sekretów i nie należy traktować go jako zaufanego miejsca przechowywania. Jest to tylko do celów programistycznych. Klucze i wartości są przechowywane w pliku konfiguracji JSON w katalogu profilu użytkownika.

Menedżer sekretów ukrywa szczegóły implementacji, takie jak to, gdzie i w jaki sposób przechowywane są wartości. Możesz użyć narzędzia bez znajomości tych szczegółów implementacji. Wartości są przechowywane w pliku JSON w folderze profilu użytkownika komputera lokalnego:

Windows

Ścieżka systemu plików:

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

Linux/macOS

Ścieżka systemu plików:

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

W ścieżce systemu plików zastąp <user_secrets_id> część wartością UserSecretsId określoną w pliku projektu.

Nie zapisuj kodu, który zależy od lokalizacji lub formatu danych zapisanych w programie Secret Manager. Te szczegóły implementacji mogą ulec zmianie. Na przykład tajne wartości nie są szyfrowane.

Włącz magazyn tajny

Menedżer sekretów działa w oparciu o ustawienia konfiguracji specyficzne dla projektu przechowywane w Twoim profilu użytkownika.

Użyj interfejsu wiersza poleceń

Menedżer sekretów zawiera polecenie init. Aby użyć tajemnic użytkownika, uruchom następujące polecenie w katalogu projektu.

dotnet user-secrets init

To polecenie dodaje element UserSecretsId wewnątrz elementu PropertyGroup pliku projektu. Domyślnie wewnętrzny tekst UserSecretsId to identyfikator GUID. Tekst wewnętrzny jest dowolny, ale jest unikatowy dla projektu. W poniższym przykładzie przedstawiono wartość identyfikatora 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>

Korzystanie z programu Visual Studio

W programie Visual Studio kliknij prawym przyciskiem myszy projekt w Eksploratorze Rozwiązań, a następnie z menu kontekstowego wybierz polecenie Zarządzaj tajnymi danymi użytkownika. Ten gest dodaje element UserSecretsId, wypełniony GUID-em, do pliku projektu.

Jeśli „GenerateAssemblyInfo” ma wartość „false”

Jeśli generowanie atrybutów informacji o zestawie () jest wyłączone (GenerateAssemblyInfoustawione na false), ręcznie dodaj element UserSecretsIdAttribute w pliku AssemblyInfo.cs . Przykład:

[assembly: UserSecretsId("your_user_secrets_id")]

Po ręcznym dodaniu atrybutu UserSecretsId do pliku UserSecretsId wartość musi być zgodna z wartością w pliku projektu.

Ustaw tajne

Zdefiniuj tajemnicę aplikacji składającą się z klucza i jego wartości. Tajemnica jest skojarzona z wartością UserSecretsId projektu. Na przykład uruchom następujące polecenie z katalogu, w którym istnieje plik projektu:

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

W tym przykładzie dwukropek wskazuje, że Movies jest to literał obiektu z właściwością ServiceApiKey .

Można również używać Secret Manager w innych katalogach. --project Dołącz opcję, aby podać ścieżkę systemu plików, w której istnieje plik projektu. Przykład:

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

Spłaszczanie struktury JSON w programie Visual Studio

Polecenie programu Visual Studio Manage User Secrets otwiera plik secrets.json w edytorze tekstu. Zastąp zawartość pliku secrets.json parami klucz-wartość, które mają być przechowywane. Przykład:

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

Struktura JSON zostaje spłaszczona po wprowadzeniu modyfikacji za pomocą polecenia dotnet user-secrets remove lub dotnet user-secrets set. Na przykład uruchomienie dotnet user-secrets remove "Movies:ConnectionString" zwija Movies literał obiektu. Zmodyfikowany plik przypomina następujący kod JSON:

{
  "Movies:ServiceApiKey": "12345"
}

Ustawianie wielu sekretów

Partię tajnych można ustawić, przekazując kod JSON do polecenia set. W poniższym przykładzie zawartość pliku input.json jest przekazywana potokowo do polecenia set.

Windows

Uruchom następujące polecenie:

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

Linux/macOS

W terminalu uruchom następujące polecenie:

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

Dostęp do tajnego

Aby uzyskać dostęp do wpisu tajnego, wykonaj następujące kroki:

1. Zarejestruj źródło konfiguracji sekretów użytkownika.

2. Odczytaj klucz tajny za pośrednictwem interfejsu API konfiguracji.

Zarejestruj źródło konfiguracji tajnych danych użytkownika

Dostawca konfiguracji tajnych danych użytkownika rejestruje odpowiednie źródło konfiguracji w interfejsie API do konfiguracji platformy .NET.

Aplikacje internetowe ASP.NET Core utworzone za pomocą polecenia dotnet new lub programu Visual Studio generują następujący kod:

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

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

app.Run();

Metoda WebApplication.CreateBuilder inicjuje nowe wystąpienie WebApplicationBuilder klasy z wstępnie skonfigurowanymi wartościami domyślnymi. Zainicjowany WebApplicationBuilder (builder) zapewnia domyślną konfigurację i wywołuje metodę AddUserSecrets, gdy właściwość EnvironmentName ma wartość Development.

Odczytywanie tajnego hasła przez interfejs API konfiguracji.

Poniższe przykłady pokazują, jak odczytywać klucz Movies:ServiceApiKey:

plik Program.cs

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

var app = builder.Build();

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

app.Run();

Razor Model strony stron

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

Aby uzyskać więcej informacji, zobacz Konfiguracja na platformie ASP.NET Core.

Mapowanie sekretów na obiekt POCO

Mapowanie całego literału obiektu na obiekt POCO (prosta klasa .NET z właściwościami) jest przydatne w przypadku agregowania powiązanych właściwości.

Załóżmy, że plik secrets.json aplikacji zawiera następujące dwa wpisy tajne:

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

Aby zamapować wcześniej wspomniane tajne informacje na obiekt POCO, użyj funkcji wiązania grafu obiektów w interfejsie API konfiguracji .NET. Poniższy kod wiąże się z niestandardowym MovieSettings elementem POCO i uzyskuje wartość właściwości z ServiceApiKey.

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

Wartości Movies:ConnectionString i Movies:ServiceApiKey są mapowane na odpowiednie właściwości w MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Używanie zamiany ciągu z wpisami tajnymi

Przechowywanie haseł w postaci zwykłego tekstu jest niezabezpieczone. Nigdy nie przechowuj wpisów tajnych w pliku konfiguracji, takim jak appsettings.json, co może zostać zaewidencjonowane w repozytorium kodu źródłowego.

Na przykład parametry połączenia z bazą danych przechowywane w pliku appsettings.json nie powinny zawierać hasła. Zamiast tego należy przechowywać hasło jako sekret i dołączać je do parametrów ciągu połączenia w czasie wykonywania. Przykład:

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

Zastąp symbol zastępczy <secret value> w przykładzie wartością hasła. Ustaw wartość wpisu tajnego SqlConnectionStringBuilder we właściwości obiektuPassword, aby uwzględnić ją jako wartość hasła w parametry połączenia:

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

Lista tajemnic

Załóżmy, że plik secrets.json aplikacji zawiera następujące dwa wpisy tajne:

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

Uruchom następujące polecenie z katalogu, w którym istnieje plik projektu:

dotnet user-secrets list

Wyświetlane są następujące dane wyjściowe:

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

W tym przykładzie dwukropek (:) w nazwach kluczy określa hierarchię obiektów w pliku secrets.json .

Usuń pojedynczą tajemnicę

Załóżmy, że plik secrets.json aplikacji zawiera następujące dwa wpisy tajne:

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

Uruchom następujące polecenie z katalogu, w którym istnieje plik projektu:

dotnet user-secrets remove "Movies:ConnectionString"

Plik secrets.json aplikacji jest modyfikowany w celu usunięcia pary klucz-wartość skojarzonej z kluczem Movies:ConnectionString :

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

Polecenie dotnet user-secrets list wyświetla następujący komunikat:

Movies:ServiceApiKey = 12345

Usuń wszystkie wpisy tajne

Załóżmy, że plik secrets.json aplikacji zawiera następujące dwa wpisy tajne:

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

Uruchom następujące polecenie z katalogu, w którym istnieje plik projektu:

dotnet user-secrets clear

Wszystkie wpisy tajne użytkownika dla aplikacji są usuwane z pliku secrets.json :

{}

Uruchomienie polecenia powoduje wyświetlenie następującego komunikatu dotnet user-secrets list :

No secrets configured for this application.

Zarządzanie wpisami tajnymi użytkownika za pomocą programu Visual Studio

Aby zarządzać wpisami tajnymi użytkownika w Visual Studio, kliknij prawym przyciskiem myszy projekt w Eksplorator rozwiązań i wybierz pozycję Zarządzaj wpisami tajnymi użytkownika:

Migrowanie wpisów tajnych użytkownika z programu ASP.NET Framework do ASP.NET Core

Możesz przeprowadzić migrację przechowywanych wpisów tajnych użytkownika z programu ASP.NET Framework do ASP.NET Core. Aby uzyskać więcej informacji, zobacz problem GitHub dotnet/aspnetcore.docs nr 27611 - dokumentacja funkcji Tajemnice użytkownika nie wspomina o niezgodności z plikiem AssemblyInfo.cs.

Praca z wpisami tajnymi użytkownika w aplikacjach nieinternetowych

Projekty przeznaczone Microsoft.NET.Sdk.Web automatycznie obejmują obsługę tajemnic użytkownika. W przypadku projektów przeznaczonych dla Microsoft.NET.Sdk, takich jak aplikacje konsolowe, zainstaluj pakiety NuGet rozszerzenia konfiguracji i tajnych danych użytkownika.

PowerShell

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

.NET

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

Po zainstalowaniu pakietów zainicjuj projekt i ustaw wpisy tajne tak samo jak w przypadku aplikacji internetowej. Poniższy przykład przedstawia aplikację konsolową, która pobiera wartość klucza tajnego ustawionego przy użyciu klucza 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"]);
    }
}

Treści powiązane

• Zgłoszenie GitHub dotnet/aspnetcore.docs nr 30378 (Debugowanie w usłudze Internet Information Services (IIS))
• Zgłoszenie GitHub dotnet/aspnetcore.docs nr 16328 (Uruchamianie w usłudze IIS)
• Konfiguracja w programie ASP.NET Core
• dostawcy konfiguracji usługi Azure Key Vault