Sicheres Speichern von App-Geheimnissen bei der Entwicklung in ASP.NET Core

Von Rick Anderson und Kirk Larkin

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

In diesem Dokument wird erläutert, wie Sie vertrauliche Daten für eine ASP.NET Core-App auf einem Entwicklungscomputer verwalten können. Speichern Sie niemals Kennwörter oder andere vertrauliche Daten im Quellcode. Produktionsgeheimnisse sollten nicht für die Entwicklung oder für Tests verwendet werden. Geheimnisse sollten nicht mit der App bereitgestellt werden. Stattdessen sollte der Zugriff auf Produktionsgeheimnisse über ein kontrolliertes Mittel wie Umgebungsvariablen oder Azure Key Vault erfolgen. Sie können Azure-Test- und -Produktionsgeheimnisse mit dem Konfigurationsanbieter Azure Key Vault speichern und schützen.

Informationen zum Verwenden von Benutzergeheimnissen in einer .NET-Konsolen-App finden Sie in diesem GitHub-Artikel.

Umgebungsvariablen

Umgebungsvariablen werden verwendet, um die Speicherung von App-Geheimnissen im Code oder in lokalen Konfigurationsdateien zu vermeiden. Umgebungsvariablen setzen die Konfigurationswerte für alle zuvor angegebenen Konfigurationsquellen außer Kraft.

Betrachten Sie eine ASP.NET Core Web-App, in der die Sicherheit für einzelne Benutzerkonten aktiviert ist. Eine standardmäßige Verbindungszeichenfolge für die Datenbank ist in der Datei appsettings.json des Projekts mit dem Schlüssel DefaultConnection enthalten. Die standardmäßige Verbindungszeichenfolge ist für LocalDB vorgesehen, die im Benutzermodus ausgeführt wird und kein Kennwort erfordert. Bei der Bereitstellung einer App kann der Wert des Schlüssels DefaultConnection durch den Wert einer Umgebungsvariablen außer Kraft gesetzt werden. Die Umgebungsvariable kann die vollständige Verbindungszeichenfolge mit vertraulichen Anmeldeinformationen speichern.

Warnung

Umgebungsvariablen werden im Allgemeinen in unverschlüsseltem Nur-Text gespeichert. Wenn der Computer oder Prozess kompromittiert ist, können nicht vertrauenswürdige Parteien auf die Umgebungsvariablen zugreifen. Es können zusätzliche Maßnahmen erforderlich sein, um die Offenlegung von Benutzergeheimnissen zu verhindern.

Das Trennzeichen : funktioniert nicht auf allen Plattformen mit den hierarchischen Schlüsseln von Umgebungsvariablen. Der doppelte Unterstrich __:

• wird auf allen Plattformen unterstützt. Das Trennzeichen : wird beispielsweise nicht von Bash unterstützt, __ hingegen schon.
• automatisch durch : ersetzt.

Geheimnis-Manager

Das Tool „Secret Manager“ speichert vertrauliche Daten während der Anwendungsentwicklung. In diesem Zusammenhang stellt ein vertrauliches Datenfragment ein App-Geheimnis dar. App-Geheimnisse werden an einem von der Projektstruktur getrennten Ort gespeichert. Die App-Geheimnisse sind einem bestimmten Projekt zugeordnet oder werden projektübergreifend freigegeben. Die Geheimnisse der App werden nicht in die Quellcodeverwaltung eingecheckt.

Warnung

Der Geheimnis-Manager verschlüsselt die gespeicherten Geheimnisse nicht und sollte nicht als vertrauenswürdiger Speicher behandelt werden. Er dient nur zu Entwicklungszwecken. Die Schlüssel und Werte werden in einer JSON-Konfigurationsdatei im Profilverzeichnis des Benutzers gespeichert.

Funktionsweise des Geheimnis-Managers

Das Tool „Geheimnis-Manager“ blendet Implementierungsdetails aus, z. B. wo und wie die Werte gespeichert werden. Sie können das Tool verwenden, ohne diese Implementierungsdetails zu kennen. Die Werte werden in einer JSON-Datei im Benutzerprofilordner des lokalen Computers gespeichert:

Windows

Dateisystempfad:

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

Linux/macOS

Dateisystempfad:

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

Ersetzen Sie in den vorangehenden Dateipfaden <user_secrets_id> durch den in der Projektdatei angegebenen UserSecretsId-Wert.

Schreiben Sie keinen Code, der vom Speicherort oder Format der mit dem Geheimnis-Manager gespeicherten Daten abhängt. Diese Implementierungsdetails können sich ändern. Beispielsweise sind die geheimen Werte nicht verschlüsselt, könnten aber in Zukunft verschlüsselt werden.

Aktivieren der Geheimnisspeicherung

