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 dizileri geliştirme veya test için kullanılmamalıdır. Gizli diziler uygulamayla dağıtılmamalıdır. Üretim gizli dizilerine 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 Kullanıcı 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.

Uyarı

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 olan , __şöyledir:

• Tüm platformlar tarafından desteklenir.
• otomatik olarak iki nokta üst üste ile :değiştirilir.

Gizli Dizi Yöneticisi

Gizli Dizi Yöneticisi aracı, uygulama geliştirme sırasında hassas verileri depolar. Bu bağlamda, hassas verilerin bir parçası bir uygulama gizli dizisidir. Uygulama gizli dizileri proje ağacından ayrı bir konumda depolanır. Uygulama gizli dizileri belirli bir projeyle ilişkilendirilir veya çeşitli projelerde paylaşılır. Uygulama gizli dizileri kaynak denetiminde denetlenmiyor.

Uyarı

Gizli Dizi Yöneticisi aracı depolanan gizli dizileri ş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.

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

Önceki dosya yollarında değerini proje dosyasında belirtilen değerle UserSecretsId değiştirin<user_secrets_id>.

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 dizi değerleri şifrelenmez.

Gizli depolamayı etkinleştirme

Gizli Dizi Yöneticisi aracı, kullanıcı profilinizde depolanan projeye özgü yapılandırma ayarları üzerinde çalışır.

CLI kullanma

Gizli Dizi Yöneticisi 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 UserSecretsId PropertyGroup öğe ekler. Varsayılan olarak, öğesinin iç metni UserSecretsId bir GUID'dir. İç metin rastgeledir, ancak projeye özgüdür.

<PropertyGroup>
  <TargetFramework>netcoreapp3.1</TargetFramework>
  <UserSecretsId>79a3edd0-2092-40a2-a04d-dcb46d5ca9ed</UserSecretsId>
</PropertyGroup>

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 .

Varsa GenerateAssemblyInfofalse

Derleme bilgisi özniteliklerinin oluşturulması devre dışı bırakıldıysa, öğesini UserSecretsIdAttribute AssemblyInfo.csel ile ekleyin. Örneğin:

[assembly: UserSecretsId("your_user_secrets_id")]

özniteliğini UserSecretsId AssemblyInfo.csel ile eklerken, değerin UserSecretsId proje dosyasındaki değerle eşleşmesi gerekir.

Gizli dizi ayarlama

Bir anahtardan ve değerinden oluşan bir uygulama gizli dizisi tanımlayın. Gizli dizi, 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"

Yukarıdaki örnekte, iki nokta üst üste özelliği olan ServiceApiKey bir nesne değişmez değeri olduğunu Movies 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ı, veya dotnet user-secrets setaracılığıyla dotnet user-secrets remove yapılan değişikliklerden sonra düzleştirilmiştir. Örneğin, çalıştırılırken dotnet user-secrets remove "Movies:ConnectionString" nesne değişmez Movies değeri daraltılır. Değiştirilen dosya aşağıdaki JSON'a benzer:

{
  "Movies:ServiceApiKey": "12345"
}

Birden çok gizli dizi 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 yürütür:

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

Linux / macOS

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

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

Gizli diziye erişme

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

1. Kullanıcı gizli dizileri yapılandırma kaynağını kaydetme
2. Yapılandırma API'sini kullanarak gizli diziyi okuyun

Kullanıcı gizli dizileri yapılandırma kaynağını kaydetme

Kullanıcı gizli dizileri yapılandırma sağlayıcısı uygun 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 () varsayılan yapılandırmayı sağlar ve olduğunda EnvironmentName Developmentöğesini çağırırAddUserSecretsbuilder:

Yapılandırma API'sini kullanarak gizli diziyi okuyun

Anahtarı okumak Movies:ServiceApiKey için aşağıdaki örnekleri 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 Sayfalar sayfası 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.

Gizli dizileri POCO ile eşleme

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 MovieSettings bir POCO'ya bağlanır ve özellik değerine erişir ServiceApiKey :

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

Movies:ConnectionString ve Movies:ServiceApiKey gizli dizileri içindeki MovieSettingsilgili özelliklere eşlenir:

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

    public string ServiceApiKey { get; set; }
}

Gizli dizilerle dize değiştirme

Parolaları düz metin olarak depolamak güvenli değildir. Gizli dizileri hiçbir zaman gibi appsettings.jsonbir yapılandırma dosyasında depolamayın. Bu dosya, kaynak kod deposunda iade edilmiş olabilir.

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

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

<secret value> Önceki örnekte yer tutucuyu parola değeriyle değiştirin. Bir nesnenin Password özelliğindeki SqlConnectionStringBuilder 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();

Gizli dizileri listeleme

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 üst üste, içindeki secrets.jsonnesne hiyerarşisini belirtir.

Tek bir gizli diziyi 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 dizileri 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 clear

Uygulamanın tüm kullanıcı gizli dizileri dosyadan secrets.json silindi:

{}

Çalıştırılıyor dotnet user-secrets list aşağıdaki iletiyi görüntüler:

No secrets configured for this application.

Visual Studio ile kullanıcı gizli dizilerini 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ı gizli dizileri

Hedef Microsoft.NET.Sdk.Web projeler otomatik olarak kullanıcı gizli dizileri için destek içerir. konsol uygulamaları gibi hedef Microsoft.NET.Sdkprojeler için yapılandırma uzantısını ve kullanıcı gizli dizilerini NuGet paketlerini açıkça yükleyin.

PowerShell’i kullanarak:

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ı