ASP.NET Core'da geliştirme aşamasında uygulama gizli dizilerinin güvenli bir şekilde depolanması

Yayımlayanlar Rick Anderson ve Kirk Larkin

Bu makalede, geliştirme makinesindeki bir ASP.NET Core uygulaması için hassas verilerin nasıl yönetileceğini açıklanmaktadır. Parolaları veya diğer hassas verileri asla kaynak kodunda veya yapılandırma dosyalarında depolamayın. Üretim gizli bilgileri geliştirme veya test amaçlı kullanılmamalıdır. Gizli bilgiler uygulamayla dağıtılmamalıdır. Üretim sırlarına Azure Key Vault gibi denetimli bir araç üzerinden erişilmelidir. Azure test ve üretim gizli dizileri Azure Key Vault yapılandırma sağlayıcısıyla depolanabilir ve korunabilir.

Örnek kodu görüntüleme veya indirme (indirme)

Dağıtılan test ve üretim uygulamaları için kimlik doğrulaması hakkında daha fazla bilgi için bkz . Güvenli kimlik doğrulama akışları.

.NET konsol uygulamasında kullanıcı gizli dizilerini kullanmak için bkz. GitHub dotnet/entityframework.docs sorunu #3939.

Ortam değişkenleriyle çalışma

Ortam değişkenleri, uygulama gizli dizilerinin kodda veya yerel yapılandırma dosyalarında depolanmasını önlemek için kullanılır. Ortam değişkenleri, daha önce belirtilen tüm yapılandırma kaynakları için yapılandırma değerlerini geçersiz kılar.

Bireysel Hesaplar güvenliğinin etkinleştirildiği bir ASP.NET Core web uygulaması düşünün. Projede, varsayılan bir veritabanı bağlantı dizesi, DefaultConnection anahtarı altında appsettings.json dosyasında yer alır. Varsayılan bağlantı dizesi, kullanıcı modunda çalışan ve parola gerektirmeyen LocalDB içindir. Uygulama dağıtımı sırasında, anahtar değerini bir ortam değişkeninden alınan değerle geçersiz kılabilirsiniz DefaultConnection . Ortam değişkeni, hassas kimlik bilgilerini içeren tam bağlantı dizesini depolayabilir.

Warning

Ortam değişkenleri genellikle düz, şifrelenmemiş metin olarak depolanır. Makine veya işlemin güvenliği aşılırsa ortam değişkenlerine güvenilmeyen taraflar erişebilir. Kullanıcı gizli dizilerinin açıklanmasını önlemek için ek önlemler gerekebilir.

Üst üste iki nokta (:) ayırıcısı, her platformda ortam değişkeni hiyerarşik anahtarları ile çalışmaz. Örneğin, Bash ayırıcı olarak iki nokta üst üste işaretini (:) desteklemez. Tüm platformlar çift alt çizgi (__) söz dizimini destekler ve bunu otomatik olarak iki nokta (:) ile değiştirir.

Secret Manager aracını kullanma

Secret Manager, uygulama geliştirme sürecinde hassas verileri depolayan bir araçtır. Bu bağlamda, hassas bir veri parçası uygulama gizli anahtarıdır.

• Uygulama sırları proje ağacından ayrı bir konumda saklanır.
• Bunlar belirli bir projeyle ilişkilendirildi veya çeşitli projelerde paylaşıldı.
• Bunlar kaynak denetimine alınmaz.

Warning

Secret Manager, depolanan gizli bilgileri şifrelemez ve güvenilir bir depolama alanı olarak değerlendirilmemelidir. Sadece geliştirme amaçlıdır. Anahtarlar ve değerler, kullanıcı profili dizinindeki bir JSON yapılandırma dosyasında depolanır.

Secret Manager, değerlerin nerede ve nasıl saklandığı gibi uygulama ayrıntılarını gizler. Bu uygulama ayrıntılarını bilmeden aracı kullanabilirsiniz. Değerler yerel makinenin kullanıcı profili klasöründeki bir JSON dosyasında depolanır:

Windows

Dosya sistemi yolu:

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

Linux / macOS

Dosya sistemi yolu:

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

Dosya sistemi yolunda, <user_secrets_id> kısmını proje dosyanızda belirtilen UserSecretsId değeriyle değiştirin.

Gizli Dizi Yöneticisi ile kaydedilen verilerin konumuna veya biçimine bağlı kod yazmayın. Bu uygulama ayrıntıları değişebilir. Örneğin, gizli değerler şifrelenmez.

Gizli depolamayı etkinleştirme

Secret Manager, kullanıcı profilinizde depolanan projeye özgü yapılandırma ayarlarını kullanır.

CLI'yi kullan

Secret Manager, init komutunu içerir. Kullanıcı gizli dizilerini kullanmak için proje dizininde aşağıdaki komutu çalıştırın:

