Säker lagring av apphemligheter under utveckling i ASP.NET Core

Av Rick Anderson och Kirk Larkin

Visa eller ladda ned exempelkod (hur du laddar ned)

Den här artikeln beskriver hur du hanterar känsliga data för en ASP.NET Core-app på en utvecklingsdator. Lagra aldrig lösenord eller andra känsliga data i källkods- eller konfigurationsfiler. Produktionshemligheter ska inte användas för utveckling eller testning. Hemligheter ska inte distribueras med appen. Produktionshemligheter bör nås via ett kontrollerat sätt som Azure Key Vault. Azure-test- och produktionshemligheter kan lagras och skyddas med Azure Key Vault-konfigurationsprovidern.

Mer information om autentisering för distribuerade test- och produktionsappar finns i Säkra autentiseringsflöden.

Information om hur du använder användarhemligheter i en .NET-konsolapp finns i det här GitHub-problemet.

Miljövariabler

Miljövariabler används för att undvika lagring av apphemligheter i kod eller i lokala konfigurationsfiler. Miljövariabler åsidosätter konfigurationsvärden för alla tidigare angivna konfigurationskällor.

Överväg en ASP.NET Core-webbapp där säkerhet för enskilda konton är aktiverat. En standardsträng för databasanslutning ingår i projektets appsettings.json fil med nyckeln DefaultConnection. Standardanslutningssträngen är för LocalDB, som körs i användarläge och inte kräver något lösenord. Under apputvecklingen DefaultConnection kan nyckelvärdet åsidosättas med en miljövariabels värde. Miljövariabeln kan lagra den fullständiga anslutningssträngen med känsliga autentiseringsuppgifter.

Varning

Miljövariabler lagras vanligtvis i oformaterad, okrypterad text. Om datorn eller processen komprometteras kan miljövariabler nås av ej betrodda parter. Ytterligare åtgärder för att förhindra avslöjande av användarhemligheter kan krävas.

Den : avgränsaren fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Till exempel stöds inte :-avgränsaren av Bash. Det dubbla understrecket, __, är:

• Stöds av alla plattformar.
• Ersätts automatiskt av ett kolon, :.

Hemlighetsansvarig

Secret Manager-verktyget lagrar känsliga data under programutvecklingen. I det här sammanhanget är en del av känsliga data en apphemlighet. Apphemligheter lagras på en separat plats från projektträdet. Apphemligheterna är associerade med ett specifikt projekt eller delas mellan flera projekt. Apphemligheterna är inte incheckade i källkontrollen.

Varning

Secret Manager-verktyget krypterar inte de lagrade hemligheterna och bör inte behandlas som ett betrott arkiv. Det är endast i utvecklingssyfte. Nycklarna och värdena lagras i en JSON-konfigurationsfil i användarprofilkatalogen.

Så här fungerar Secret Manager-verktyget

Secret Manager-verktyget döljer implementeringsinformation, till exempel var och hur värdena lagras. Du kan använda verktyget utan att känna till den här implementeringsinformationen. Värdena lagras i en JSON-fil i den lokala datorns användarprofilmapp:

Windows

Filsystemets sökväg

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

Linux/macOS

Filsystemets sökväg

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

I föregående filsökvägar ersätter du <user_secrets_id> med det UserSecretsId värde som anges i projektfilen.

Skriv inte kod som är beroende av platsen eller formatet för data som sparats med Secret Manager-verktyget. Den här implementeringsinformationen kan ändras. Till exempel krypteras inte de hemliga värdena.

Aktivera hemlig lagring

Secret Manager-verktyget fungerar med projektspecifika konfigurationsinställningar som lagras i din användarprofil.

Använda CLI

Secret Manager-verktyget innehåller ett init kommando. Om du vill använda användarhemligheter kör du följande kommando i projektkatalogen:

dotnet user-secrets init

Föregående kommando lägger till ett UserSecretsId element i en PropertyGroup av projektfilen. Som standard är den inre texten av UserSecretsId en GUID. Den inre texten är godtycklig, men är unik för projektet.

Använda Visual Studio

Högerklicka på projektet i Solution Explorer i Visual Studio och välj Hantera användarhemligheter på snabbmenyn. Den här gesten lägger till ett UserSecretsId element, fyllt med ett GUID, i projektfilen.

Om GenerateAssemblyInfo är false

Om genereringen av sammansättningsinformationsattribut är inaktiverad lägger du manuellt till UserSecretsIdAttribute i AssemblyInfo.cs. Till exempel:

[assembly: UserSecretsId("your_user_secrets_id")]

När du lägger till UserSecretsId attributet manuellt i AssemblyInfo.csUserSecretsId måste värdet matcha värdet i projektfilen.

Ange en hemlighet

Definiera en apphemlighet som består av en nyckel och dess värde. Hemligheten är associerad med projektets UserSecretsId värde. Kör till exempel följande kommando från katalogen där projektfilen finns:

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

I föregående exempel anger kolonet att Movies är en objekt litera med en ServiceApiKey egenskap.

Secret Manager-verktyget kan också användas från andra kataloger. Använd alternativet --project för att ange den filsystemsökväg där projektfilen finns. Till exempel:

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

Utplattad JSON-struktur i Visual Studio

Gesten Hantera användarhemligheter i Visual Studio öppnar en secrets.json fil i textredigeraren. Ersätt innehållet i secrets.json med de nyckel/värde-par som ska lagras. Till exempel:

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

