Sicheres Speichern von App-Geheimnissen bei der Entwicklung in ASP.NET Core
Hinweis
Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
Warnung
Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der Supportrichtlinie für .NET und .NET Core. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
Wichtig
Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.
Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.
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:
Dateisystempfad:
%APPDATA%\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.
Öffnen Sie eine Befehlsshell, und führen Sie den folgenden Befehl aus:
type .\input.json | dotnet user-secrets set
Zugreifen auf ein Geheimnis
Führen Sie die folgenden Schritte aus, um auf ein Geheimnis zuzugreifen:
- Registrieren der Konfigurationsquelle von Benutzergeheimnissen
- 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
Von Rick Anderson, Kirk Larkin, Daniel Roth, und Scott Addie
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.
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:
Dateisystempfad:
%APPDATA%\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.
Der Geheimnis-Manager enthält einen init
-Befehl in .NET Core SDK 3.0.100 oder höher. 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>
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.
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.
Öffnen Sie eine Befehlsshell, und führen Sie den folgenden Befehl aus:
type .\input.json | dotnet user-secrets set
Zugreifen auf ein Geheimnis
Führen Sie die folgenden Schritte aus, um auf ein Geheimnis zuzugreifen:
- Registrieren der Konfigurationsquelle von Benutzergeheimnissen
- 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.
Die Konfigurationsquelle für die Benutzergeheimnisse wird im Entwicklungsmodus automatisch hinzugefügt, wenn das Projekt CreateDefaultBuilder aufruft. CreateDefaultBuilder
ruft AddUserSecrets auf, wenn der EnvironmentName entsprechend Development lautet:
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
Wenn CreateDefaultBuilder
nicht aufgerufen wird, fügen Sie die Konfigurationsquelle für die Benutzergeheimnisse explizit hinzu, indem Sie AddUserSecrets in ConfigureAppConfiguration aufrufen. Rufen Sie AddUserSecrets
nur auf, wenn die App in der Entwicklungsumgebung ausgeführt wird, wie im folgenden Beispiel gezeigt:
public class Program
{
public static void Main(string[] args)
{
var host = new HostBuilder()
.ConfigureAppConfiguration((hostContext, builder) =>
{
// Add other providers for JSON, etc.
if (hostContext.HostingEnvironment.IsDevelopment())
{
builder.AddUserSecrets<Program>();
}
})
.Build();
host.Run();
}
}
Lesen des Geheimnisses über die Konfigurations-API
Wenn die Konfigurationsquelle für die Benutzergeheimnisse registriert ist, kann die .NET-Konfigurations-API die Geheimnisse lesen. Die Konstruktoreinschleusung kann verwendet werden, um Zugriff auf die .NET-Konfigurations-API zu erhalten. Betrachten Sie die folgenden Beispiele zum Lesen des Movies:ServiceApiKey
-Schlüssels:
Startklasse:
public class Startup
{
private string _moviesApiKey = null;
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
_moviesApiKey = Configuration["Movies:ServiceApiKey"];
}
public void Configure(IApplicationBuilder app)
{
app.Run(async (context) =>
{
var result = string.IsNullOrEmpty(_moviesApiKey) ? "Null" : "Not Null";
await context.Response.WriteAsync($"Secret is {result}");
});
}
}
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 Zugriffskonfiguration beim Start und Zugriffskonfiguration in Razor Pages.
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:
public class Startup
{
private string _connection = null;
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
var builder = new SqlConnectionStringBuilder(
Configuration.GetConnectionString("Movies"));
builder.Password = Configuration["DbPassword"];
_connection = builder.ConnectionString;
// code omitted for brevity
}
public void Configure(IApplicationBuilder app)
{
app.Run(async (context) =>
{
await context.Response.WriteAsync($"DB Connection: {_connection}");
});
}
}
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 MoviesConnectionString
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