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

Av Rick Anderson och Kirk Larkin

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.

Visa eller ladda ned exempelkoden (ladda ned)

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 GitHub dotnet/entityframework.docs issue #3939.

Arbeta med 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 standardanslutningssträng för databasen ingår i projektfilen appsettings.json under nyckeln DefaultConnection. Standardanslutningssträngen är för LocalDB, som körs i användarläge och inte kräver något lösenord. Under appdistributionen kan du åsidosätta DefaultConnection nyckelvärdet med värdet från en miljövariabel. Miljövariabeln kan lagra hela reťazec pripojenia med känsliga autentiseringsuppgifter.

Warning

Miljövariabler lagras ofta som okrypterad text. Om datorn eller processen komprometteras är miljövariabler tillgängliga för ej betrodda parter. Extra åtgärder för att förhindra avslöjande av användarhemligheter kan krävas.

Kolonavgränsaren (:) fungerar inte med hierarkiska nycklar för miljövariabler på alla plattformar. Bash stöder till exempel inte kolon (:) som avgränsare. Alla plattformar stöder syntaxen för dubbla understreck (__) och ersätter den automatiskt med ett kolon (:).

Använda secret manager-verktyget

Secret Manager är ett verktyg som 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.
• De är associerade med ett specifikt projekt eller delas mellan flera projekt.
• De är inte incheckade i versionshanteringen.

Warning

Secret Manager krypterar inte lagrade hemligheter 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.

Secret Manager 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 sökvägen till filsystemet ersätter du <user_secrets_id> delen 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. Den här implementeringsinformationen kan komma att ändras. Till exempel krypteras inte de hemliga värdena.

Aktivera hemlig lagring

Secret Manager arbetar med projektspecifika konfigurationsinställningar som lagras i din användarprofil.

Använda CLI

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

dotnet user-secrets init

Det här kommandot 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. I följande exempel visas ett GUID-värde på 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>

Använda Visual Studio

Högerklicka på projektet i Prieskumník riešení 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 (GenerateAssemblyInfo) är inaktiverad (inställd på false) lägger du manuellt till UserSecretsIdAttribute i filen AssemblyInfo.cs . Till exempel:

[assembly: UserSecretsId("your_user_secrets_id")]

När du lägger till UserSecretsId attributet manuellt i AssemblyInfo.cs-filenUserSecretsId 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 det här exemplet anger kolonet att det Movies är en objektliteral med en ServiceApiKey egenskap.

Du kan också använda Secret Manager från andra kataloger. Inkludera alternativet --project för att ange sökvägen till filsystemet 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 Visual Studio Manage User Secrets öppnar en secrets.json fil i textredigeraren. Ersätt innehållet i secrets.json-filen med nyckel/värde-paren 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 kommandot 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 skickas innehållet i input.json-filen till set kommandot .

Windows

Kör följande kommando:

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

Linux/macOS

Kör följande kommando i en terminal:

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 kommandot dotnet new eller Visual Studio generera följande kod:

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

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

app.Run();

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

Läs hemligheten via konfigurations-API:et

Följande exempel visar hur du Movies:ServiceApiKey läser nyckeln:

Program.cs fil

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

var app = builder.Build();

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

app.Run();

Razor Sidmodell för Pages

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 programmet secrets.json filen 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; }
}

Använd strängbyte 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.

Till exempel bör en anslutningssträng för databasen som lagras i filen appsettings.json inte innehålla ett 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 exemplet 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 programmet secrets.json filen 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 exemplet anger ett kolon (:) i nyckelnamn objekthierarkin i filensecrets.json .

Ta bort en enda hemlighet

Anta att programmet secrets.json filen 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"

Programmets secrets.json-fil ändras för att ta bort det nyckel/värde-par som är kopplat till nyckeln Movies:ConnectionString:

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

Kommandot dotnet user-secrets list visar följande meddelande:

Movies:ServiceApiKey = 12345

Ta bort alla hemligheter

Anta att programmet secrets.json filen 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 tas bort från filensecrets.json :

{}

dotnet user-secrets list När du kör kommandot 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 Prieskumník riešení och väljer Hantera användarhemligheter:

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

Du kan migrera dina lagrade användarhemligheter från ASP.NET Framework till ASP.NET Core. Mer information finns i GitHub dotnet/aspnetcore.docs issue #27611 - Användarhemlighetsdokumentation nämner inte inkompatibilitet med AssemblyInfo.cs.

Arbeta med 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.

PowerShell

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

.NET CLI

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

När du har installerat paketen 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 hemlig uppsättning med AppSecret nyckeln:

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Relaterat innehåll

• GitHub dotnet/aspnetcore.docs ärende #30378 (Felsökning under Internet Information Services (IIS))
• GitHub dotnet/aspnetcore.docs problem #16328 (körs i IIS)
• Konfiguration i ASP.NET Core
• Azure Key Vault-konfigurationsprovider