Brankas penyimpanan rahasia aplikasi dalam pengembangan di ASP.NET Core

Oleh Rick Anderson dan Kirk Larkin

Melihat atau mengunduh kode sampel (cara mengunduh)

Dokumen ini menjelaskan cara mengelola data sensitif untuk aplikasi ASP.NET Core pada komputer pengembangan. Jangan pernah menyimpan kata sandi atau data sensitif lainnya dalam kode sumber. Rahasia produksi tidak boleh digunakan untuk pengembangan atau pengujian. Rahasia tidak boleh disebarkan dengan aplikasi. Sebagai gantinya, rahasia produksi harus diakses melalui cara terkontrol seperti variabel lingkungan atau Azure Key Vault. Anda dapat menyimpan dan melindungi rahasia pengujian dan produksi Azure dengan penyedia konfigurasi Azure Key Vault.

Untuk menggunakan rahasia pengguna di aplikasi konsol .NET, lihat masalah GitHub ini.

Variabel lingkungan

Variabel lingkungan digunakan untuk menghindari penyimpanan rahasia aplikasi dalam kode atau dalam file konfigurasi lokal. Variabel lingkungan mengambil alih nilai konfigurasi untuk semua sumber konfigurasi yang ditentukan sebelumnya.

Pertimbangkan aplikasi web ASP.NET Core tempat keamanan Akun Pengguna Individual diaktifkan. Database default string koneksi disertakan dalam file proyek appsettings.json dengan kunci DefaultConnection. String koneksi default adalah untuk LocalDB, yang berjalan dalam mode pengguna dan tidak memerlukan kata sandi. Selama penyebaran aplikasi, DefaultConnection nilai kunci dapat diganti dengan nilai variabel lingkungan. Variabel lingkungan dapat menyimpan string koneksi lengkap dengan kredensial sensitif.

Peringatan

Variabel lingkungan umumnya disimpan dalam teks biasa dan tidak terenkripsi. Jika mesin atau proses disusupi, variabel lingkungan dapat diakses oleh pihak yang tidak tepercaya. Langkah-langkah tambahan untuk mencegah pengungkapan rahasia pengguna mungkin diperlukan.

Pemisah : tidak berfungsi dengan kunci hierarkis variabel lingkungan di semua platform. __, garis bawah ganda:

• Didukung oleh semua platform. Misalnya, pemisah : tidak didukung oleh Bash, tetapi __ didukung.
• Secara otomatis diganti dengan :

Manajer Rahasia

Alat Secret Manager menyimpan data sensitif selama pengembangan aplikasi. Dalam konteks ini, sepotong data sensitif adalah rahasia aplikasi. Rahasia aplikasi disimpan di lokasi terpisah dari pohon proyek. Rahasia aplikasi dikaitkan dengan proyek tertentu atau dibagikan di beberapa proyek. Rahasia aplikasi tidak diperiksa ke kontrol sumber.

Peringatan

Alat Secret Manager tidak mengenkripsi rahasia yang disimpan dan tidak boleh diperlakukan sebagai penyimpanan tepercaya. Ini hanya untuk tujuan pengembangan. Kunci dan nilai disimpan dalam JSfile konfigurasi ON di direktori profil pengguna.

Cara kerja alat Secret Manager

Alat Secret Manager menyembunyikan detail implementasi, seperti di mana dan bagaimana nilai disimpan. Anda dapat menggunakan alat ini tanpa mengetahui detail implementasi ini. Nilai disimpan dalam JSfile ON di folder profil pengguna komputer lokal:

Windows

Jalur sistem file:

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

Linux / macOS

Jalur sistem file:

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

Di jalur file sebelumnya, ganti <user_secrets_id> dengan UserSecretsId nilai yang ditentukan dalam file proyek.

Jangan menulis kode yang bergantung pada lokasi atau format data yang disimpan dengan alat Secret Manager. Detail implementasi ini dapat berubah. Misalnya, nilai rahasia tidak dienkripsi, tetapi bisa di masa depan.

Aktifkan penyimpanan rahasia

Alat Secret Manager beroperasi pada pengaturan konfigurasi khusus proyek yang disimpan di profil pengguna Anda.

