Az alkalmazás titkos kulcsainak biztonságos tárolása a fejlesztés során a ASP.NET Core-ban

Rick Anderson és Kirk Larkin

Ez a cikk azt ismerteti, hogyan kezelheti a ASP.NET Core-alkalmazások bizalmas adatait egy fejlesztői gépen. Soha ne tároljon jelszavakat vagy más bizalmas adatokat forráskódban vagy konfigurációs fájlokban. A gyártási titkokat nem szabad fejlesztésre vagy tesztelésre használni. Titkokat nem szabad üzembe helyezni az alkalmazással együtt. A gyártási titkokhoz egy kontrollált módon kell hozzáférni, mint például az Azure Key Vault. Az Azure-teszt- és éles titkos kódok az Azure Key Vault konfigurációszolgáltatójával tárolhatók és védhetők.

A mintakód megtekintése vagy letöltése (letöltés)

Az üzembe helyezett teszt- és éles alkalmazások hitelesítéséről további információt Biztonságos hitelesítési folyamatokcímű témakörben talál.

Ha felhasználói titkos kódokat szeretne használni egy .NET konzolalkalmazásban, olvassa el a GitHub dotnet/entityframework.docs 3939 című témakört.

Környezeti változók használata

A környezeti változók az alkalmazáskulcsok kódban vagy helyi konfigurációs fájlokban való tárolásának elkerülésére szolgálnak. A környezeti változók felülbírálják az összes korábban megadott konfigurációs forrás konfigurációs értékeit.

Fontolja meg egy ASP.NET Core-webalkalmazást, amelyben engedélyezve van az egyéni fiókok biztonsága. A projekt appsettings.json fájlja tartalmaz egy alapértelmezett adatbázis-kapcsolati karakterláncot a(z) DefaultConnection kulccsal. Az alapértelmezett kapcsolati sztring a LocalDB-hez tartozik, amely felhasználói módban fut, és nem igényel jelszót. Az alkalmazás üzembe helyezése során felülbírálhatja a DefaultConnection kulcs értékét egy környezeti változó értékével. A környezeti változó tárolhatja a teljes kapcsolati karakterláncot az érzékeny hitelesítési adatokkal együtt.

Warning

A környezeti változók gyakran egyszerű, titkosítatlan szövegként vannak tárolva. Ha a gép vagy a folyamat sérült, a környezeti változók nem megbízható felek számára érhetők el. További intézkedésekre lehet szükség a felhasználói titkos kódok felfedésének megakadályozására.

A kettőspont (:) elválasztó nem működik a környezeti változók hierarchikus kulcsaival minden platformon. A Bash például nem támogatja a kettőspontot (:) elválasztóként. Minden platform támogatja a dupla aláhúzás (__) szintaxist, és automatikusan kettőspontra (:) cseréli.

A Secret Manager eszköz használata

A Secret Manager egy olyan eszköz, amely bizalmas adatokat tárol az alkalmazásfejlesztés során. Ebben az összefüggésben a bizalmas adatok egy része alkalmazástitkos.

• Az alkalmazás titkos kulcsainak tárolása a projektfától eltérő helyen történik.
• Egy adott projekthez vannak társítva, vagy több projektben vannak megosztva.
• A rendszer nem ellenőrzi őket a forrásvezérlőben.

Warning

A Secret Manager nem titkosítja a tárolt titkos kulcsokat, és nem kell megbízható tárolóként kezelni. Csak fejlesztési célokat szolgál. A kulcsok és értékek egy JSON-konfigurációs fájlban vannak tárolva a felhasználói profil könyvtárában.

A Secret Manager elrejti a megvalósítás részleteit, például az értékek tárolásának helyét és módját. Az eszközt anélkül használhatja, hogy ismerné ezeket a megvalósítási részleteket. Az értékek egy JSON-fájlban vannak tárolva a helyi gép felhasználói profilmappájában:

Windows

Fájlrendszer elérési útja:

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

Linux/macOS

Fájlrendszer elérési útja:

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

A fájlrendszer elérési útján cserélje le a <user_secrets_id> részt a UserSecretsId projektfájlban megadott értékre.

Ne írjon olyan kódot, amely a Secret Managerrel mentett adatok helyétől vagy formátumától függ. Ezek a megvalósítás részletei változhatnak. A titkos értékek például nincsenek titkosítva.

Titkos kulcsok tárolásának engedélyezése

A Secret Manager a felhasználói profilban tárolt projektspecifikus konfigurációs beállításokon működik.

A parancssori felület (CLI) használata

A Secret Manager tartalmaz egy init parancsot. A felhasználói titkos kódok használatához futtassa a következő parancsot a projektkönyvtárban:

dotnet user-secrets init