JSON-strukturen plattas ut efter ändringar via dotnet user-secrets remove eller dotnet user-secrets set. Om du till exempel kör dotnet user-secrets remove "Movies:ConnectionString" komprimeras objektliteralen Movies . Den ändrade filen liknar följande JSON:

{
  "Movies:ServiceApiKey": "12345"
}

Ange flera hemligheter

Du kan ange en batch med hemligheter genom att skicka JSON till set kommandot . I följande exempel input.json skickas filens innehåll till set kommandot .

Windows

Öppna ett kommandogränssnitt och kör följande kommando:

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

Linux/macOS

Öppna ett kommandogränssnitt och kör följande kommando:

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

Få åtkomst till en hemlighet

Utför följande steg för att komma åt en hemlighet:

1. Registrera konfigurationskällan för användarhemligheter
2. Läs hemligheten via konfigurations-API:et

Registrera konfigurationskällan för användarhemligheter

Konfigurationsprovidern för användarhemligheter registrerar den lämpliga konfigurationskällan med .NET-konfigurations-API:et.

ASP.NET Core-webbappar som skapats med dotnet new eller Visual Studio genererar följande kod:

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

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

app.Run();

WebApplication.CreateBuilder initierar en ny instans av klassen WebApplicationBuilder med förkonfigurerade standardvärden. Den initierade WebApplicationBuilder (builder) tillhandahåller standardkonfiguration och anropar AddUserSecrets när EnvironmentName är Development:

Läs hemligheten via konfigurations-API:et

Tänk dig följande exempel på hur du Movies:ServiceApiKey läser nyckeln:

Program.cs-filen:

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

var app = builder.Build();

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

app.Run();

Razor Sidmodell för sidor:

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

Mer information finns i Konfiguration i ASP.NET Core.

Mappa hemlig information till en POCO

Att mappa en hel objektliteral till en POCO (en enkel .NET-klass med egenskaper) är användbart för att aggregera relaterade egenskaper.

Anta att appens secrets.json fil innehåller följande två hemligheter:

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

Om du vill mappa föregående hemligheter till en POCO använder du .NET Configuration API:s objektdiagrambindningsfunktion . Följande kod binder till en anpassad MovieSettings POCO och får åtkomst till egenskapsvärdet ServiceApiKey :

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

Hemligheterna Movies:ConnectionString och Movies:ServiceApiKey mappas till respektive egenskaper i MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Strängersättning med hemligheter

Det är osäkert att lagra lösenord i oformaterad text. Lagra aldrig hemligheter i en konfigurationsfil, till exempel appsettings.json, som kan checkas in på en källkodslagringsplats.

En databasanslutningssträng som lagras i appsettings.json bör till exempel inte innehålla något lösenord. Lagra istället lösenordet som en hemlighet och inkludera lösenordet i anslutningssträngen vid körning. Till exempel:

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

<secret value> Ersätt platshållaren i föregående exempel med lösenordsvärdet. Ange hemlighetens värde på ett SqlConnectionStringBuilder objekts egenskap så att det inkluderas Password som lösenordsvärde i anslutningssträngen:

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

Visa en lista över hemligheter

Anta att appens secrets.json fil innehåller följande två hemligheter:

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

Kör följande kommando från katalogen där projektfilen finns:

dotnet user-secrets list

Följande utdata visas:

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

I föregående exempel anger ett kolon i nyckelnamn objekthierarkin i secrets.json.

Ta bort en enda hemlighet

Anta att appens secrets.json fil innehåller följande två hemligheter:

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

Kör följande kommando från katalogen där projektfilen finns:

dotnet user-secrets remove "Movies:ConnectionString"

secrets.json-filen i appen ändrades för att ta bort nyckel/värde-paret som är associerat med Movies:ConnectionString-nyckeln:

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

dotnet user-secrets list visar följande meddelande:

Movies:ServiceApiKey = 12345

Ta bort alla hemligheter

Anta att appens secrets.json fil innehåller följande två hemligheter:

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

Kör följande kommando från katalogen där projektfilen finns:

dotnet user-secrets clear

Alla användarhemligheter för appen har tagits bort från secrets.json filen:

{}

När du kör dotnet user-secrets list visas följande meddelande:

No secrets configured for this application.

Hantera användarhemligheter med Visual Studio

Om du vill hantera användarhemligheter i Visual Studio högerklickar du på projektet i Solution Explorer och väljer Hantera användarhemligheter:

Migrera användarhemligheter från ASP.NET Framework till ASP.NET Core

Se det här GitHub-problemet.

Användarhemligheter i icke-webbprogram

Projekt som har som mål Microsoft.NET.Sdk.Web inkluderar automatiskt stöd för användarhemligheter. För projekt som riktar sig till Microsoft.NET.Sdk, till exempel konsolprogram, installerar du konfigurationstillägget och NuGet-paketen för användarhemligheter explicit.

Med PowerShell:

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

Använda .NET CLI:

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

När paketen har installerats initierar du projektet och anger hemligheter på samma sätt som för en webbapp. I följande exempel visas ett konsolprogram som hämtar värdet för en hemlighet som har angetts med nyckeln "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"]);
    }
}

Ytterligare resurser

• Se det här problemet och det här problemet för information om åtkomst till användarhemligheter från IIS.
• Konfiguration i ASP.NET Core
• Azure Key Vault-konfigurationsprovider i ASP.NET Core