Menggunakan CLI

Alat Secret Manager menyertakan init perintah. Untuk menggunakan rahasia pengguna, jalankan perintah berikut di direktori proyek:

dotnet user-secrets init

Perintah sebelumnya menambahkan UserSecretsId elemen dalam PropertyGroup file proyek. Secara default, teks UserSecretsId dalam adalah GUID. Teks dalam bersifat arbitrer, tetapi unik untuk proyek.

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

Gunakan Visual Studio

Di Visual Studio, klik kanan proyek di Penjelajah Solusi, dan pilih Kelola Rahasia Pengguna dari menu konteks. Gerakan ini menambahkan UserSecretsId elemen, diisi dengan GUID, ke file proyek.

Jika GenerateAssemblyInfo adalah false

Jika pembuatan atribut info perakitan dinonaktifkan, tambahkan UserSecretsIdAttribute secara manual di AssemblyInfo.cs. Contohnya:

[assembly: UserSecretsId("your_user_secrets_id")]

Saat menambahkan UserSecretsId atribut secara manual ke AssemblyInfo.cs, UserSecretsId nilai harus cocok dengan nilai dalam file proyek.

Menetapkan rahasia

Tentukan rahasia aplikasi yang terdiri dari kunci dan nilainya. Rahasia dikaitkan dengan nilai proyek UserSecretsId . Misalnya, jalankan perintah berikut dari direktori tempat file proyek ada:

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

Dalam contoh sebelumnya, titik dua menunjukkan bahwa Movies merupakan objek literal dengan ServiceApiKey properti.

Alat Secret Manager juga dapat digunakan dari direktori lain. --project Gunakan opsi untuk menyediakan jalur sistem file tempat file proyek ada. Contohnya:

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

JSStruktur ON meratakan di Visual Studio

Gerakan Kelola Rahasia Pengguna Visual Studio membuka secrets.json file di editor teks. Ganti konten secrets.json dengan pasangan kunci-nilai yang akan disimpan. Contohnya:

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

Struktur JSON diratakan setelah modifikasi melalui dotnet user-secrets remove atau dotnet user-secrets set. Misalnya, menjalankan dotnet user-secrets remove "Movies:ConnectionString" menciutkan Movies objek secara harfiah. File yang dimodifikasi menyerupan ON berikut JS:

{
  "Movies:ServiceApiKey": "12345"
}

Mengatur beberapa rahasia

Batch rahasia dapat diatur dengan melakukan piping JSON ke set perintah . Dalam contoh berikut, input.json konten file disalurkan ke set perintah .

Windows

Buka shell perintah, dan jalankan perintah berikut:

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

Linux / macOS

Buka shell perintah, dan jalankan perintah berikut:

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

Mengakses rahasia

Untuk mengakses rahasia, selesaikan langkah-langkah berikut:

1. Mendaftarkan sumber konfigurasi rahasia pengguna
2. Membaca rahasia melalui API Konfigurasi

Mendaftarkan sumber konfigurasi rahasia pengguna

Penyedia konfigurasi rahasia pengguna mendaftarkan sumber konfigurasi yang sesuai dengan .NET Configuration API.

Aplikasi web ASP.NET Core yang dibuat dengan dotnet baru atau Visual Studio menghasilkan kode berikut:

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

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

app.Run();

WebApplication.CreateBuilder menginisialisasi instans baru kelas WebApplicationBuilder dengan default yang telah dikonfigurasi sebelumnya. Inisialisasi WebApplicationBuilderAddUserSecrets (builder) menyediakan konfigurasi dan panggilan default saat EnvironmentName adalah Development:

Membaca rahasia melalui API Konfigurasi

Pertimbangkan contoh membaca Movies:ServiceApiKey kunci berikut:

file Program.cs:

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

var app = builder.Build();

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

app.Run();

Razor Model halaman Halaman:

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

Untuk informasi lebih lanjut, lihat Konfigurasi di ASP.NET Core.

Memetakan rahasia ke POCO