dotnet user-secrets init

Bu komut, proje dosyasının içine bir UserSecretsId öğe eklerPropertyGroup. Varsayılan olarak, UserSecretsId öğesinin iç metni bir GUID'dir. İç metin rastgeledir, ancak projeye özgüdür. Aşağıdaki örnek, 0000a1a1-b2b2-c3c3-d4d4-eeeeee555555 GUID değerini gösterir.

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

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

</Project>

Visual Studio'yu kullanma

Visual Studio'da, Çözüm Gezgini'da projeye sağ tıklayın ve bağlam menüsünden Kullanıcı Gizli Dizilerini Yönet'i seçin. Bu hareket, proje dosyasına GUID ile doldurulmuş bir öğe ekler UserSecretsId .

'GenerateAssemblyInfo' 'false' ise

Derleme bilgisi özniteliklerinin oluşturulması (GenerateAssemblyInfo) devre dışı bırakılırsa (false olarak ayarlanırsa), UserSecretsIdAttribute öğesini AssemblyInfo.cs dosyasına el ile ekleyin. Örneğin:

[assembly: UserSecretsId("your_user_secrets_id")]

özniteliğini UserSecretsIdAssemblyInfo.cs dosyasına el ile eklediğinizde, değerin UserSecretsId proje dosyasındaki değerle eşleşmesi gerekir.

Gizli bilgi ayarlama

Bir anahtardan ve değerinden oluşan bir uygulama sır anahtarı tanımlayın. Gizli anahtar, projenin UserSecretsId değeriyle ilişkilendirilir. Örneğin, proje dosyasının bulunduğu dizinden aşağıdaki komutu çalıştırın:

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

Bu örnekte iki nokta, Movies öğesinin ServiceApiKey özelliğine sahip bir nesne sabiti olduğunu gösterir.

Secret Manager'ı diğer dizinlerden de kullanabilirsiniz. Proje dosyasının --project bulunduğu dosya sistemi yolunu sağlama seçeneğini ekleyin. Örneğin:

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

Visual Studio'da JSON yapısı düzleştirme

Visual Studio Manage User Secrets hareketi, metin düzenleyicisinde bir secrets.json dosyası açar. secrets.json dosyasının içeriğini depoacak anahtar-değer çiftleriyle değiştirin. Örneğin:

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

JSON yapısı, dotnet user-secrets remove veya dotnet user-secrets set komutu aracılığıyla yapılan değişikliklerden sonra düzleştirilir. Örneğin, dotnet user-secrets remove "Movies:ConnectionString" çalıştırmak Movies nesne sözlüğünü daraltır. Değiştirilen dosya aşağıdaki JSON'a benzer:

{
  "Movies:ServiceApiKey": "12345"
}

Birden çok gizli anahtar ayarlama

JSON set komutuna bağlanarak bir dizi gizli dizi ayarlanabilir. Aşağıdaki örnekte, input.json dosyasının içeriği komutuna aktarılır set .

Windows

Aşağıdaki komutu çalıştırın:

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

Linux / macOS

Terminalde aşağıdaki komutu çalıştırın:

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

Gizliye eriş

Gizli bir bilgiye erişmek için aşağıdaki adımları tamamlayın:

1. Kullanıcı gizli bilgileri yapılandırma kaynağını kaydedin.

2. Gizli değeri Yapılandırma API'si aracılığıyla okuyun.

Kullanıcı sırları yapılandırma kaynağını kaydet

Kullanıcı sırları yapılandırma sağlayıcısı, yapılandırma kaynağını .NET Yapılandırma API'sine kaydeder.

dotnet new komutuyla veya Visual Studio ile oluşturulan ASP.NET Core web uygulamaları aşağıdaki kodu oluşturur:

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

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

app.Run();

WebApplication.CreateBuilder yöntemi, önceden yapılandırılmış varsayılanlarla sınıfının yeni bir örneğini WebApplicationBuilder başlatır. Başlatılan WebApplicationBuilder (builder), varsayılan yapılandırma sağlar ve EnvironmentName özelliği Development olduğunda AddUserSecrets yöntemini çağırır.

Yapılandırma API'sini kullanarak gizliyi okuyun

Aşağıdaki örneklerde anahtarın nasıl okunduğu gösterilmektedir Movies:ServiceApiKey :

Program.cs dosyası

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

var app = builder.Build();

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

app.Run();

Razor Sayfalar sayfa modeli

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

Daha fazla bilgi için, bkz. ASP.NET Core’da yapılandırma analizi.

Map secret bilgilerini bir POCO'ya eşleştirme

Bir nesne sabit değerinin tamamını POCO'ya (özelliklere sahip basit bir .NET sınıfı) eşlemek, ilgili özellikleri toplamada yararlıdır.