Ez a parancs hozzáad egy UserSecretsId elemet a projektfájlhoz PropertyGroup . Alapértelmezés szerint a UserSecretsId belső szövege egy GUID. A belső szöveg tetszőleges, de egyedi a projektben. Az alábbi példa a GUID értékét 0000a1a1-b2b2-c3c3-d4d4-eeeeee555555mutatja be.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <UserSecretsId>0000a1a1-b2b2-c3c3-d4d4-eeeeee555555</UserSecretsId>
  </PropertyGroup>

</Project>

A Visual Studio használata

A Visual Studióban kattintson a jobb gombbal a projektre a Megoldáskezelőben, és válassza a Helyi menü Felhasználói titkos kulcsok kezelése parancsát . Ez a kézmozdulat egy UserSecretsId GUID azonosítóval kitöltött elemet ad hozzá a projektfájlhoz.

Ha a GenerateAssemblyInfo értéke "hamis"

Ha az összeállítási információs attribútumok létrehozása (GenerateAssemblyInfo) le van tiltva (azaz false értékre van állítva), manuálisan adja hozzá a(z) UserSecretsIdAttribute elemet a(z) AssemblyInfo.cs fájlban. Például:

[assembly: UserSecretsId("your_user_secrets_id")]

Ha manuálisan adja hozzá az UserSecretsId attribútumot a AssemblyInfo.cs fájlhoz, az UserSecretsId értéknek meg kell egyeznie a projektfájlban lévő értékkel.

Titkos kód beállítása

Egy kulcsból és annak értékéből álló alkalmazástitkot definiálhat. A titkos kód a projekt értékéhez UserSecretsId van társítva. Futtassa például a következő parancsot abból a könyvtárból, amelyben a projektfájl létezik:

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

Ebben a példában a kettőspont azt jelzi, hogy Movies egy objektumkonstans egy ServiceApiKey tulajdonsággal.

A Secret Manager szolgáltatást más mappákból is használhatja. Adja meg a --project beállítást annak a fájlrendszerbeli elérési útnak a megadásához, amelyen a projektfájl található. Például:

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

JSON-struktúra simítása a Visual Studióban

A Visual Studio Felhasználói titkos kódok kezelése kézmozdulat megnyit egy secrets.json fájlt a szövegszerkesztőben. Cserélje le a secrets.json fájl tartalmát a tárolni kívánt kulcs-érték párokra. Például:

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

A JSON-struktúra a dotnet user-secrets remove vagy dotnet user-secrets set paranccsal végzett módosítások után ellaposodik. A dotnet user-secrets remove "Movies:ConnectionString" futtatása például összecsukja az objektumliterált Movies. A módosított fájl a következő JSON-fájlhoz hasonlít:

{
  "Movies:ServiceApiKey": "12345"
}

Több titkos kulcs beállítása

A titkos kódok kötegét úgy állíthatja be, hogy a JSON-t a set parancsra irányítja. Az alábbi példában a input.json fájl tartalma a set parancsnak van átirányítva.

Windows

Futtassa a következő parancsot:

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

Linux/macOS

Futtassa a következő parancsot a terminálban:

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

Hozzáférés egy titokhoz

Egy titkos kód eléréséhez hajtsa végre a következő lépéseket:

1. Regisztrálja a felhasználói titkos kulcsok konfigurációs forrását.

2. Olvassa el a titkos kulcsot a Configuration API-val.

A felhasználói titkos kódok konfigurációs forrásának regisztrálása

A felhasználói titkos kódok konfigurációszolgáltatója regisztrálja a megfelelő konfigurációs forrást a .NET Configuration API-val.

ASP.NET Core dotnet new paranccsal létrehozott webalkalmazások Visual Studio a következő kódot generálják:

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

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

app.Run();

A WebApplication.CreateBuilder metódus inicializálja az WebApplicationBuilder osztály új példányát előre konfigurált alapértelmezett értékekkel. Az inicializált WebApplicationBuilder (builder) alapértelmezett konfigurációt biztosít, és meghívja a AddUserSecrets metódust, ha a EnvironmentName tulajdonság értéke .Development

A titkos kód beolvasása a Configuration API-val

Az alábbi példák bemutatják, hogyan olvasható be a Movies:ServiceApiKey kulcs:

Program.cs fájl

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

var app = builder.Build();

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

app.Run();

Razor Pages lapmodellje

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

További információkért lásd: Konfiguráció az ASP.NET Core-ben.

Titkos kódok leképezése POCO-ra

A teljes objektum literálját POCO-ra (egyszerű .NET-osztály tulajdonságokkal) való leképezés hasznos lehet a kapcsolódó tulajdonságok összesítéséhez.

Tegyük fel, hogy az alkalmazás secrets.json fájl a következő két titkos kódot tartalmazza:

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

