Bezpieczne przechowywanie wpisów tajnych aplikacji podczas programowania w programie ASP.NET Core

Autorzy: Rick Anderson i Kirk Larkin

Wyświetl lub pobierz przykładowy kod (jak pobrać)

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. Wpisy tajne nie powinny być wdrażane za pomocą aplikacji. Dostęp do wpisów tajnych produkcyjnych należy uzyskać za pośrednictwem kontrolowanych środków, takich jak usługa Azure Key Vault. Wpisy tajne testowania i produkcji platformy Azure można przechowywać i chronić za pomocą dostawcy konfiguracji usługi Azure Key Vault.

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

Aby użyć wpisów tajnych użytkownika w aplikacji konsolowej platformy .NET, zobacz ten problem z usługą GitHub.

Zmienne środowiskowe

Zmienne środowiskowe służą do unikania przechowywania wpisów tajnych 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żmy aplikację internetową ASP.NET Core, w której włączono zabezpieczenia poszczególnych kont użytkowników. Domyślna parametry połączenia bazy danych jest zawarta appsettings.json w pliku projektu z kluczem DefaultConnection. Domyślnym parametry połączenia jest localDB, który działa w trybie użytkownika i nie wymaga hasła. Podczas wdrażania DefaultConnection aplikacji wartość klucza może zostać zastąpiona wartością zmiennej środowiskowej. Zmienna środowiskowa może przechowywać kompletne parametry połączenia z poufnymi poświadczeniami.

Ostrzeżenie

Zmienne środowiskowe są zwykle przechowywane w postaci zwykłego, niezaszyfrowanego tekstu. W przypadku naruszenia zabezpieczeń maszyny lub procesu zmienne środowiskowe mogą być dostępne dla niezaufanych stron. Mogą być wymagane dodatkowe środki zapobiegające ujawnieniu wpisów tajnych użytkownika.

Separator : nie współdziała z kluczami hierarchicznymi zmiennych środowiskowych na wszystkich platformach. Na przykład separator nie jest obsługiwany przez powłokę : Bash. Podwójne podkreślenie, __, to:

• Jest obsługiwany przez wszystkie platformy.
• Automatycznie zamieniono dwukropek na :.

Menedżer wpisów tajnych

Narzędzie Secret Manager przechowuje poufne dane podczas tworzenia aplikacji. W tym kontekście element poufnych danych jest wpisem tajnym aplikacji. Wpisy tajne aplikacji są przechowywane w oddzielnej lokalizacji od drzewa projektu. Wpisy tajne aplikacji są skojarzone z określonym projektem lub współużytkowane w kilku projektach. Wpisy tajne aplikacji nie są zaewidencjonowane w kontroli źródła.

Ostrzeżenie

Narzędzie Secret Manager nie szyfruje przechowywanych wpisów tajnych i nie powinno być traktowane jako zaufany magazyn. Jest to tylko do celów programistycznych. Klucze i wartości są przechowywane w pliku konfiguracji JSON w katalogu profilu użytkownika.

Jak działa narzędzie Secret Manager

Narzędzie Secret Manager ukrywa szczegóły implementacji, takie jak miejsce i sposób przechowywania 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 poprzednich ścieżkach plików zastąp UserSecretsId wartość <user_secrets_id> określoną w pliku projektu.

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

Włączanie magazynu wpisów tajnych

Narzędzie Secret Manager działa na ustawieniach konfiguracji specyficznych dla projektu przechowywanych w profilu użytkownika.

Korzystanie z interfejsu wiersza polecenia

Narzędzie Secret Manager zawiera init polecenie . Aby użyć wpisów tajnych użytkownika, uruchom następujące polecenie w katalogu projektu:

dotnet user-secrets init

Poprzednie polecenie dodaje UserSecretsId element w PropertyGroup pliku projektu. Domyślnie tekst UserSecretsId wewnętrzny elementu jest identyfikatorem GUID. Tekst wewnętrzny jest dowolny, ale jest unikatowy dla projektu.

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

Korzystanie z programu Visual Studio

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

Jeśli GenerateAssemblyInfo jest false

Jeśli generowanie atrybutów informacji o zestawie jest wyłączone, ręcznie dodaj element UserSecretsIdAttribute w AssemblyInfo.cspliku . Na przykład:

[assembly: UserSecretsId("your_user_secrets_id")]

Podczas ręcznego dodawania atrybutu UserSecretsId do UserSecretsId AssemblyInfo.cselementu wartość musi być zgodna z wartością w pliku projektu.

Ustawianie wpisu tajnego

Zdefiniuj wpis tajny aplikacji składający się z klucza i jego wartości. Wpis tajny jest skojarzony 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 poprzednim przykładzie dwukropek oznacza, że Movies jest to literał obiektu z właściwością ServiceApiKey .

