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

Yayımlayanlar Rick Anderson ve Kirk Larkin

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

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.

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ı.

Bir .NET konsol uygulamasında kullanıcı gizli dizilerini kullanmak için bu GitHub sorununa bakın.

Ortam değişkenleri

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. Projenin appsettings.json dosyasına anahtarıyla DefaultConnectionbirlikte varsayılan veritabanı bağlantı dizesi eklenir. 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ğeri bir DefaultConnection ortam değişkeninin değeriyle geçersiz kılınabilir. Ortam değişkeni, hassas kimlik bilgileriyle tam bağlantı dizesi depolayabilir.

Warning

Ortam değişkenleri genellikle düz, şifrelenmemiş metinde depolanır. Makine veya işlemin güvenliği ihlal edilirse ortam değişkenlerine güvenilmeyen taraflar tarafından erişilebilir. Kullanıcı gizli dizilerinin açığa çıkmasını önlemek için ek önlemler gerekebilir.

: ayıracı, tüm platformlarda ortam değişkeni hiyerarşik anahtarlarıyla çalışmaz. Örneğin, : ayırıcı Bash tarafından desteklenmez. Çift alt çizgi, __, tüm platformlar tarafından desteklenir ve otomatik olarak iki nokta, :, ile değiştirilir.

Gizli Yönetici

Gizli Bilgi Yöneticisi aracı, uygulama geliştirme sırasında hassas verileri depolar. Bu bağlamda, hassas veri bir uygulama sırrıdır. Uygulama sırları proje ağacından ayrı bir konumda saklanır. Uygulama sırları belirli bir projeyle ilişkilendirilir veya birden fazla projede paylaşılır. Uygulama sırları kaynak denetimine dahil edilmiyor.

Warning

Sır Yöneticisi aracı depolanan sırları şifrelemez ve güvenilir bir depo 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 aracı nasıl çalışır?

Gizli Dizi Yöneticisi aracı, değerlerin nerede ve nasıl depolandığı 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

Proje dosyasında belirtilen UserSecretsId değeriyle <user_secrets_id> değerini önceki dosya yollarında değiştirin.

Gizli Dizi Yöneticisi aracıyla 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

Sır Yöneticisi aracı, kullanıcı profilinizde depolanan projeye özgü yapılandırma ayarları üzerinde işler.

CLI'yi kullan

Gizli Yönetici aracı bir init komut içerir. Kullanıcı gizli dizilerini kullanmak için proje dizininde aşağıdaki komutu çalıştırın:

dotnet user-secrets init

Yukarıdaki komut, proje dosyasının içine bir UserSecretsIdPropertyGroup öğe ekler. Varsayılan olarak, UserSecretsId öğesinin iç metni bir GUID'dir. İç metin rastgeledir, ancak projeye özgüdür.

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 .

Eğer GenerateAssemblyInfo ise false

Derleme bilgi özniteliklerinin oluşturulması devre dışı bırakıldıysa, UserSecretsIdAttribute öğesini AssemblyInfo.cs içinde el ile ekleyin. Örneğin:

[assembly: UserSecretsId("your_user_secrets_id")]

özniteliğini UserSecretsIdAssemblyInfo.csel ile eklerken, 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"

Önceki örnekte, iki nokta üst üste işareti, Movies nesne literalının ServiceApiKey özelliği olduğunu belirtir.

Gizli Dizi Yöneticisi aracı diğer dizinlerden de kullanılabilir. Proje dosyasının --project bulunduğu dosya sistemi yolunu sağlamak için seçeneğini kullanın. Ö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'nun Kullanıcı Gizli Dizilerini Yönet hareketi, metin düzenleyicisinde bir secrets.json dosya açar. öğesinin içeriğini secrets.json depolanacak 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 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 dosyanın içeriği komutuna set aktarılır.

Windows

Bir komut kabuğu açın ve aşağıdaki komutu çalıştırın:

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

Linux / macOS

Bir komut kabuğu açın ve 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ı sırları yapılandırma kaynağını kaydet
2. Yapılandırma API'sini kullanarak gizli bilgiyi 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 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 önceden yapılandırılmış varsayılanlarla WebApplicationBuilder sınıfının yeni bir örneğini başlatır. Başlatılan WebApplicationBuilder (builder), varsayılan yapılandırmayı sağlar ve EnvironmentNameDevelopment olduğunda AddUserSecrets öğesini çağırır.

Yapılandırma API'sini kullanarak gizliyi okuyun

Aşağıdaki anahtar Movies:ServiceApiKey okuma örneklerini göz önünde bulundurun:

Program.cs dosyası:

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

var app = builder.Build();

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

app.Run();

Razor 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.

Uygulamanın secrets.json dosyasında aşağıdaki iki gizli dizi olduğunu 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; }
}

Sırlarla dize değiştirme

Parolaları düz metin olarak depolamak güvenli değildir. Gizli bilgileri hiçbir zaman gibi appsettings.json yapılandırma dosyasında depolamayın. Bu dosya, versiyon kontrol sistemine kaydolabilir.

Örneğin, içinde depolanan appsettings.json 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>`"

<secret value> Önceki örnekte 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

Uygulamanın secrets.json dosyasında aşağıdaki iki gizli dizi olduğunu 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

Yukarıdaki örnekte, anahtar adlarındaki iki nokta, secrets.json içindeki nesne hiyerarşisini belirtir.

Tek bir sırrı kaldırma

Uygulamanın secrets.json dosyasında aşağıdaki iki gizli dizi olduğunu 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"

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

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

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

Movies:ServiceApiKey = 12345

Tüm gizli bilgileri kaldır

Uygulamanın secrets.json dosyasında aşağıdaki iki gizli dizi olduğunu 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 kullanıcıya ait tüm gizli bilgiler secrets.json dosyasından silindi.

{}

dotnet user-secrets list komutunu çalıştırmak, aşağıdaki mesajı görüntüler:

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 gezgininde projeye sağ tıklayın ve Kullanıcı Gizli Dizilerini Yönet'i seçin:

Kullanıcı Gizli Dizilerini ASP.NET Framework'ten ASP.NET Core'a Geçirme

Bu GitHub sorununa bakın.

Web dışı uygulamalarda kullanıcı sırları

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'i kullanma:

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

.NET CLI'yi kullanma:

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

Paketler yüklendikten sonra projeyi başlatın ve gizli dizileri bir web uygulamasıyla aynı şekilde ayarlayın. Aşağıdaki örnekte, "AppSecret" anahtarıyla ayarlanmış bir gizli dizinin değerini alan bir konsol uygulaması gösterilmektedir:

using Microsoft.Extensions.Configuration;

namespace ConsoleApp;

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

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

Ek kaynaklar

• IIS'den kullanıcı gizli dizilerine erişme hakkında bilgi için bu soruna ve bu soruna bakın.
• ASP.NET Core'da yapılandırma
• ASP.NET Core'da Azure Key Vault yapılandırma sağlayıcısı