Der Geheimnis-Manager arbeitet mit projektspezifischen Konfigurationseinstellungen, die in Ihrem Benutzerprofil gespeichert sind.

Verwenden der Befehlszeilenschnittstelle

Der Geheimnis-Manager enthält einen init-Befehl. Um Benutzergeheimnisse zu verwenden, führen Sie den folgenden Befehl im Projektverzeichnis aus:

dotnet user-secrets init

Der vorangehende Befehl fügt ein UserSecretsId-Element innerhalb einer PropertyGroup der Projektdatei hinzu. Standardmäßig ist der innere Text von UserSecretsId eine GUID. Der innere Text ist willkürlich, aber für das Projekt eindeutig.

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

Verwenden von Visual Studio

Klicken Sie in Visual Studio mit der rechten Maustaste auf das Projekt im Projektmappen-Explorer, und wählen Sie Benutzergeheimnisse verwalten aus dem Kontextmenü aus. Diese Geste fügt der Projektdatei ein UserSecretsId-Element hinzu, das mit einer GUID gefüllt ist.

Wenn GenerateAssemblyInfo gleich false

Wenn die Generierung von Assemblyinfoattributen deaktiviert ist, fügen Sie das UserSecretsIdAttribute manuell in AssemblyInfo.cs hinzu. Beispiel:

[assembly: UserSecretsId("your_user_secrets_id")]

Wenn Sie das UserSecretsId-Attribut manuell zu AssemblyInfo.cs hinzufügen, muss der UserSecretsId-Wert mit dem Wert in der Projektdatei übereinstimmen.

Festlegen eines Geheimnisses

Definieren Sie ein App-Geheimnis, das aus einem Schlüssel und seinem Wert besteht. Das Geheimnis ist dem UserSecretsId-Wert des Projekts zugeordnet. Führen Sie z. B. den folgenden Befehl von dem Verzeichnis aus, in dem sich die Projektdatei befindet:

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

Im vorangehenden Beispiel bedeutet der Doppelpunkt, dass Movies ein Objektliteral mit einer ServiceApiKey-Eigenschaft ist.

Der Geheimnis-Manager kann auch von anderen Verzeichnissen aus verwendet werden. Verwenden Sie die Option --project, um den Dateisystempfad anzugeben, unter dem die Projektdatei vorhanden ist. Beispiel:

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

JSON-Strukturvereinfachung in Visual Studio

Die Geste Benutzergeheimnisse verwalten von Visual Studio öffnet eine secrets.json-Datei im Text-Editor. Ersetzen Sie den Inhalt von secrets.json durch die zu speichernden Schlüssel-Wert-Paare. Beispiel:

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

Die JSON-Struktur wird nach Änderungen über dotnet user-secrets remove oder dotnet user-secrets set vereinfacht. Wenn Sie z. B. dotnet user-secrets remove "Movies:ConnectionString" ausführen, wird das Objektliteral Movies reduziert. Die geänderte Datei ähnelt dem folgenden JSON-Code:

{
  "Movies:ServiceApiKey": "12345"
}

Festlegen mehrerer Geheimnisse

Sie können einen Batch von Geheimnissen festlegen, indem Sie JSON per Pipeline an den Befehl set weiterreichen. Im folgenden Beispiel wird der Inhalt der Datei input.json an den Befehl set weitergereicht.

Windows

Öffnen Sie eine Befehlsshell, und führen Sie den folgenden Befehl aus:

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

Linux/macOS

Öffnen Sie eine Befehlsshell, und führen Sie den folgenden Befehl aus:

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

Zugreifen auf ein Geheimnis

Führen Sie die folgenden Schritte aus, um auf ein Geheimnis zuzugreifen:

1. Registrieren der Konfigurationsquelle von Benutzergeheimnissen
2. Lesen des Geheimnisses über die Konfigurations-API

Registrieren der Konfigurationsquelle von Benutzergeheimnissen

Der Konfigurationsanbieter von Benutzergeheimnissen registriert die entsprechende Konfigurationsquelle mit der .NET-Konfigurations-API.

ASP.NET Core-Web-Apps, die mit dotnet new oder Visual Studio erstellt wurden, generieren den folgenden Code:

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

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

app.Run();

WebApplication.CreateBuilder Initialisiert eine neue Instanz der WebApplicationBuilder-Klasse mit vorkonfigurierten Standardwerten. Der initialisierte WebApplicationBuilder (builder) bietet eine Standardkonfiguration und ruft AddUserSecrets auf, wenn der EnvironmentName entsprechend Development lautet:

Lesen des Geheimnisses über die Konfigurations-API

Betrachten Sie die folgenden Beispiele zum Lesen des Movies:ServiceApiKey-Schlüssels:

Datei „Program.cs“:

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

var app = builder.Build();

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

app.Run();

Razor Pages-Seitenmodell:

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

Weitere Informationen finden Sie unter Konfiguration in ASP.NET Core.