Memetakan seluruh objek secara harfiah ke POCO (kelas .NET sederhana dengan properti) berguna untuk menggabungkan properti terkait.

Asumsikan file aplikasi secrets.json berisi dua rahasia berikut:

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

Untuk memetakan rahasia sebelumnya ke POCO, gunakan fitur pengikatan grafik objek .NET Configuration API. Kode berikut mengikat ke POCO kustom MovieSettings dan mengakses ServiceApiKey nilai properti:

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

Rahasia Movies:ConnectionString dan Movies:ServiceApiKey dipetakan ke properti masing-masing di MovieSettings:

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

    public string ServiceApiKey { get; set; }
}

Penggantian string dengan rahasia

Menyimpan kata sandi dalam teks biasa tidak aman. Misalnya, database yang string koneksi disimpan appsettings.json mungkin menyertakan kata sandi untuk pengguna yang ditentukan:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;Password=pass123;MultipleActiveResultSets=true"
  }
}

Pendekatan yang lebih aman adalah menyimpan kata sandi sebagai rahasia. Contohnya:

dotnet user-secrets set "DbPassword" "pass123"

Password Hapus pasangan kunci-nilai dari string koneksi di appsettings.json. Contohnya:

{
  "ConnectionStrings": {
    "Movies": "Server=(localdb)\\mssqllocaldb;Database=Movie-1;User Id=johndoe;MultipleActiveResultSets=true"
  }
}

Nilai rahasia dapat diatur pada SqlConnectionStringBuilder properti objek Password untuk menyelesaikan string koneksi:

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

Mencantumkan rahasia

Asumsikan file aplikasi secrets.json berisi dua rahasia berikut:

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

Jalankan perintah berikut dari direktori tempat file proyek berada:

dotnet user-secrets list

Output berikut muncul:

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

Dalam contoh sebelumnya, titik dua dalam nama kunci menunjukkan hierarki objek dalam secrets.json.

Menghapus satu rahasia

Asumsikan file aplikasi secrets.json berisi dua rahasia berikut:

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

Jalankan perintah berikut dari direktori tempat file proyek berada:

dotnet user-secrets remove "Movies:ConnectionString"

File aplikasi secrets.json dimodifikasi untuk menghapus pasangan kunci-nilai yang Movies:ConnectionString terkait dengan kunci:

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

dotnet user-secrets list menampilkan pesan berikut:

Movies:ServiceApiKey = 12345

Menghapus semua rahasia

Asumsikan file aplikasi secrets.json berisi dua rahasia berikut:

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

Jalankan perintah berikut dari direktori tempat file proyek berada:

dotnet user-secrets clear

Semua rahasia pengguna untuk aplikasi telah dihapus dari secrets.json file:

{}

Menjalankan dotnet user-secrets list menampilkan pesan berikut:

No secrets configured for this application.

Mengelola rahasia pengguna dengan Visual Studio

Untuk mengelola rahasia pengguna di Visual Studio, klik kanan proyek di penjelajah solusi dan pilih Kelola Rahasia Pengguna:

Memigrasikan Rahasia Pengguna dari ASP.NET Framework ke ASP.NET Core

Lihat masalah GitHub ini.

Rahasia pengguna dalam aplikasi non-web

Proyek yang menargetkan Microsoft.NET.Sdk.Web secara otomatis menyertakan dukungan untuk rahasia pengguna. Untuk proyek yang menargetkan Microsoft.NET.Sdk, seperti aplikasi konsol, instal ekstensi konfigurasi dan rahasia pengguna paket NuGet secara eksplisit.

Jika menggunakan PowerShell:

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

Menggunakan CLI .NET:

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

Setelah paket diinstal, inisialisasi proyek dan atur rahasia dengan cara yang sama seperti untuk aplikasi web. Contoh berikut menunjukkan aplikasi konsol yang mengambil nilai rahasia yang diatur dengan kunci "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"]);
    }
}

Sumber Daya Tambahan:

• Lihat masalah ini dan masalah ini untuk informasi tentang mengakses rahasia pengguna dari IIS.
• Konfigurasi di ASP.NET Core
• Penyedia konfigurasi Azure Key Vault di ASP.NET Core