Narzędzie Secret Manager może być również używane z innych katalogów. --project Użyj opcji , aby podać ścieżkę systemu plików, w której istnieje plik projektu. Na przykład:

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

Spłaszczanie struktury JSON w programie Visual Studio

Gest Zarządzanie wpisami tajnymi użytkownika programu Visual Studio otwiera secrets.json plik w edytorze tekstów. Zastąp zawartość secrets.json par klucz-wartość, które mają być przechowywane. Na przykład:

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

Struktura JSON jest spłaszczana po modyfikacjach za pośrednictwem metody 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 wpisów tajnych

Partię wpisów tajnych można ustawić, potokując kod JSON do set polecenia . W poniższym przykładzie input.json zawartość pliku jest potokowana do set polecenia .

Windows

Otwórz powłokę poleceń i wykonaj następujące polecenie:

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

Linux/macOS

Otwórz powłokę poleceń i wykonaj następujące polecenie:

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

Uzyskiwanie dostępu do wpisu tajnego

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

1. Rejestrowanie źródła konfiguracji wpisów tajnych użytkownika
2. Odczytywanie wpisu tajnego za pośrednictwem interfejsu API konfiguracji

Rejestrowanie źródła konfiguracji wpisów tajnych użytkownika

Dostawca konfiguracji wpisów tajnych użytkownika rejestruje odpowiednie źródło konfiguracji za pomocą interfejsu API konfiguracji platformy .NET.

Aplikacje internetowe ASP.NET Core utworzone za pomocą platformy 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();

WebApplication.CreateBuilder inicjuje nowe wystąpienie klasy WebApplicationBuilder ze wstępnie skonfigurowanymi wartościami domyślnymi. Zainicjowany WebApplicationBuilder (builder) udostępnia konfigurację domyślną i wywołuje metodę AddUserSecrets , gdy parametr EnvironmentName to Development:

Odczytywanie wpisu tajnego za pośrednictwem interfejsu API konfiguracji

Rozważmy następujące przykłady odczytywania Movies:ServiceApiKey klucza:

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 wpisów tajnych na element 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 aplikacji secrets.json 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ć powyższe wpisy tajne na element POCO, użyj funkcji powiązania grafu obiektów interfejsu API konfiguracji platformy .NET. Poniższy kod wiąże się z niestandardowym MovieSettings elementem POCO i uzyskuje ServiceApiKey dostęp do wartości właściwości:

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

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

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

    public string ServiceApiKey { get; set; }
}

Zastępowanie ciągu 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 baza danych parametry połączenia przechowywana w programie appsettings.json nie powinna zawierać hasła. Zamiast tego należy przechowywać hasło jako wpis tajny i dołączać hasło do parametry połączenia w czasie wykonywania. Na przykład:

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

Zastąp <secret value> symbol zastępczy w poprzednim 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();

Wyświetlanie listy wpisów tajnych

Załóżmy, że plik aplikacji secrets.json 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 poprzednim przykładzie dwukropek w nazwach kluczy określa hierarchię obiektów w programie secrets.json.

Usuwanie pojedynczego wpisu tajnego

Załóżmy, że plik aplikacji secrets.json 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 aplikacji secrets.json został zmodyfikowany w celu usunięcia pary klucz-wartość skojarzonej z kluczem Movies:ConnectionString :

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

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

Movies:ServiceApiKey = 12345

Usuń wszystkie wpisy tajne

Załóżmy, że plik aplikacji secrets.json 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 zostały usunięte z secrets.json pliku:

{}

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

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 programie Visual Studio, kliknij prawym przyciskiem myszy projekt w Eksploratorze rozwiązań i wybierz polecenie Zarządzaj wpisami tajnymi użytkownika:

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

Zobacz ten problem z usługą GitHub.

Wpisy tajne użytkownika w aplikacjach innych niż internetowe

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

Za pomocą programu PowerShell:

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

Korzystanie z interfejsu wiersza polecenia platformy .NET:

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

Po zainstalowaniu pakietów zainicjuj projekt i ustaw wpisy tajne w taki sam sposób jak w przypadku aplikacji internetowej. W poniższym przykładzie pokazano aplikację konsolową, która pobiera wartość wpisu tajnego ustawionego za pomocą 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"]);
    }
}

Dodatkowe zasoby

• Zobacz ten problem i ten problem, aby uzyskać informacje na temat uzyskiwania dostępu do wpisów tajnych użytkownika z usług IIS.
• Konfiguracja w programie ASP.NET Core
• Dostawca konfiguracji usługi Azure Key Vault w usłudze ASP.NET Core