Az előző titkos kódok POCO-ra való leképezéséhez használja a .NET Configuration API objektumgráf-kötési funkcióját. A következő kód egy egyéni MovieSettings POCO-hoz kapcsolódik, és hozzáfér a ServiceApiKey tulajdonságértékhez:

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

A Movies:ConnectionString és Movies:ServiceApiKey titkok a MovieSettings megfelelő tulajdonságaira vannak leképezve.

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

    public string ServiceApiKey { get; set; }
}

Sztringhelyettesítés használata titkos kulcsokkal

A jelszavak egyszerű szövegben való tárolása nem biztonságos. Soha ne tároljon titkos kulcsokat olyan konfigurációs fájlban, mint például aappsettings.json, amely be van jelentkezve egy forráskódtárba.

Egy kapcsolati karakterlánc appsettings.json fájlban tárolt adatbázisnak például nem szabad jelszót tartalmaznia. Ehelyett tárolja a jelszót titokként, és futtatáskor adja meg a jelszót a kapcsolati sztringben. Például:

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

Cserélje le a <secret value> példában szereplő helyőrzőt a jelszó értékére. Állítsa be a titkos kód értékét egy objektum tulajdonságán SqlConnectionStringBuilder úgy, hogy az a kapcsolati sztringben Password jelszóértékként szerepeljen:

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

Titkos kódok listázása

Tegyük fel, hogy az alkalmazás secrets.json fájl a következő két titkos kódot tartalmazza:

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

Futtassa a következő parancsot abból a könyvtárból, amelyben a projektfájl létezik:

dotnet user-secrets list

A következő kimenet jelenik meg:

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

A példában a kulcsnevekben lévő kettőspont (:) a secrets.json fájl objektumhierarchiáját jelöli.

Egyetlen titkos kód eltávolítása

Tegyük fel, hogy az alkalmazás secrets.json fájl a következő két titkos kódot tartalmazza:

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

Futtassa a következő parancsot abból a könyvtárból, amelyben a projektfájl létezik:

dotnet user-secrets remove "Movies:ConnectionString"

Az alkalmazás secrets.json fájl úgy módosul, hogy eltávolítsa a kulcshoz társított kulcs-érték párot Movies:ConnectionString :

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

A dotnet user-secrets list parancs a következő üzenetet jeleníti meg:

Movies:ServiceApiKey = 12345

Az összes titkos kód eltávolítása

Tegyük fel, hogy az alkalmazás secrets.json fájl a következő két titkos kódot tartalmazza:

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

Futtassa a következő parancsot abból a könyvtárból, amelyben a projektfájl létezik:

dotnet user-secrets clear

Az alkalmazáshoz tartozó összes felhasználói titkos kód törlődik a secrets.json fájlból:

{}

A parancs futtatása a dotnet user-secrets list következő üzenetet jeleníti meg:

No secrets configured for this application.

Felhasználói titkos kódok kezelése a Visual Studióval

A felhasználói titkos kódok Visual Studio való kezeléséhez kattintson a jobb gombbal a projektre a Megoldáskezelő, és válassza a Felhasználói titkos kódok kezelése:

Felhasználói titkos kódok migrálása ASP.NET-keretrendszerből ASP.NET Core

A tárolt felhasználói titkos kulcsokat áttelepítheti ASP.NET Keretrendszerből ASP.NET Core. További információ: GitHub dotnet/aspnetcore.docs probléma #27611 - A titkos kulcsok dokumentációja nem említi a AssemblyInfo.cs-vel való kompatibilitást.

Felhasználói titkos kódok kezelése nem webes alkalmazásokban

A megcélzott Microsoft.NET.Sdk.Web projektek automatikusan támogatják a felhasználói titkos kulcsokat. Azoknál a projekteknél, amelyek Microsoft.NET.Sdk-et céloznak meg, például konzolalkalmazások esetében, telepítse kifejezetten a konfigurációs bővítményt és a felhasználói titkos NuGet-csomagokat.

PowerShell

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

.NET parancssori felület

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

A csomagok telepítése után inicializálja a projektet , és állítsa be a titkos kulcsokat ugyanúgy, mint egy webalkalmazás esetében. Az alábbi példa egy konzolalkalmazást mutat be, amely lekéri egy titkos kódkészlet értékét a AppSecret kulccsal:

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Kapcsolódó tartalom

• GitHub dotnet/aspnetcore.docs hibajegy #30378 (Hibakeresés az Internet Information Services (IIS) alatt)
• GitHub dotnet/aspnetcore.docs probléma #16328 (IIS-ben futtatva)
• Az ASP.NET Core konfigurációja
• Azure Key Vault konfiguráció szolgáltató