Uygulama secrets.json dosyasının aşağıdaki iki gizli diziyi içerdiğini varsayalım:

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

Önceki gizli dizileri bir POCO ile eşlemek için .NET Yapılandırma API'sinin nesne grafı bağlama özelliğini kullanın. Aşağıdaki kod, özel bir MovieSettings POCO'ya bağlanır ve ServiceApiKey özellik değerine erişir:

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

Movies:ConnectionString ve Movies:ServiceApiKey gizli anahtarları, MovieSettings içindeki ilgili özelliklere eşlenir.

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

    public string ServiceApiKey { get; set; }
}

Gizli anahtarlarla dize değiştirme kullanın

Parolaları düz metin olarak depolamak güvenli değildir. appsettings.json gibi, kaynak kod deposuna işlenebilecek bir yapılandırma dosyasında gizli bilgileri asla depolamayın.

Örneğin, appsettings.json dosyasında depolanan bir veritabanı bağlantı dizesi parola içermemelidir. Bunun yerine parolayı gizli bilgi olarak depolayın ve çalışma zamanında bağlantı dizesine parolayı dahil edin. Örneğin:

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

Örnekteki <secret value> yer tutucuyu parola değeriyle değiştirin. Bir nesnenin SqlConnectionStringBuilder özelliğindeki Password gizli anahtarın değerini, bağlantı dizesi parola değeri olarak içerecek şekilde ayarlayın:

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

Sırları listele

Uygulama secrets.json dosyasının aşağıdaki iki gizli diziyi içerdiğini varsayalım:

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

Proje dosyasının bulunduğu dizinden aşağıdaki komutu çalıştırın:

dotnet user-secrets list

Aşağıdaki çıkış görüntülenir:

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

Örnekte, anahtar adlarındaki iki nokta üst üste (:), secrets.json dosyasındaki nesne hiyerarşisini belirtir.

Tek bir sırrı kaldırma

Uygulama secrets.json dosyasının aşağıdaki iki gizli diziyi içerdiğini varsayalım:

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

Proje dosyasının bulunduğu dizinden aşağıdaki komutu çalıştırın:

dotnet user-secrets remove "Movies:ConnectionString"

Uygulama secrets.json dosyası, anahtarla ilişkili anahtar-değer çiftini Movies:ConnectionString kaldırmak için değiştirilir:

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

Komut dotnet user-secrets list aşağıdaki iletiyi görüntüler:

Movies:ServiceApiKey = 12345

Tüm gizli bilgileri kaldır

Uygulama secrets.json dosyasının aşağıdaki iki gizli diziyi içerdiğini varsayalım:

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

Proje dosyasının bulunduğu dizinden aşağıdaki komutu çalıştırın:

dotnet user-secrets clear

Uygulamanın tüm kullanıcı gizli dizileri secrets.json dosyasından silinir:

{}

komutu çalıştırılırken dotnet user-secrets list aşağıdaki ileti görüntülenir:

No secrets configured for this application.

Visual Studio ile kullanıcı sırlarını yönetme

Visual Studio'da kullanıcı gizli dizilerini yönetmek için Çözüm Gezgini'da projeye sağ tıklayın ve User Secrets öğesini seçin:

Kullanıcı gizli bilgilerini ASP.NET Framework'ten ASP.NET Core'a geçirme

Depolanmış kullanıcı gizli bilgilerinizi ASP.NET Framework'ten ASP.NET Core'a taşıyabilirsiniz. Daha fazla bilgi için bkz. GitHub dotnet/aspnetcore.docs sorunu #27611 - Kullanıcı Gizli Dizileri belgelerinde AssemblyInfo.cs uyumsuzluğundan bahsedilmiyor.

Web dışı uygulamalarda kullanıcı sırlarıyla çalışma

Hedef Microsoft.NET.Sdk.Web projelere otomatik olarak kullanıcı sırları için destek eklenir. Microsoft.NET.Sdk hedefleyen projeler, örneğin konsol uygulamaları için, yapılandırma uzantısını ve kullanıcı sırlarını NuGet paketleri olarak açıkça yükleyin.

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

Paketleri yükledikten sonra projeyi başlatın ve gizli dizileri bir web uygulamasıyla aynı şekilde ayarlayın. Aşağıdaki örnekte anahtarla bir gizli dizi kümesinin değerini alan bir konsol uygulaması gösterilmektedir 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"]);
    }
}

İlgili içerik

• GitHub dotnet/aspnetcore.docs sorunu #30378 (Internet Information Services (IIS) altında hata ayıklama)
• GitHub dotnet/aspnetcore.docs sorunu #16328 (IIS'de çalıştırılıyor)
• ASP.NET Core'da yapılandırma
• Azure Key Vault yapılandırma sağlayıcısı