Zuordnen von Geheimnissen zu einem POCO

Das Zuordnen eines ganzen Objektliterals zu einem POCO (eine einfache .NET-Klasse mit Eigenschaften) ist nützlich, um verwandte Eigenschaften zu aggregieren.

Angenommen, die Datei secrets.json der App enthält die folgenden zwei Geheimnisse:

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

Um die oben genannten Geheimnisse einem POCO zuzuordnen, verwenden Sie das Feature Objektgraphenbindung der .NET-Konfigurations-API. Der folgende Code bindet an einen benutzerdefinierten MovieSettings-POCO und greift auf den ServiceApiKey-Eigenschaftswert zu:

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

Die Geheimnisse Movies:ConnectionString und Movies:ServiceApiKey werden den entsprechenden Eigenschaften in MovieSettings zugeordnet:

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

    public string ServiceApiKey { get; set; }
}

Ersetzen von Zeichenfolgen durch Geheimnisse

Die Speicherung von Kennwörtern in Nur-Text ist keine sichere Methode. Eine in appsettings.json gespeicherte Verbindungszeichenfolge der Datenbank kann z. B. ein Kennwort für den angegebenen Benutzer enthalten:

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

Eine sicherere Methode besteht darin, das Kennwort als Geheimnis zu speichern. Beispiel:

dotnet user-secrets set "DbPassword" "pass123"

Entfernen Sie das Schlüssel-Wert-Paar Password aus der Verbindungszeichenfolge in appsettings.json. Beispiel:

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

Der Wert des Geheimnisses kann in der Eigenschaft Password eines SqlConnectionStringBuilder-Objekts festgelegt werden, um die Verbindungszeichenfolge zu vervollständigen:

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

Auflisten der Geheimnisse

Angenommen, die Datei secrets.json der App enthält die folgenden zwei Geheimnisse:

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

Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem sich die Projektdatei befindet:

dotnet user-secrets list

Die folgende Ausgabe wird angezeigt:

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

Im vorangegangenen Beispiel kennzeichnet ein Doppelpunkt in den Schlüsselnamen die Objekthierarchie innerhalb von secrets.json.

Entfernen eines einzelnen Geheimnisses

Angenommen, die Datei secrets.json der App enthält die folgenden zwei Geheimnisse:

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

Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem sich die Projektdatei befindet:

dotnet user-secrets remove "Movies:ConnectionString"

Die Datei secrets.json der App wurde geändert, um das Schlüssel-Wert-Paar zu entfernen, das dem Schlüssel Movies:ConnectionString zugeordnet ist:

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

dotnet user-secrets list zeigt die folgende Meldung an:

Movies:ServiceApiKey = 12345

Entfernen aller Geheimnisse

Angenommen, die Datei secrets.json der App enthält die folgenden zwei Geheimnisse:

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

Führen Sie den folgenden Befehl in dem Verzeichnis aus, in dem sich die Projektdatei befindet:

dotnet user-secrets clear

Alle Benutzergeheimnisse für die App wurden aus der Datei secrets.json gelöscht:

{}

Wenn Sie dotnet user-secrets list ausführen, wird die folgende Meldung angezeigt:

No secrets configured for this application.

Verwalten von Benutzergeheimnissen mit Visual Studio

Um Benutzergeheimnisse in Visual Studio zu verwalten, klicken Sie mit der rechten Maustaste auf das Projekt im Projektmappen-Explorer, und wählen Sie Benutzergeheimnisse verwalten aus:

Migrieren von Benutzergeheimnissen von ASP.NET Framework zu ASP.NET Core

Weitere Informationen finden Sie im entsprechenden GitHub-Issue.

Geheime Benutzerschlüssel in Nicht-Webanwendungen

Projekte, die auf Microsoft.NET.Sdk.Web ausgelegt sind, enthalten automatisch Unterstützung für Benutzergeheimnisse. Installieren Sie für Projekte wie Konsolenanwendungen, die auf Microsoft.NET.Sdk ausgelegt sind, explizit die Konfigurationserweiterung und NuGet-Pakete der Benutzergeheimnisse.

Über PowerShell:

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

Verwenden der .NET-CLI:

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

Nachdem die Pakete installiert wurden, initialisieren Sie das Projekt und legen Sie geheime Schlüssel auf die gleiche Weise wie für eine Web-App fest. Das folgende Beispiel zeigt eine Konsolenanwendung, die den Wert eines Geheimnisses abruft, das mit dem Schlüssel „AppSecret“ festgelegt wurde:

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Zusätzliche Ressourcen

• Informationen zum Zugriff auf Benutzergeheimnisse über IIS finden Sie in diesem Issue und diesem Issue.
• Konfiguration in ASP.NET Core
• Azure Key Vault-Konfigurationsanbieter in ASP.NET Core