Menerapkan HTTPS di ASP.NET Core
Oleh David Galvan dan Rick Anderson
artikel ini memperlihatkan cara:
- Memerlukan HTTPS untuk semua permintaan.
- Mengalihkan semua permintaan HTTP ke HTTPS.
Tidak ada API yang dapat mencegah klien mengirim data sensitif pada permintaan pertama.
Peringatan
Proyek API
Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:
- Tidak mendengarkan di HTTP.
- Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.
Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 8 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.
Proyek HSTS dan API
Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.
Pengalihan HTTP ke HTTPS menyebabkan ERR_INVALID_REDIRECT pada permintaan preflight CORS
Permintaan ke titik akhir menggunakan HTTP yang dialihkan ke HTTPS dengan UseHttpsRedirection gagal pada ERR_INVALID_REDIRECT permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya produksi ASP.NET aplikasi web Core menggunakan:
- Https Redirection Middleware (UseHttpsRedirection) untuk mengalihkan permintaan HTTP ke HTTPS.
- Middleware HSTS (UseHsts) untuk mengirim header HTTP Strict Transport Security Protocol (HSTS) ke klien.
Catatan
Aplikasi yang disebarkan dalam konfigurasi proksi terbalik memungkinkan proksi untuk menangani keamanan koneksi (HTTPS). Jika proksi juga menangani pengalihan HTTPS, tidak perlu menggunakan Middleware Pengalihan HTTPS. Jika server proksi juga menangani penulisan header HSTS (misalnya, dukungan HSTS asli di IIS 10.0 (1709) atau yang lebih baru), Middleware HSTS tidak diperlukan oleh aplikasi. Untuk informasi selengkapnya, lihat Menolak HTTPS/HSTS pada pembuatan proyek.
GunakanHttpsRedirection
Kode berikut memanggil UseHttpsRedirection dalam Program.cs file:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Kode yang disorot sebelumnya:
- Menggunakan default HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
- Menggunakan default HttpsRedirectionOptions.HttpsPort (null) kecuali ditimpa oleh
ASPNETCORE_HTTPS_PORTvariabel lingkungan atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penembolokan tautan dapat menyebabkan perilaku yang tidak stabil di lingkungan pengembangan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, lihat bagian Mengonfigurasi pengalihan permanen di produksi . Sebaiknya gunakan HSTS untuk memberi sinyal kepada klien bahwa hanya permintaan sumber daya aman yang harus dikirim ke aplikasi (hanya dalam produksi).
Konfigurasi port
Port harus tersedia untuk middleware untuk mengalihkan permintaan yang tidak aman ke HTTPS. Jika tidak ada port yang tersedia:
- Pengalihan ke HTTPS tidak terjadi.
- Middleware mencatat peringatan "Gagal menentukan port https untuk dialihkan."
Tentukan port HTTPS menggunakan salah satu pendekatan berikut:
Atur
https_portpengaturan host:Dalam konfigurasi host.
Dengan mengatur
ASPNETCORE_HTTPS_PORTvariabel lingkungan.Dengan menambahkan entri tingkat atas di
appsettings.json:{ "https_port": 443, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }
Tunjukkan port dengan skema aman menggunakan variabel lingkungan ASPNETCORE_URLS. Variabel lingkungan mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core mengatur URL HTTPS untuk
Properties/launchsettings.jsondan Kestrel IIS Express.launchsettings.jsonhanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penyebaran Kestrel tepi server atau server HTTP.sys yang menghadap publik. Hanya satu port HTTPS yang digunakan oleh aplikasi. Middleware menemukan port melalui IServerAddressesFeature.
Catatan
Saat aplikasi dijalankan dalam konfigurasi proksi terbalik, IServerAddressesFeature tidak tersedia. Atur port menggunakan salah satu pendekatan lain yang dijelaskan di bagian ini.
Penyebaran Edge
Saat Kestrel atau HTTP.sys digunakan sebagai server tepi yang menghadap publik, Kestrel atau HTTP.sys harus dikonfigurasi untuk mendengarkan di keduanya:
- Port aman tempat klien dialihkan (biasanya, 443 dalam produksi dan 5001 dalam pengembangan).
- Port yang tidak aman (biasanya, 80 dalam produksi dan 5000 dalam pengembangan).
Port yang tidak aman harus dapat diakses oleh klien agar aplikasi menerima permintaan yang tidak aman dan mengalihkan klien ke port aman.
Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir atau implementasi server web HTTP.sys di ASP.NET Core.
Skenario penyebaran
Firewall apa pun antara klien dan server juga harus membuka port komunikasi untuk lalu lintas.
Jika permintaan diteruskan dalam konfigurasi proksi terbalik, gunakan Middleware Header yang Diteruskan sebelum memanggil Middleware Pengalihan HTTPS. Middleware Header yang Diteruskan memperbarui Request.Scheme, menggunakan X-Forwarded-Proto header . Middleware memungkinkan URI pengalihan dan kebijakan keamanan lainnya berfungsi dengan benar. Saat Middleware Header yang Diteruskan tidak digunakan, aplikasi backend mungkin tidak menerima skema yang benar dan berakhir dalam perulangan pengalihan. Pesan kesalahan pengguna akhir umum adalah bahwa terlalu banyak pengalihan yang terjadi.
Saat menyebarkan ke Azure App Service, ikuti panduan dalam Tutorial: Mengikat sertifikat SSL kustom yang ada ke Azure Web Apps.
Opsi
Panggilan kode yang disorot AddHttpsRedirection berikut untuk mengonfigurasi opsi middleware:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
AddHttpsRedirection Panggilan hanya diperlukan untuk mengubah nilai HttpsPort atau RedirectStatusCode.
Kode yang disorot sebelumnya:
- HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang StatusCodes kelas untuk penugasan ke
RedirectStatusCode. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen dalam produksi
Middleware default untuk mengirim Status307TemporaryRedirect dengan semua pengalihan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, bungkus konfigurasi opsi middleware dalam pemeriksaan kondisional untuk lingkungan non-Pengembangan.
Saat mengonfigurasi layanan di Program.cs:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
if (!builder.Environment.IsDevelopment())
{
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status308PermanentRedirect;
options.HttpsPort = 443;
});
}
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Pendekatan alternatif Middleware Pengalihan HTTPS
Alternatif untuk menggunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) adalah menggunakan MIDDLEware Penulisan Ulang URL (AddRedirectToHttps). AddRedirectToHttps juga dapat mengatur kode status dan port saat pengalihan dijalankan. Untuk informasi selengkapnya, lihat URL Menulis Ulang Middleware.
Saat mengalihkan ke HTTPS tanpa persyaratan untuk aturan pengalihan tambahan, sebaiknya gunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) yang dijelaskan dalam artikel ini.
Http Strict Transport Security Protocol (HSTS)
Per OWASP, HTTP Strict Transport Security (HSTS) adalah peningkatan keamanan keikutsertaan yang ditentukan oleh aplikasi web melalui penggunaan header respons. Saat browser yang mendukung HSTS menerima header ini:
- Browser menyimpan konfigurasi untuk domain yang mencegah pengiriman komunikasi apa pun melalui HTTP. Browser memaksa semua komunikasi melalui HTTPS.
- Browser mencegah pengguna menggunakan sertifikat yang tidak tepercaya atau tidak valid. Browser menonaktifkan perintah yang memungkinkan pengguna untuk memercayai sertifikat tersebut untuk sementara waktu.
Karena HSTS diberlakukan oleh klien, HSTS memiliki beberapa batasan:
- Klien harus mendukung HSTS.
- HSTS memerlukan setidaknya satu permintaan HTTPS yang berhasil untuk menetapkan kebijakan HSTS.
- Aplikasi harus memeriksa setiap permintaan HTTP dan mengalihkan atau menolak permintaan HTTP.
ASP.NET Core mengimplementasikan HSTS dengan UseHsts metode ekstensi. Kode berikut memanggil UseHsts saat aplikasi tidak dalam mode pengembangan:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
UseHsts tidak disarankan dalam pengembangan karena pengaturan HSTS sangat dapat di-cache oleh browser. Secara default, UseHsts tidak termasuk alamat loopback lokal.
Untuk lingkungan produksi yang menerapkan HTTPS untuk pertama kalinya, atur awal HstsOptions.MaxAge ke nilai kecil menggunakan salah TimeSpan satu metode. Atur nilai dari jam ke tidak lebih dari satu hari jika Anda perlu mengembalikan infrastruktur HTTPS ke HTTP. Setelah Anda yakin dengan keberlanjutan konfigurasi HTTPS, tingkatkan nilai HSTS max-age ; nilai yang umum digunakan adalah satu tahun.
Kode yang disorot berikut:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
- Mengatur parameter
Strict-Transport-Securitypramuat header. Pramuat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk memuat situs HSTS sebelumnya pada penginstalan baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-ageparameterStrict-Transport-Securityheader menjadi 60 hari. Jika tidak diatur, default ke 30 hari. Untuk informasi selengkapnya, lihat arahan usia maks. example.comMenambahkan ke daftar host untuk dikecualikan.
UseHsts mengecualikan host loopback berikut:
localhost: Alamat loopback IPv4.127.0.0.1: Alamat loopback IPv4.[::1]: Alamat loopback IPv6.
Menolak HTTPS/HSTS pada pembuatan proyek
Dalam beberapa skenario layanan backend di mana keamanan koneksi ditangani di tepi jaringan yang menghadap publik, mengonfigurasi keamanan koneksi di setiap simpul tidak diperlukan. Aplikasi web yang dihasilkan dari templat di Visual Studio atau dari perintah baru dotnet mengaktifkan pengalihan HTTPS dan HSTS. Untuk penyebaran yang tidak memerlukan skenario ini, Anda dapat menolak HTTPS/HSTS saat aplikasi dibuat dari templat.
Untuk menolak HTTPS/HSTS:
Hapus centang pada kotak centang Konfigurasi untuk HTTPS .
Percayai sertifikat pengembangan HTTPS Inti ASP.NET
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman eksekusi pertama. Misalnya, dotnet --info menghasilkan variasi output berikut:
ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.
Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal. Sertifikat telah diinstal, tetapi tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah satu kali untuk menjalankan dotnet dev-certs alat:
dotnet dev-certs https --trust
Perintah berikut memberikan bantuan pada dotnet dev-certs alat:
dotnet dev-certs https --help
Peringatan
Jangan membuat sertifikat pengembangan di lingkungan yang akan didistribusikan ulang, seperti gambar kontainer atau komputer virtual. Melakukannya dapat menyebabkan spoofing dan elevasi hak istimewa. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE variabel lingkungan ke false sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewati pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman eksekusi pertama CLI.
Cara menyiapkan sertifikat pengembang untuk Docker
Lihat masalah GitHub ini.
Pertimbangan khusus Linux
Distro Linux berbeda secara substansial dalam cara mereka menandai sertifikat sebagai tepercaya. Meskipun dotnet dev-certs diharapkan dapat diterapkan secara luas, ini hanya didukung secara resmi pada Ubuntu dan Fedora dan secara khusus bertujuan untuk memastikan kepercayaan pada browser berbasis Firefox dan Chromium (Edge, Chrome, dan Chromium).
Dependensi
Untuk membangun kepercayaan OpenSSL, openssl alat harus berada di jalur.
Untuk membangun kepercayaan browser (misalnya di Edge atau Firefox), certutil alat harus berada di jalur.
Kepercayaan OpenSSL
Ketika sertifikat pengembangan ASP.NET Core tepercaya, sertifikat tersebut diekspor ke folder di direktori pengguna home saat ini. Agar OpenSSL (dan klien yang menggunakannya) mengambil folder ini, Anda perlu mengatur SSL_CERT_DIR variabel lingkungan. Anda dapat melakukan ini dalam satu sesi dengan menjalankan perintah seperti export SSL_CERT_DIR=$HOME/.aspnet/dev-certs/trust:/usr/lib/ssl/certs (nilai yang tepat akan berada dalam output ketika --verbose diteruskan) atau dengan menambahkan file konfigurasi Anda (khusus distro dan shell) (misalnya .profile).
Ini diperlukan untuk membuat alat seperti curl mempercayai sertifikat pengembangan. Atau, atau, Anda dapat meneruskan -CAfile atau -CApath ke setiap pemanggilan individu curl .
Perhatikan bahwa ini memerlukan 1.1.1h atau yang lebih baru atau 3.0.0 atau yang lebih baru, tergantung pada versi utama mana yang Anda gunakan.
Jika kepercayaan OpenSSL masuk ke status buruk (misalnya jika dotnet dev-certs https --clean gagal menghapusnya), sering dimungkinkan untuk mengatur hal-hal yang tepat menggunakan alat.c_rehash
Timpa
Jika Anda menggunakan browser lain dengan penyimpanan Network Security Services (NSS) sendiri, Anda dapat menggunakan DOTNET_DEV_CERTS_NSSDB_PATHS variabel lingkungan untuk menentukan daftar direktori NSS yang dibatasi titik dua (misalnya, direktori yang berisi cert9.db) untuk menambahkan sertifikat pengembangan.
Jika Anda menyimpan sertifikat yang Anda inginkan untuk dipercaya OpenSSL dalam direktori tertentu, Anda dapat menggunakan DOTNET_DEV_CERTS_OPENSSL_CERTIFICATE_DIRECTORY variabel lingkungan untuk menunjukkan di mana itu berada.
Peringatan
Jika Anda mengatur salah satu variabel ini, penting bahwa variabel tersebut diatur ke nilai yang sama setiap kali kepercayaan diperbarui. Jika berubah, alat ini tidak akan tahu tentang sertifikat di lokasi sebelumnya (misalnya untuk membersihkannya).
Menggunakan sudo
Seperti pada platform lain, sertifikat pengembangan disimpan dan dipercaya secara terpisah untuk setiap pengguna. Akibatnya, jika Anda menjalankan dotnet dev-certs sebagai pengguna yang berbeda (misalnya dengan menggunakan sudo), pengguna tersebut (misalnya root) yang akan mempercayai sertifikat pengembangan.
Percayai sertifikat HTTPS di Linux dengan linux-dev-certs
linux-dev-certs adalah alat global .NET sumber terbuka yang didukung komunitas yang menyediakan cara mudah untuk membuat dan memercayai sertifikat pengembang di Linux. Alat ini tidak dipertahankan atau didukung oleh Microsoft.
Perintah berikut menginstal alat dan membuat sertifikat pengembang tepercaya:
dotnet tool update -g linux-dev-certs
dotnet linux-dev-certs install
Untuk informasi selengkapnya atau untuk melaporkan masalah, lihat repositori GitHub linux-dev-certs.
Memecahkan masalah sertifikat seperti sertifikat tidak tepercaya
Bagian ini memberikan bantuan ketika sertifikat pengembangan ASP.NET Core HTTPS telah diinstal dan dipercaya, tetapi Anda masih memiliki peringatan browser bahwa sertifikat tidak tepercaya. Sertifikat pengembangan HTTPS Inti ASP.NET digunakan oleh Kestrel.
Untuk memperbaiki sertifikat IIS Express, lihat masalah Stackoverflow ini.
Semua platform - sertifikat tidak tepercaya
Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
dotnet dev-certs https --clean Fails
Perintah sebelumnya menyelesaikan sebagian besar masalah kepercayaan browser. Jika browser masih tidak mempercayai sertifikat, ikuti saran khusus platform yang mengikutinya.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan solusinya. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpanan sertifikat. Harus
localhostada sertifikat dengan nama yang mudah diingatASP.NET Core HTTPS development certificatebaik di bawahCurrent User > Personal > CertificatesdanCurrent User > Trusted root certification authorities > Certificates - Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi akar Pribadi dan Tepercaya. Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah simbol berisi
+simbol pada ikon untuk menunjukkan bahwa simbol tersebut tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
Lihat Kesalahan HTTPS menggunakan IIS Express (dotnet/AspNetCore #16892) untuk memecahkan masalah sertifikat dengan Visual Studio.
Sertifikat Linux tidak tepercaya
Periksa apakah sertifikat yang dikonfigurasi untuk kepercayaan adalah sertifikat pengembang HTTPS pengguna yang akan digunakan oleh Kestrel server.
Periksa sertifikat pengembang Kestrel HTTPS default pengguna saat ini di lokasi berikut:
ls -la ~/.dotnet/corefx/cryptography/x509stores/my
File sertifikat pengembang Kestrel HTTPS adalah thumbprint SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa thumbprint kecocokan sertifikat yang diekspor dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, sertifikat tersebut bisa menjadi salah satu hal berikut:
- Sertifikat lama.
- Sertifikat pengembang yang diekspor untuk pengguna root. Untuk kasus ini, ekspor sertifikat.
Sertifikat pengguna akar dapat diperiksa di:
ls -la /root/.dotnet/corefx/cryptography/x509stores/my
Sertifikat SSL IIS Express yang digunakan dengan Visual Studio
Untuk memperbaiki masalah dengan sertifikat IIS Express, pilih Perbaiki dari alat penginstal Visual Studio. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Kebijakan grup mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya
Dalam beberapa kasus, kebijakan grup dapat mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Catatan
Jika Anda menggunakan .NET 9 SDK atau yang lebih baru, lihat prosedur Linux yang diperbarui di versi .NET 9 dari artikel ini.
Peringatan
Proyek API
Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:
- Tidak mendengarkan di HTTP.
- Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.
Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 8 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.
Proyek HSTS dan API
Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.
Pengalihan HTTP ke HTTPS menyebabkan ERR_INVALID_REDIRECT pada permintaan preflight CORS
Permintaan ke titik akhir menggunakan HTTP yang dialihkan ke HTTPS dengan UseHttpsRedirection gagal pada ERR_INVALID_REDIRECT permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya produksi ASP.NET aplikasi web Core menggunakan:
- Https Redirection Middleware (UseHttpsRedirection) untuk mengalihkan permintaan HTTP ke HTTPS.
- Middleware HSTS (UseHsts) untuk mengirim header HTTP Strict Transport Security Protocol (HSTS) ke klien.
Catatan
Aplikasi yang disebarkan dalam konfigurasi proksi terbalik memungkinkan proksi untuk menangani keamanan koneksi (HTTPS). Jika proksi juga menangani pengalihan HTTPS, tidak perlu menggunakan Middleware Pengalihan HTTPS. Jika server proksi juga menangani penulisan header HSTS (misalnya, dukungan HSTS asli di IIS 10.0 (1709) atau yang lebih baru), Middleware HSTS tidak diperlukan oleh aplikasi. Untuk informasi selengkapnya, lihat Menolak HTTPS/HSTS pada pembuatan proyek.
GunakanHttpsRedirection
Kode berikut memanggil UseHttpsRedirection dalam Program.cs file:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Kode yang disorot sebelumnya:
- Menggunakan default HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
- Menggunakan default HttpsRedirectionOptions.HttpsPort (null) kecuali ditimpa oleh
ASPNETCORE_HTTPS_PORTvariabel lingkungan atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penembolokan tautan dapat menyebabkan perilaku yang tidak stabil di lingkungan pengembangan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, lihat bagian Mengonfigurasi pengalihan permanen di produksi . Sebaiknya gunakan HSTS untuk memberi sinyal kepada klien bahwa hanya permintaan sumber daya aman yang harus dikirim ke aplikasi (hanya dalam produksi).
Konfigurasi port
Port harus tersedia untuk middleware untuk mengalihkan permintaan yang tidak aman ke HTTPS. Jika tidak ada port yang tersedia:
- Pengalihan ke HTTPS tidak terjadi.
- Middleware mencatat peringatan "Gagal menentukan port https untuk dialihkan."
Tentukan port HTTPS menggunakan salah satu pendekatan berikut:
Atur
https_portpengaturan host:Dalam konfigurasi host.
Dengan mengatur
ASPNETCORE_HTTPS_PORTvariabel lingkungan.Dengan menambahkan entri tingkat atas di
appsettings.json:{ "https_port": 443, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }
Tunjukkan port dengan skema aman menggunakan variabel lingkungan ASPNETCORE_URLS. Variabel lingkungan mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core mengatur URL HTTPS untuk
Properties/launchsettings.jsondan Kestrel IIS Express.launchsettings.jsonhanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penyebaran Kestrel tepi server atau server HTTP.sys yang menghadap publik. Hanya satu port HTTPS yang digunakan oleh aplikasi. Middleware menemukan port melalui IServerAddressesFeature.
Catatan
Saat aplikasi dijalankan dalam konfigurasi proksi terbalik, IServerAddressesFeature tidak tersedia. Atur port menggunakan salah satu pendekatan lain yang dijelaskan di bagian ini.
Penyebaran Edge
Saat Kestrel atau HTTP.sys digunakan sebagai server tepi yang menghadap publik, Kestrel atau HTTP.sys harus dikonfigurasi untuk mendengarkan di keduanya:
- Port aman tempat klien dialihkan (biasanya, 443 dalam produksi dan 5001 dalam pengembangan).
- Port yang tidak aman (biasanya, 80 dalam produksi dan 5000 dalam pengembangan).
Port yang tidak aman harus dapat diakses oleh klien agar aplikasi menerima permintaan yang tidak aman dan mengalihkan klien ke port aman.
Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir atau implementasi server web HTTP.sys di ASP.NET Core.
Skenario penyebaran
Firewall apa pun antara klien dan server juga harus membuka port komunikasi untuk lalu lintas.
Jika permintaan diteruskan dalam konfigurasi proksi terbalik, gunakan Middleware Header yang Diteruskan sebelum memanggil Middleware Pengalihan HTTPS. Middleware Header yang Diteruskan memperbarui Request.Scheme, menggunakan X-Forwarded-Proto header . Middleware memungkinkan URI pengalihan dan kebijakan keamanan lainnya berfungsi dengan benar. Saat Middleware Header yang Diteruskan tidak digunakan, aplikasi backend mungkin tidak menerima skema yang benar dan berakhir dalam perulangan pengalihan. Pesan kesalahan pengguna akhir umum adalah bahwa terlalu banyak pengalihan yang terjadi.
Saat menyebarkan ke Azure App Service, ikuti panduan dalam Tutorial: Mengikat sertifikat SSL kustom yang ada ke Azure Web Apps.
Opsi
Panggilan kode yang disorot AddHttpsRedirection berikut untuk mengonfigurasi opsi middleware:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
AddHttpsRedirection Panggilan hanya diperlukan untuk mengubah nilai HttpsPort atau RedirectStatusCode.
Kode yang disorot sebelumnya:
- HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang StatusCodes kelas untuk penugasan ke
RedirectStatusCode. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen dalam produksi
Middleware default untuk mengirim Status307TemporaryRedirect dengan semua pengalihan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, bungkus konfigurasi opsi middleware dalam pemeriksaan kondisional untuk lingkungan non-Pengembangan.
Saat mengonfigurasi layanan di Program.cs:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
if (!builder.Environment.IsDevelopment())
{
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status308PermanentRedirect;
options.HttpsPort = 443;
});
}
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Pendekatan alternatif Middleware Pengalihan HTTPS
Alternatif untuk menggunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) adalah menggunakan MIDDLEware Penulisan Ulang URL (AddRedirectToHttps). AddRedirectToHttps juga dapat mengatur kode status dan port saat pengalihan dijalankan. Untuk informasi selengkapnya, lihat URL Menulis Ulang Middleware.
Saat mengalihkan ke HTTPS tanpa persyaratan untuk aturan pengalihan tambahan, sebaiknya gunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) yang dijelaskan dalam artikel ini.
Http Strict Transport Security Protocol (HSTS)
Per OWASP, HTTP Strict Transport Security (HSTS) adalah peningkatan keamanan keikutsertaan yang ditentukan oleh aplikasi web melalui penggunaan header respons. Saat browser yang mendukung HSTS menerima header ini:
- Browser menyimpan konfigurasi untuk domain yang mencegah pengiriman komunikasi apa pun melalui HTTP. Browser memaksa semua komunikasi melalui HTTPS.
- Browser mencegah pengguna menggunakan sertifikat yang tidak tepercaya atau tidak valid. Browser menonaktifkan perintah yang memungkinkan pengguna untuk memercayai sertifikat tersebut untuk sementara waktu.
Karena HSTS diberlakukan oleh klien, HSTS memiliki beberapa batasan:
- Klien harus mendukung HSTS.
- HSTS memerlukan setidaknya satu permintaan HTTPS yang berhasil untuk menetapkan kebijakan HSTS.
- Aplikasi harus memeriksa setiap permintaan HTTP dan mengalihkan atau menolak permintaan HTTP.
ASP.NET Core mengimplementasikan HSTS dengan UseHsts metode ekstensi. Kode berikut memanggil UseHsts saat aplikasi tidak dalam mode pengembangan:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
UseHsts tidak disarankan dalam pengembangan karena pengaturan HSTS sangat dapat di-cache oleh browser. Secara default, UseHsts tidak termasuk alamat loopback lokal.
Untuk lingkungan produksi yang menerapkan HTTPS untuk pertama kalinya, atur awal HstsOptions.MaxAge ke nilai kecil menggunakan salah TimeSpan satu metode. Atur nilai dari jam ke tidak lebih dari satu hari jika Anda perlu mengembalikan infrastruktur HTTPS ke HTTP. Setelah Anda yakin dengan keberlanjutan konfigurasi HTTPS, tingkatkan nilai HSTS max-age ; nilai yang umum digunakan adalah satu tahun.
Kode yang disorot berikut:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
- Mengatur parameter
Strict-Transport-Securitypramuat header. Pramuat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk memuat situs HSTS sebelumnya pada penginstalan baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-ageparameterStrict-Transport-Securityheader menjadi 60 hari. Jika tidak diatur, default ke 30 hari. Untuk informasi selengkapnya, lihat arahan usia maks. example.comMenambahkan ke daftar host untuk dikecualikan.
UseHsts mengecualikan host loopback berikut:
localhost: Alamat loopback IPv4.127.0.0.1: Alamat loopback IPv4.[::1]: Alamat loopback IPv6.
Menolak HTTPS/HSTS pada pembuatan proyek
Dalam beberapa skenario layanan backend di mana keamanan koneksi ditangani di tepi jaringan yang menghadap publik, mengonfigurasi keamanan koneksi di setiap simpul tidak diperlukan. Aplikasi web yang dihasilkan dari templat di Visual Studio atau dari perintah baru dotnet mengaktifkan pengalihan HTTPS dan HSTS. Untuk penyebaran yang tidak memerlukan skenario ini, Anda dapat menolak HTTPS/HSTS saat aplikasi dibuat dari templat.
Untuk menolak HTTPS/HSTS:
Hapus centang pada kotak centang Konfigurasi untuk HTTPS .
Percayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS
Untuk browser Firefox, lihat bagian berikutnya.
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman eksekusi pertama. Misalnya, dotnet --info menghasilkan variasi output berikut:
ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.
Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal. Sertifikat telah diinstal, tetapi tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah satu kali untuk menjalankan dotnet dev-certs alat:
dotnet dev-certs https --trust
Perintah berikut memberikan bantuan pada dotnet dev-certs alat:
dotnet dev-certs https --help
Peringatan
Jangan membuat sertifikat pengembangan di lingkungan yang akan didistribusikan ulang, seperti gambar kontainer atau komputer virtual. Melakukannya dapat menyebabkan spoofing dan elevasi hak istimewa. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE variabel lingkungan ke false sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewati pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman eksekusi pertama CLI.
Percayai sertifikat HTTPS dengan Firefox untuk mencegah kesalahan SEC_ERROR_INADEQUATE_KEY_USAGE
Browser Firefox menggunakan penyimpanan sertifikatnya sendiri, dan karenanya tidak mempercayai sertifikat IIS Express atau Kestrel pengembang.
Ada dua pendekatan untuk mempercayai sertifikat HTTPS dengan Firefox, membuat file kebijakan atau mengonfigurasi dengan browser FireFox. Mengonfigurasi dengan browser membuat file kebijakan, sehingga dua pendekatan tersebut setara.
Membuat file kebijakan untuk mempercayai sertifikat HTTPS dengan Firefox
Buat file kebijakan (policies.json) di:
- Windows:
%PROGRAMFILES%\Mozilla Firefox\distribution\ - MacOS:
Firefox.app/Contents/Resources/distribution - Linux: Lihat Mempercayai sertifikat dengan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
File kebijakan sebelumnya membuat sertifikat kepercayaan Firefox dari sertifikat tepercaya di penyimpanan sertifikat Windows. Bagian berikutnya menyediakan pendekatan alternatif untuk membuat file kebijakan sebelumnya dengan menggunakan browser Firefox.
Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox
Atur security.enterprise_roots.enabled = true menggunakan instruksi berikut:
- Masukkan
about:configdi browser FireFox. - Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
- Pilih Perlihatkan Semua
- Mengeset
security.enterprise_roots.enabled=true - Keluar dan mulai ulang Firefox
Untuk informasi selengkapnya, lihat Menyiapkan Otoritas Sertifikat (CA) di Firefox dan file mozilla/policy-templates/README.
Cara menyiapkan sertifikat pengembang untuk Docker
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS di Linux
Membangun kepercayaan adalah distribusi dan browser spesifik. Bagian berikut memberikan instruksi untuk beberapa distribusi populer dan browser Chromium (Edge dan Chrome) dan untuk Firefox.
Ubuntu mempercayai sertifikat untuk komunikasi layanan-ke-layanan
Instruksi berikut tidak berfungsi untuk beberapa versi Ubuntu, seperti 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.
Jalankan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM sudo update-ca-certificates
Perintah sebelumnya:
- Pastikan sertifikat pengembang pengguna saat ini dibuat.
- Mengekspor sertifikat dengan izin yang ditingkatkan yang diperlukan untuk
ca-certificatesfolder, menggunakan lingkungan pengguna saat ini. - Menghapus
-Ebendera mengekspor sertifikat pengguna akar, menghasilkannya jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudodan-Etidak diperlukan.
Jalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Percayai sertifikat HTTPS di Linux menggunakan Edge atau Chrome
Untuk browser kromium di Linux:
libnss3-toolsInstal untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdbfolder ada pada komputer.Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Jalankan perintah berikut:
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n localhost -i /usr/local/share/ca-certificates/aspnet/https.crtKeluar dan mulai ulang browser.
Percayai sertifikat dengan Firefox di Linux
Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Buat file JSON di
/usr/lib/firefox/distribution/policies.jsondengan perintah berikut:
cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
"policies": {
"Certificates": {
"Install": [
"/usr/local/share/ca-certificates/aspnet/https.crt"
]
}
}
}
EOF
Catatan: Ubuntu 21.10 Firefox hadir sebagai paket snap dan folder penginstalan adalah /snap/firefox/current/usr/lib/firefox.
Lihat Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox di artikel ini untuk cara alternatif mengonfigurasi file kebijakan menggunakan browser.
Percayai sertifikat dengan Fedora 34
Lihat:
- Komentar GitHub ini
- Fedora: Menggunakan Sertifikat Sistem Bersama
- Siapkan lingkungan pengembangan .NET di Fedora.
Percayai sertifikat dengan distro lain
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS dari Subsistem Windows untuk Linux
Instruksi berikut tidak berfungsi untuk beberapa distribusi Linux, seperti Ubuntu 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Subsistem Windows untuk Linux (WSL) menghasilkan sertifikat pengembangan yang ditandatangani sendiri HTTPS, yang secara default tidak dipercaya di Windows. Cara term mudah agar Windows mempercayai sertifikat WSL, adalah dengan mengonfigurasi WSL untuk menggunakan sertifikat yang sama dengan Windows:
Di Windows, ekspor sertifikat pengembang ke file:
dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trustDi mana
$CREDENTIAL_PLACEHOLDER$kata sandi.Di jendela WSL, impor sertifikat yang diekspor pada instans WSL:
dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
Pendekatan sebelumnya adalah operasi satu kali per sertifikat dan per distribusi WSL. Lebih mudah daripada mengekspor sertifikat berulang kali. Jika Anda memperbarui atau meregenerasi sertifikat pada windows, Anda mungkin perlu menjalankan perintah sebelumnya lagi.
Memecahkan masalah sertifikat seperti sertifikat tidak tepercaya
Bagian ini memberikan bantuan ketika sertifikat pengembangan ASP.NET Core HTTPS telah diinstal dan dipercaya, tetapi Anda masih memiliki peringatan browser bahwa sertifikat tidak tepercaya. Sertifikat pengembangan HTTPS Inti ASP.NET digunakan oleh Kestrel.
Untuk memperbaiki sertifikat IIS Express, lihat masalah Stackoverflow ini.
Semua platform - sertifikat tidak tepercaya
Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
dotnet dev-certs https --clean Fails
Perintah sebelumnya menyelesaikan sebagian besar masalah kepercayaan browser. Jika browser masih tidak mempercayai sertifikat, ikuti saran khusus platform yang mengikutinya.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan solusinya. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpanan sertifikat. Harus
localhostada sertifikat dengan nama yang mudah diingatASP.NET Core HTTPS development certificatebaik di bawahCurrent User > Personal > CertificatesdanCurrent User > Trusted root certification authorities > Certificates - Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi akar Pribadi dan Tepercaya. Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah simbol berisi
+simbol pada ikon untuk menunjukkan bahwa simbol tersebut tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
Lihat Kesalahan HTTPS menggunakan IIS Express (dotnet/AspNetCore #16892) untuk memecahkan masalah sertifikat dengan Visual Studio.
Sertifikat Linux tidak tepercaya
Periksa apakah sertifikat yang dikonfigurasi untuk kepercayaan adalah sertifikat pengembang HTTPS pengguna yang akan digunakan oleh Kestrel server.
Periksa sertifikat pengembang Kestrel HTTPS default pengguna saat ini di lokasi berikut:
ls -la ~/.dotnet/corefx/cryptography/x509stores/my
File sertifikat pengembang Kestrel HTTPS adalah thumbprint SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa thumbprint kecocokan sertifikat yang diekspor dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, sertifikat tersebut bisa menjadi salah satu hal berikut:
- Sertifikat lama.
- Sertifikat pengembang yang diekspor untuk pengguna root. Untuk kasus ini, ekspor sertifikat.
Sertifikat pengguna akar dapat diperiksa di:
ls -la /root/.dotnet/corefx/cryptography/x509stores/my
Sertifikat SSL IIS Express yang digunakan dengan Visual Studio
Untuk memperbaiki masalah dengan sertifikat IIS Express, pilih Perbaiki dari alat penginstal Visual Studio. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Kebijakan grup mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya
Dalam beberapa kasus, kebijakan grup dapat mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Peringatan
Proyek API
Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:
- Tidak mendengarkan di HTTP.
- Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.
Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 5 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.
Proyek HSTS dan API
Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.
Memerlukan HTTPS
Sebaiknya produksi ASP.NET aplikasi web Core menggunakan:
- Https Redirection Middleware (UseHttpsRedirection) untuk mengalihkan permintaan HTTP ke HTTPS.
- Middleware HSTS (UseHsts) untuk mengirim header HTTP Strict Transport Security Protocol (HSTS) ke klien.
Catatan
Aplikasi yang disebarkan dalam konfigurasi proksi terbalik memungkinkan proksi untuk menangani keamanan koneksi (HTTPS). Jika proksi juga menangani pengalihan HTTPS, tidak perlu menggunakan Middleware Pengalihan HTTPS. Jika server proksi juga menangani penulisan header HSTS (misalnya, dukungan HSTS asli di IIS 10.0 (1709) atau yang lebih baru), Middleware HSTS tidak diperlukan oleh aplikasi. Untuk informasi selengkapnya, lihat Menolak HTTPS/HSTS pada pembuatan proyek.
GunakanHttpsRedirection
Kode berikut memanggil UseHttpsRedirection di Startup kelas :
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
Kode yang disorot sebelumnya:
- Menggunakan default HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
- Menggunakan default HttpsRedirectionOptions.HttpsPort (null) kecuali ditimpa oleh
ASPNETCORE_HTTPS_PORTvariabel lingkungan atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penembolokan tautan dapat menyebabkan perilaku yang tidak stabil di lingkungan pengembangan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, lihat bagian Mengonfigurasi pengalihan permanen di produksi . Sebaiknya gunakan HSTS untuk memberi sinyal kepada klien bahwa hanya permintaan sumber daya aman yang harus dikirim ke aplikasi (hanya dalam produksi).
Konfigurasi port
Port harus tersedia untuk middleware untuk mengalihkan permintaan yang tidak aman ke HTTPS. Jika tidak ada port yang tersedia:
- Pengalihan ke HTTPS tidak terjadi.
- Middleware mencatat peringatan "Gagal menentukan port https untuk dialihkan."
Tentukan port HTTPS menggunakan salah satu pendekatan berikut:
Atur
https_portpengaturan host:Dalam konfigurasi host.
Dengan mengatur
ASPNETCORE_HTTPS_PORTvariabel lingkungan.Dengan menambahkan entri tingkat atas di
appsettings.json:{ "https_port": 443, "Logging": { "LogLevel": { "Default": "Information", "Microsoft": "Warning", "Microsoft.Hosting.Lifetime": "Information" } }, "AllowedHosts": "*" }
Tunjukkan port dengan skema aman menggunakan variabel lingkungan ASPNETCORE_URLS. Variabel lingkungan mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Dalam pengembangan, atur URL HTTPS di
launchsettings.json. Aktifkan HTTPS saat IIS Express digunakan.Konfigurasikan titik akhir URL HTTPS untuk penyebaran Kestrel tepi server atau server HTTP.sys yang menghadap publik. Hanya satu port HTTPS yang digunakan oleh aplikasi. Middleware menemukan port melalui IServerAddressesFeature.
Catatan
Saat aplikasi dijalankan dalam konfigurasi proksi terbalik, IServerAddressesFeature tidak tersedia. Atur port menggunakan salah satu pendekatan lain yang dijelaskan di bagian ini.
Penyebaran Edge
Ketika Kestrel atau HTTP.sys digunakan sebagai server tepi yang menghadap publik, Kestrel atau HTTP.sys harus dikonfigurasi untuk mendengarkan di keduanya:
- Port aman tempat klien dialihkan (biasanya, 443 dalam produksi dan 5001 dalam pengembangan).
- Port yang tidak aman (biasanya, 80 dalam produksi dan 5000 dalam pengembangan).
Port yang tidak aman harus dapat diakses oleh klien agar aplikasi menerima permintaan yang tidak aman dan mengalihkan klien ke port aman.
Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir atau implementasi server web HTTP.sys di ASP.NET Core.
Skenario penyebaran
Firewall apa pun antara klien dan server juga harus membuka port komunikasi untuk lalu lintas.
Jika permintaan diteruskan dalam konfigurasi proksi terbalik, gunakan Middleware Header yang Diteruskan sebelum memanggil Middleware Pengalihan HTTPS. Middleware Header yang Diteruskan memperbarui Request.Scheme, menggunakan X-Forwarded-Proto header . Middleware memungkinkan URI pengalihan dan kebijakan keamanan lainnya berfungsi dengan benar. Saat Middleware Header yang Diteruskan tidak digunakan, aplikasi backend mungkin tidak menerima skema yang benar dan berakhir dalam perulangan pengalihan. Pesan kesalahan pengguna akhir umum adalah bahwa terlalu banyak pengalihan yang terjadi.
Saat menyebarkan ke Azure App Service, ikuti panduan dalam Tutorial: Mengikat sertifikat SSL kustom yang ada ke Azure Web Apps.
Opsi
Panggilan kode yang disorot AddHttpsRedirection berikut untuk mengonfigurasi opsi middleware:
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = (int) HttpStatusCode.TemporaryRedirect;
options.HttpsPort = 5001;
});
}
AddHttpsRedirection Panggilan hanya diperlukan untuk mengubah nilai HttpsPort atau RedirectStatusCode.
Kode yang disorot sebelumnya:
- HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang StatusCodes kelas untuk penugasan ke
RedirectStatusCode. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen dalam produksi
Middleware default untuk mengirim Status307TemporaryRedirect dengan semua pengalihan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, bungkus konfigurasi opsi middleware dalam pemeriksaan kondisional untuk lingkungan non-Pengembangan.
Saat mengonfigurasi layanan di Startup.cs:
public void ConfigureServices(IServiceCollection services)
{
// IWebHostEnvironment (stored in _env) is injected into the Startup class.
if (!_env.IsDevelopment())
{
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = (int) HttpStatusCode.PermanentRedirect;
options.HttpsPort = 443;
});
}
}
Pendekatan alternatif Middleware Pengalihan HTTPS
Alternatif untuk menggunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) adalah menggunakan MIDDLEware Penulisan Ulang URL (AddRedirectToHttps). AddRedirectToHttps juga dapat mengatur kode status dan port saat pengalihan dijalankan. Untuk informasi selengkapnya, lihat URL Menulis Ulang Middleware.
Saat mengalihkan ke HTTPS tanpa persyaratan untuk aturan pengalihan tambahan, sebaiknya gunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) yang dijelaskan dalam artikel ini.
Http Strict Transport Security Protocol (HSTS)
Per OWASP, HTTP Strict Transport Security (HSTS) adalah peningkatan keamanan keikutsertaan yang ditentukan oleh aplikasi web melalui penggunaan header respons. Saat browser yang mendukung HSTS menerima header ini:
- Browser menyimpan konfigurasi untuk domain yang mencegah pengiriman komunikasi apa pun melalui HTTP. Browser memaksa semua komunikasi melalui HTTPS.
- Browser mencegah pengguna menggunakan sertifikat yang tidak tepercaya atau tidak valid. Browser menonaktifkan perintah yang memungkinkan pengguna untuk memercayai sertifikat tersebut untuk sementara waktu.
Karena HSTS diberlakukan oleh klien, HSTS memiliki beberapa batasan:
- Klien harus mendukung HSTS.
- HSTS memerlukan setidaknya satu permintaan HTTPS yang berhasil untuk menetapkan kebijakan HSTS.
- Aplikasi harus memeriksa setiap permintaan HTTP dan mengalihkan atau menolak permintaan HTTP.
ASP.NET Core mengimplementasikan HSTS dengan UseHsts metode ekstensi. Kode berikut memanggil UseHsts saat aplikasi tidak dalam mode pengembangan:
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapRazorPages();
});
}
UseHsts tidak disarankan dalam pengembangan karena pengaturan HSTS sangat dapat di-cache oleh browser. Secara default, UseHsts tidak termasuk alamat loopback lokal.
Untuk lingkungan produksi yang menerapkan HTTPS untuk pertama kalinya, atur awal HstsOptions.MaxAge ke nilai kecil menggunakan salah TimeSpan satu metode. Atur nilai dari jam ke tidak lebih dari satu hari jika Anda perlu mengembalikan infrastruktur HTTPS ke HTTP. Setelah Anda yakin dengan keberlanjutan konfigurasi HTTPS, tingkatkan nilai HSTS max-age ; nilai yang umum digunakan adalah satu tahun.
Kode berikut:
public void ConfigureServices(IServiceCollection services)
{
services.AddRazorPages();
services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = (int) HttpStatusCode.TemporaryRedirect;
options.HttpsPort = 5001;
});
}
- Mengatur parameter
Strict-Transport-Securitypramuat header. Pramuat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk memuat situs HSTS sebelumnya pada penginstalan baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-ageparameterStrict-Transport-Securityheader menjadi 60 hari. Jika tidak diatur, default ke 30 hari. Untuk informasi selengkapnya, lihat arahan usia maks. example.comMenambahkan ke daftar host untuk dikecualikan.
UseHsts mengecualikan host loopback berikut:
localhost: Alamat loopback IPv4.127.0.0.1: Alamat loopback IPv4.[::1]: Alamat loopback IPv6.
Menolak HTTPS/HSTS pada pembuatan proyek
Dalam beberapa skenario layanan backend di mana keamanan koneksi ditangani di tepi jaringan yang menghadap publik, mengonfigurasi keamanan koneksi di setiap simpul tidak diperlukan. Aplikasi web yang dihasilkan dari templat di Visual Studio atau dari perintah baru dotnet mengaktifkan pengalihan HTTPS dan HSTS. Untuk penyebaran yang tidak memerlukan skenario ini, Anda dapat menolak HTTPS/HSTS saat aplikasi dibuat dari templat.
Untuk menolak HTTPS/HSTS:
Hapus centang pada kotak centang Konfigurasi untuk HTTPS .
Percayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS
Untuk browser Firefox, lihat bagian berikutnya.
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman eksekusi pertama. Misalnya, menjalankan dotnet new webapp untuk pertama kalinya menghasilkan variasi output berikut:
Installed an ASP.NET Core HTTPS development certificate.
To trust the certificate, run 'dotnet dev-certs https --trust'
Learn about HTTPS: https://aka.ms/dotnet-https
Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal. Sertifikat telah diinstal, tetapi tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah satu kali untuk menjalankan dotnet dev-certs alat:
dotnet dev-certs https --trust
Perintah berikut memberikan bantuan pada dotnet dev-certs alat:
dotnet dev-certs https --help
Peringatan
Jangan membuat sertifikat pengembangan di lingkungan yang akan didistribusikan ulang, seperti gambar kontainer atau komputer virtual. Melakukannya dapat menyebabkan spoofing dan elevasi hak istimewa. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE variabel lingkungan ke false sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewati pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman eksekusi pertama CLI.
Percayai sertifikat HTTPS dengan Firefox untuk mencegah kesalahan SEC_ERROR_INADEQUATE_KEY_USAGE
Browser Firefox menggunakan penyimpanan sertifikatnya sendiri, dan karenanya tidak mempercayai sertifikat IIS Express atau Kestrel pengembang.
Ada dua pendekatan untuk mempercayai sertifikat HTTPS dengan Firefox, membuat file kebijakan atau mengonfigurasi dengan browser FireFox. Mengonfigurasi dengan browser membuat file kebijakan, sehingga dua pendekatan tersebut setara.
Membuat file kebijakan untuk mempercayai sertifikat HTTPS dengan Firefox
Buat file kebijakan (policies.json) di:
- Windows:
%PROGRAMFILES%\Mozilla Firefox\distribution\ - MacOS:
Firefox.app/Contents/Resources/distribution - Linux: Lihat Mempercayai sertifikat dengan Firefox di Linux nanti di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
File kebijakan sebelumnya membuat sertifikat kepercayaan Firefox dari sertifikat tepercaya di penyimpanan sertifikat Windows. Bagian berikutnya menyediakan pendekatan alternatif untuk membuat file kebijakan sebelumnya dengan menggunakan browser Firefox.
Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox
Atur security.enterprise_roots.enabled = true menggunakan instruksi berikut:
- Masukkan
about:configdi browser FireFox. - Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
- Pilih Perlihatkan Semua.
- Set
security.enterprise_roots.enabled=true. - Keluar dan mulai ulang Firefox.
Untuk informasi selengkapnya, lihat Menyiapkan Otoritas Sertifikat (CA) di Firefox dan file mozilla/policy-templates/README.
Cara menyiapkan sertifikat pengembang untuk Docker
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS di Linux
Membangun kepercayaan adalah distribusi dan browser spesifik. Bagian berikut memberikan instruksi untuk beberapa distribusi populer dan browser Chromium (Edge dan Chrome) dan untuk Firefox.
Ubuntu mempercayai sertifikat untuk komunikasi layanan-ke-layanan
Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.
Jalankan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM sudo update-ca-certificates
Perintah sebelumnya:
- Pastikan sertifikat pengembang pengguna saat ini dibuat.
- Ekspor sertifikat dengan izin yang ditingkatkan yang diperlukan untuk
ca-certificatesfolder, menggunakan lingkungan pengguna saat ini. -EHapus bendera untuk mengekspor sertifikat pengguna akar, menghasilkannya jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudodan-Etidak diperlukan.
Jalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Percayai sertifikat HTTPS di Linux menggunakan Edge atau Chrome
Untuk browser kromium di Linux:
libnss3-toolsInstal untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdbfolder ada pada komputer.Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Jalankan perintah berikut:
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n localhost -i /usr/local/share/ca-certificates/aspnet/https.crtKeluar dan mulai ulang browser.
Percayai sertifikat dengan Firefox di Linux
Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Buat file JSON di
/usr/lib/firefox/distribution/policies.jsondengan konten berikut:
cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
"policies": {
"Certificates": {
"Install": [
"/usr/local/share/ca-certificates/aspnet/https.crt"
]
}
}
}
EOF
Lihat Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox di artikel ini untuk cara alternatif mengonfigurasi file kebijakan menggunakan browser.
Percayai sertifikat dengan Fedora 34
Firefox di Fedora
echo 'pref("general.config.filename", "firefox.cfg");
pref("general.config.obscure_value", 0);' > ./autoconfig.js
echo '//Enable policies.json
lockPref("browser.policies.perUserDir", false);' > firefox.cfg
echo "{
\"policies\": {
\"Certificates\": {
\"Install\": [
\"aspnetcore-localhost-https.crt\"
]
}
}
}" > policies.json
dotnet dev-certs https -ep localhost.crt --format PEM
sudo mv autoconfig.js /usr/lib64/firefox/
sudo mv firefox.cfg /usr/lib64/firefox/
sudo mv policies.json /usr/lib64/firefox/distribution/
mkdir -p ~/.mozilla/certificates
cp localhost.crt ~/.mozilla/certificates/aspnetcore-localhost-https.crt
rm localhost.crt
Percayai dotnet-to-dotnet di Fedora
sudo cp localhost.crt /etc/pki/tls/certs/localhost.pem
sudo update-ca-trust
rm localhost.crt
Lihat komentar GitHub ini untuk informasi selengkapnya.
Percayai sertifikat dengan distro lain
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS dari Subsistem Windows untuk Linux
Subsistem Windows untuk Linux (WSL) menghasilkan sertifikat pengembangan yang ditandatangani sendiri HTTPS. Untuk mengonfigurasi penyimpanan sertifikat Windows agar mempercayai sertifikat WSL:
Ekspor sertifikat pengembang ke file di Windows:
dotnet dev-certs https -ep C:\<<path-to-folder>>\aspnetcore.pfx -p $CREDENTIAL_PLACEHOLDER$Di mana
$CREDENTIAL_PLACEHOLDER$kata sandi.Di jendela WSL, impor sertifikat yang diekspor pada instans WSL:
dotnet dev-certs https --clean --import /mnt/c/<<path-to-folder>>/aspnetcore.pfx -p $CREDENTIAL_PLACEHOLDER$
Pendekatan sebelumnya adalah operasi satu kali per sertifikat dan per distribusi WSL. Lebih mudah daripada mengekspor sertifikat berulang kali. Jika Anda memperbarui atau meregenerasi sertifikat pada windows, Anda mungkin perlu menjalankan perintah sebelumnya lagi.
Memecahkan masalah sertifikat seperti sertifikat tidak tepercaya
Bagian ini memberikan bantuan ketika sertifikat pengembangan ASP.NET Core HTTPS telah diinstal dan dipercaya, tetapi Anda masih memiliki peringatan browser bahwa sertifikat tidak tepercaya. Sertifikat pengembangan HTTPS Inti ASP.NET digunakan oleh Kestrel.
Untuk memperbaiki sertifikat IIS Express, lihat masalah Stackoverflow ini.
Semua platform - sertifikat tidak tepercaya
Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
dotnet dev-certs https --clean gagal
Perintah sebelumnya menyelesaikan sebagian besar masalah kepercayaan browser. Jika browser masih tidak mempercayai sertifikat, ikuti saran khusus platform yang mengikutinya.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan solusinya. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio, Visual Studio Code, atau Visual Studio untuk Mac.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpanan sertifikat. Harus
localhostada sertifikat dengan nama yang mudah diingatASP.NET Core HTTPS development certificatebaik di bawahCurrent User > Personal > CertificatesdanCurrent User > Trusted root certification authorities > Certificates - Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi akar Pribadi dan Tepercaya. Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah simbol berisi
+simbol pada ikon untuk menunjukkan bahwa simbol tersebut tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
Lihat Kesalahan HTTPS menggunakan IIS Express (dotnet/AspNetCore #16892) untuk memecahkan masalah sertifikat dengan Visual Studio.
Sertifikat Linux tidak tepercaya
Periksa apakah sertifikat yang dikonfigurasi untuk kepercayaan adalah sertifikat pengembang HTTPS pengguna yang akan digunakan oleh Kestrel server.
Periksa sertifikat pengembang Kestrel HTTPS default pengguna saat ini di lokasi berikut:
ls -la ~/.dotnet/corefx/cryptography/x509stores/my
File sertifikat pengembang Kestrel HTTPS adalah thumbprint SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa thumbprint kecocokan sertifikat yang diekspor dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, sertifikat tersebut bisa menjadi salah satu hal berikut:
- Sertifikat lama.
- Sertifikat pengembang yang diekspor untuk pengguna root. Untuk kasus ini, ekspor sertifikat.
Sertifikat pengguna akar dapat diperiksa di:
ls -la /root/.dotnet/corefx/cryptography/x509stores/my
Sertifikat SSL IIS Express yang digunakan dengan Visual Studio
Untuk memperbaiki masalah dengan sertifikat IIS Express, pilih Perbaiki dari alat penginstal Visual Studio. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Catatan
Jika Anda menggunakan .NET 9 SDK atau yang lebih baru, lihat prosedur Linux yang diperbarui di versi .NET 9 dari artikel ini.
Peringatan
Proyek API
Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:
- Tidak mendengarkan di HTTP.
- Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.
Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 8 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.
Proyek HSTS dan API
Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.
Pengalihan HTTP ke HTTPS menyebabkan ERR_INVALID_REDIRECT pada permintaan preflight CORS
Permintaan ke titik akhir menggunakan HTTP yang dialihkan ke HTTPS dengan UseHttpsRedirection gagal pada ERR_INVALID_REDIRECT permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya produksi ASP.NET aplikasi web Core menggunakan:
- Https Redirection Middleware (UseHttpsRedirection) untuk mengalihkan permintaan HTTP ke HTTPS.
- Middleware HSTS (UseHsts) untuk mengirim header HTTP Strict Transport Security Protocol (HSTS) ke klien.
Catatan
Aplikasi yang disebarkan dalam konfigurasi proksi terbalik memungkinkan proksi untuk menangani keamanan koneksi (HTTPS). Jika proksi juga menangani pengalihan HTTPS, tidak perlu menggunakan Middleware Pengalihan HTTPS. Jika server proksi juga menangani penulisan header HSTS (misalnya, dukungan HSTS asli di IIS 10.0 (1709) atau yang lebih baru), Middleware HSTS tidak diperlukan oleh aplikasi. Untuk informasi selengkapnya, lihat Menolak HTTPS/HSTS pada pembuatan proyek.
GunakanHttpsRedirection
Kode berikut memanggil UseHttpsRedirection dalam Program.cs file:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Kode yang disorot sebelumnya:
- Menggunakan default HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
- Menggunakan default HttpsRedirectionOptions.HttpsPort (null) kecuali ditimpa oleh
ASPNETCORE_HTTPS_PORTvariabel lingkungan atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penembolokan tautan dapat menyebabkan perilaku yang tidak stabil di lingkungan pengembangan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, lihat bagian Mengonfigurasi pengalihan permanen di produksi . Sebaiknya gunakan HSTS untuk memberi sinyal kepada klien bahwa hanya permintaan sumber daya aman yang harus dikirim ke aplikasi (hanya dalam produksi).
Konfigurasi port
Port harus tersedia untuk middleware untuk mengalihkan permintaan yang tidak aman ke HTTPS. Jika tidak ada port yang tersedia:
- Pengalihan ke HTTPS tidak terjadi.
- Middleware mencatat peringatan "Gagal menentukan port https untuk dialihkan."
Tentukan port HTTPS menggunakan salah satu pendekatan berikut:
Atur
https_portpengaturan host:Dalam konfigurasi host.
Dengan mengatur
ASPNETCORE_HTTPS_PORTvariabel lingkungan.Dengan menambahkan entri tingkat atas di
appsettings.json:{ "https_port": 443, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }
Tunjukkan port dengan skema aman menggunakan variabel lingkungan ASPNETCORE_URLS. Variabel lingkungan mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core mengatur URL HTTPS untuk
Properties/launchsettings.jsondan Kestrel IIS Express.launchsettings.jsonhanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penyebaran Kestrel tepi server atau server HTTP.sys yang menghadap publik. Hanya satu port HTTPS yang digunakan oleh aplikasi. Middleware menemukan port melalui IServerAddressesFeature.
Catatan
Saat aplikasi dijalankan dalam konfigurasi proksi terbalik, IServerAddressesFeature tidak tersedia. Atur port menggunakan salah satu pendekatan lain yang dijelaskan di bagian ini.
Penyebaran Edge
Saat Kestrel atau HTTP.sys digunakan sebagai server tepi yang menghadap publik, Kestrel atau HTTP.sys harus dikonfigurasi untuk mendengarkan di keduanya:
- Port aman tempat klien dialihkan (biasanya, 443 dalam produksi dan 5001 dalam pengembangan).
- Port yang tidak aman (biasanya, 80 dalam produksi dan 5000 dalam pengembangan).
Port yang tidak aman harus dapat diakses oleh klien agar aplikasi menerima permintaan yang tidak aman dan mengalihkan klien ke port aman.
Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir atau implementasi server web HTTP.sys di ASP.NET Core.
Skenario penyebaran
Firewall apa pun antara klien dan server juga harus membuka port komunikasi untuk lalu lintas.
Jika permintaan diteruskan dalam konfigurasi proksi terbalik, gunakan Middleware Header yang Diteruskan sebelum memanggil Middleware Pengalihan HTTPS. Middleware Header yang Diteruskan memperbarui Request.Scheme, menggunakan X-Forwarded-Proto header . Middleware memungkinkan URI pengalihan dan kebijakan keamanan lainnya berfungsi dengan benar. Saat Middleware Header yang Diteruskan tidak digunakan, aplikasi backend mungkin tidak menerima skema yang benar dan berakhir dalam perulangan pengalihan. Pesan kesalahan pengguna akhir umum adalah bahwa terlalu banyak pengalihan yang terjadi.
Saat menyebarkan ke Azure App Service, ikuti panduan dalam Tutorial: Mengikat sertifikat SSL kustom yang ada ke Azure Web Apps.
Opsi
Panggilan kode yang disorot AddHttpsRedirection berikut untuk mengonfigurasi opsi middleware:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
AddHttpsRedirection Panggilan hanya diperlukan untuk mengubah nilai HttpsPort atau RedirectStatusCode.
Kode yang disorot sebelumnya:
- HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang StatusCodes kelas untuk penugasan ke
RedirectStatusCode. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen dalam produksi
Middleware default untuk mengirim Status307TemporaryRedirect dengan semua pengalihan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, bungkus konfigurasi opsi middleware dalam pemeriksaan kondisional untuk lingkungan non-Pengembangan.
Saat mengonfigurasi layanan di Program.cs:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
if (!builder.Environment.IsDevelopment())
{
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status308PermanentRedirect;
options.HttpsPort = 443;
});
}
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Pendekatan alternatif Middleware Pengalihan HTTPS
Alternatif untuk menggunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) adalah menggunakan MIDDLEware Penulisan Ulang URL (AddRedirectToHttps). AddRedirectToHttps juga dapat mengatur kode status dan port saat pengalihan dijalankan. Untuk informasi selengkapnya, lihat URL Menulis Ulang Middleware.
Saat mengalihkan ke HTTPS tanpa persyaratan untuk aturan pengalihan tambahan, sebaiknya gunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) yang dijelaskan dalam artikel ini.
Http Strict Transport Security Protocol (HSTS)
Per OWASP, HTTP Strict Transport Security (HSTS) adalah peningkatan keamanan keikutsertaan yang ditentukan oleh aplikasi web melalui penggunaan header respons. Saat browser yang mendukung HSTS menerima header ini:
- Browser menyimpan konfigurasi untuk domain yang mencegah pengiriman komunikasi apa pun melalui HTTP. Browser memaksa semua komunikasi melalui HTTPS.
- Browser mencegah pengguna menggunakan sertifikat yang tidak tepercaya atau tidak valid. Browser menonaktifkan perintah yang memungkinkan pengguna untuk memercayai sertifikat tersebut untuk sementara waktu.
Karena HSTS diberlakukan oleh klien, HSTS memiliki beberapa batasan:
- Klien harus mendukung HSTS.
- HSTS memerlukan setidaknya satu permintaan HTTPS yang berhasil untuk menetapkan kebijakan HSTS.
- Aplikasi harus memeriksa setiap permintaan HTTP dan mengalihkan atau menolak permintaan HTTP.
ASP.NET Core mengimplementasikan HSTS dengan UseHsts metode ekstensi. Kode berikut memanggil UseHsts saat aplikasi tidak dalam mode pengembangan:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
UseHsts tidak disarankan dalam pengembangan karena pengaturan HSTS sangat dapat di-cache oleh browser. Secara default, UseHsts tidak termasuk alamat loopback lokal.
Untuk lingkungan produksi yang menerapkan HTTPS untuk pertama kalinya, atur awal HstsOptions.MaxAge ke nilai kecil menggunakan salah TimeSpan satu metode. Atur nilai dari jam ke tidak lebih dari satu hari jika Anda perlu mengembalikan infrastruktur HTTPS ke HTTP. Setelah Anda yakin dengan keberlanjutan konfigurasi HTTPS, tingkatkan nilai HSTS max-age ; nilai yang umum digunakan adalah satu tahun.
Kode yang disorot berikut:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
- Mengatur parameter
Strict-Transport-Securitypramuat header. Pramuat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk memuat situs HSTS sebelumnya pada penginstalan baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-ageparameterStrict-Transport-Securityheader menjadi 60 hari. Jika tidak diatur, default ke 30 hari. Untuk informasi selengkapnya, lihat arahan usia maks. example.comMenambahkan ke daftar host untuk dikecualikan.
UseHsts mengecualikan host loopback berikut:
localhost: Alamat loopback IPv4.127.0.0.1: Alamat loopback IPv4.[::1]: Alamat loopback IPv6.
Menolak HTTPS/HSTS pada pembuatan proyek
Dalam beberapa skenario layanan backend di mana keamanan koneksi ditangani di tepi jaringan yang menghadap publik, mengonfigurasi keamanan koneksi di setiap simpul tidak diperlukan. Aplikasi web yang dihasilkan dari templat di Visual Studio atau dari perintah baru dotnet mengaktifkan pengalihan HTTPS dan HSTS. Untuk penyebaran yang tidak memerlukan skenario ini, Anda dapat menolak HTTPS/HSTS saat aplikasi dibuat dari templat.
Untuk menolak HTTPS/HSTS:
Hapus centang pada kotak centang Konfigurasi untuk HTTPS .
Percayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS
Untuk browser Firefox, lihat bagian berikutnya.
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman eksekusi pertama. Misalnya, dotnet --info menghasilkan variasi output berikut:
ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.
Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal. Sertifikat telah diinstal, tetapi tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah satu kali untuk menjalankan dotnet dev-certs alat:
dotnet dev-certs https --trust
Perintah berikut memberikan bantuan pada dotnet dev-certs alat:
dotnet dev-certs https --help
Peringatan
Jangan membuat sertifikat pengembangan di lingkungan yang akan didistribusikan ulang, seperti gambar kontainer atau komputer virtual. Melakukannya dapat menyebabkan spoofing dan elevasi hak istimewa. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE variabel lingkungan ke false sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewati pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman eksekusi pertama CLI.
Percayai sertifikat HTTPS dengan Firefox untuk mencegah kesalahan SEC_ERROR_INADEQUATE_KEY_USAGE
Browser Firefox menggunakan penyimpanan sertifikatnya sendiri, dan karenanya tidak mempercayai sertifikat IIS Express atau Kestrel pengembang.
Ada dua pendekatan untuk mempercayai sertifikat HTTPS dengan Firefox, membuat file kebijakan atau mengonfigurasi dengan browser FireFox. Mengonfigurasi dengan browser membuat file kebijakan, sehingga dua pendekatan tersebut setara.
Membuat file kebijakan untuk mempercayai sertifikat HTTPS dengan Firefox
Buat file kebijakan (policies.json) di:
- Windows:
%PROGRAMFILES%\Mozilla Firefox\distribution\ - MacOS:
Firefox.app/Contents/Resources/distribution - Linux: Lihat Mempercayai sertifikat dengan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
File kebijakan sebelumnya membuat sertifikat kepercayaan Firefox dari sertifikat tepercaya di penyimpanan sertifikat Windows. Bagian berikutnya menyediakan pendekatan alternatif untuk membuat file kebijakan sebelumnya dengan menggunakan browser Firefox.
Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox
Atur security.enterprise_roots.enabled = true menggunakan instruksi berikut:
- Masukkan
about:configdi browser FireFox. - Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
- Pilih Perlihatkan Semua
- Mengeset
security.enterprise_roots.enabled=true - Keluar dan mulai ulang Firefox
Untuk informasi selengkapnya, lihat Menyiapkan Otoritas Sertifikat (CA) di Firefox dan file mozilla/policy-templates/README.
Cara menyiapkan sertifikat pengembang untuk Docker
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS di Linux
Membangun kepercayaan adalah distribusi dan browser spesifik. Bagian berikut memberikan instruksi untuk beberapa distribusi populer dan browser Chromium (Edge dan Chrome) dan untuk Firefox.
Ubuntu mempercayai sertifikat untuk komunikasi layanan-ke-layanan
Instruksi berikut tidak berfungsi untuk beberapa versi Ubuntu, seperti 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.
Jalankan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM sudo update-ca-certificates
Perintah sebelumnya:
- Pastikan sertifikat pengembang pengguna saat ini dibuat.
- Mengekspor sertifikat dengan izin yang ditingkatkan yang diperlukan untuk
ca-certificatesfolder, menggunakan lingkungan pengguna saat ini. - Menghapus
-Ebendera mengekspor sertifikat pengguna akar, menghasilkannya jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudodan-Etidak diperlukan.
Jalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Percayai sertifikat HTTPS di Linux menggunakan Edge atau Chrome
Untuk browser kromium di Linux:
libnss3-toolsInstal untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdbfolder ada pada komputer.Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Jalankan perintah berikut:
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n localhost -i /usr/local/share/ca-certificates/aspnet/https.crtKeluar dan mulai ulang browser.
Percayai sertifikat dengan Firefox di Linux
Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Buat file JSON di
/usr/lib/firefox/distribution/policies.jsondengan perintah berikut:
cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
"policies": {
"Certificates": {
"Install": [
"/usr/local/share/ca-certificates/aspnet/https.crt"
]
}
}
}
EOF
Catatan: Ubuntu 21.10 Firefox hadir sebagai paket snap dan folder penginstalan adalah /snap/firefox/current/usr/lib/firefox.
Lihat Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox di artikel ini untuk cara alternatif mengonfigurasi file kebijakan menggunakan browser.
Percayai sertifikat dengan Fedora 34
Lihat:
- Komentar GitHub ini
- Fedora: Menggunakan Sertifikat Sistem Bersama
- Siapkan lingkungan pengembangan .NET di Fedora.
Percayai sertifikat dengan distro lain
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS dari Subsistem Windows untuk Linux
Instruksi berikut tidak berfungsi untuk beberapa distribusi Linux, seperti Ubuntu 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Subsistem Windows untuk Linux (WSL) menghasilkan sertifikat pengembangan yang ditandatangani sendiri HTTPS, yang secara default tidak dipercaya di Windows. Cara term mudah agar Windows mempercayai sertifikat WSL, adalah dengan mengonfigurasi WSL untuk menggunakan sertifikat yang sama dengan Windows:
Di Windows, ekspor sertifikat pengembang ke file:
dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trustDi mana
$CREDENTIAL_PLACEHOLDER$kata sandi.Di jendela WSL, impor sertifikat yang diekspor pada instans WSL:
dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
Pendekatan sebelumnya adalah operasi satu kali per sertifikat dan per distribusi WSL. Lebih mudah daripada mengekspor sertifikat berulang kali. Jika Anda memperbarui atau meregenerasi sertifikat pada windows, Anda mungkin perlu menjalankan perintah sebelumnya lagi.
Memecahkan masalah sertifikat seperti sertifikat tidak tepercaya
Bagian ini memberikan bantuan ketika sertifikat pengembangan ASP.NET Core HTTPS telah diinstal dan dipercaya, tetapi Anda masih memiliki peringatan browser bahwa sertifikat tidak tepercaya. Sertifikat pengembangan HTTPS Inti ASP.NET digunakan oleh Kestrel.
Untuk memperbaiki sertifikat IIS Express, lihat masalah Stackoverflow ini.
Semua platform - sertifikat tidak tepercaya
Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
dotnet dev-certs https --clean Fails
Perintah sebelumnya menyelesaikan sebagian besar masalah kepercayaan browser. Jika browser masih tidak mempercayai sertifikat, ikuti saran khusus platform yang mengikutinya.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan solusinya. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpanan sertifikat. Harus
localhostada sertifikat dengan nama yang mudah diingatASP.NET Core HTTPS development certificatebaik di bawahCurrent User > Personal > CertificatesdanCurrent User > Trusted root certification authorities > Certificates - Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi akar Pribadi dan Tepercaya. Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah simbol berisi
+simbol pada ikon untuk menunjukkan bahwa simbol tersebut tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
Lihat Kesalahan HTTPS menggunakan IIS Express (dotnet/AspNetCore #16892) untuk memecahkan masalah sertifikat dengan Visual Studio.
Sertifikat Linux tidak tepercaya
Periksa apakah sertifikat yang dikonfigurasi untuk kepercayaan adalah sertifikat pengembang HTTPS pengguna yang akan digunakan oleh Kestrel server.
Periksa sertifikat pengembang Kestrel HTTPS default pengguna saat ini di lokasi berikut:
ls -la ~/.dotnet/corefx/cryptography/x509stores/my
File sertifikat pengembang Kestrel HTTPS adalah thumbprint SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa thumbprint kecocokan sertifikat yang diekspor dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, sertifikat tersebut bisa menjadi salah satu hal berikut:
- Sertifikat lama.
- Sertifikat pengembang yang diekspor untuk pengguna root. Untuk kasus ini, ekspor sertifikat.
Sertifikat pengguna akar dapat diperiksa di:
ls -la /root/.dotnet/corefx/cryptography/x509stores/my
Sertifikat SSL IIS Express yang digunakan dengan Visual Studio
Untuk memperbaiki masalah dengan sertifikat IIS Express, pilih Perbaiki dari alat penginstal Visual Studio. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Kebijakan grup mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya
Dalam beberapa kasus, kebijakan grup dapat mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Catatan
Jika Anda menggunakan .NET 9 SDK atau yang lebih baru, lihat prosedur Linux yang diperbarui di versi .NET 9 dari artikel ini.
Peringatan
Proyek API
Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:
- Tidak mendengarkan di HTTP.
- Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.
Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 8 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.
Proyek HSTS dan API
Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.
Pengalihan HTTP ke HTTPS menyebabkan ERR_INVALID_REDIRECT pada permintaan preflight CORS
Permintaan ke titik akhir menggunakan HTTP yang dialihkan ke HTTPS dengan UseHttpsRedirection gagal pada ERR_INVALID_REDIRECT permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya produksi ASP.NET aplikasi web Core menggunakan:
- Https Redirection Middleware (UseHttpsRedirection) untuk mengalihkan permintaan HTTP ke HTTPS.
- Middleware HSTS (UseHsts) untuk mengirim header HTTP Strict Transport Security Protocol (HSTS) ke klien.
Catatan
Aplikasi yang disebarkan dalam konfigurasi proksi terbalik memungkinkan proksi untuk menangani keamanan koneksi (HTTPS). Jika proksi juga menangani pengalihan HTTPS, tidak perlu menggunakan Middleware Pengalihan HTTPS. Jika server proksi juga menangani penulisan header HSTS (misalnya, dukungan HSTS asli di IIS 10.0 (1709) atau yang lebih baru), Middleware HSTS tidak diperlukan oleh aplikasi. Untuk informasi selengkapnya, lihat Menolak HTTPS/HSTS pada pembuatan proyek.
GunakanHttpsRedirection
Kode berikut memanggil UseHttpsRedirection dalam Program.cs file:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Kode yang disorot sebelumnya:
- Menggunakan default HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
- Menggunakan default HttpsRedirectionOptions.HttpsPort (null) kecuali ditimpa oleh
ASPNETCORE_HTTPS_PORTvariabel lingkungan atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penembolokan tautan dapat menyebabkan perilaku yang tidak stabil di lingkungan pengembangan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, lihat bagian Mengonfigurasi pengalihan permanen di produksi . Sebaiknya gunakan HSTS untuk memberi sinyal kepada klien bahwa hanya permintaan sumber daya aman yang harus dikirim ke aplikasi (hanya dalam produksi).
Konfigurasi port
Port harus tersedia untuk middleware untuk mengalihkan permintaan yang tidak aman ke HTTPS. Jika tidak ada port yang tersedia:
- Pengalihan ke HTTPS tidak terjadi.
- Middleware mencatat peringatan "Gagal menentukan port https untuk dialihkan."
Tentukan port HTTPS menggunakan salah satu pendekatan berikut:
Atur
https_portpengaturan host:Dalam konfigurasi host.
Dengan mengatur
ASPNETCORE_HTTPS_PORTvariabel lingkungan.Dengan menambahkan entri tingkat atas di
appsettings.json:{ "https_port": 443, "Logging": { "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" } }, "AllowedHosts": "*" }
Tunjukkan port dengan skema aman menggunakan variabel lingkungan ASPNETCORE_URLS. Variabel lingkungan mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core mengatur URL HTTPS untuk
Properties/launchsettings.jsondan Kestrel IIS Express.launchsettings.jsonhanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penyebaran Kestrel tepi server atau server HTTP.sys yang menghadap publik. Hanya satu port HTTPS yang digunakan oleh aplikasi. Middleware menemukan port melalui IServerAddressesFeature.
Catatan
Saat aplikasi dijalankan dalam konfigurasi proksi terbalik, IServerAddressesFeature tidak tersedia. Atur port menggunakan salah satu pendekatan lain yang dijelaskan di bagian ini.
Penyebaran Edge
Saat Kestrel atau HTTP.sys digunakan sebagai server tepi yang menghadap publik, Kestrel atau HTTP.sys harus dikonfigurasi untuk mendengarkan di keduanya:
- Port aman tempat klien dialihkan (biasanya, 443 dalam produksi dan 5001 dalam pengembangan).
- Port yang tidak aman (biasanya, 80 dalam produksi dan 5000 dalam pengembangan).
Port yang tidak aman harus dapat diakses oleh klien agar aplikasi menerima permintaan yang tidak aman dan mengalihkan klien ke port aman.
Untuk informasi selengkapnya, lihat Kestrel konfigurasi titik akhir atau implementasi server web HTTP.sys di ASP.NET Core.
Skenario penyebaran
Firewall apa pun antara klien dan server juga harus membuka port komunikasi untuk lalu lintas.
Jika permintaan diteruskan dalam konfigurasi proksi terbalik, gunakan Middleware Header yang Diteruskan sebelum memanggil Middleware Pengalihan HTTPS. Middleware Header yang Diteruskan memperbarui Request.Scheme, menggunakan X-Forwarded-Proto header . Middleware memungkinkan URI pengalihan dan kebijakan keamanan lainnya berfungsi dengan benar. Saat Middleware Header yang Diteruskan tidak digunakan, aplikasi backend mungkin tidak menerima skema yang benar dan berakhir dalam perulangan pengalihan. Pesan kesalahan pengguna akhir umum adalah bahwa terlalu banyak pengalihan yang terjadi.
Saat menyebarkan ke Azure App Service, ikuti panduan dalam Tutorial: Mengikat sertifikat SSL kustom yang ada ke Azure Web Apps.
Opsi
Panggilan kode yang disorot AddHttpsRedirection berikut untuk mengonfigurasi opsi middleware:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
AddHttpsRedirection Panggilan hanya diperlukan untuk mengubah nilai HttpsPort atau RedirectStatusCode.
Kode yang disorot sebelumnya:
- HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang StatusCodes kelas untuk penugasan ke
RedirectStatusCode. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen dalam produksi
Middleware default untuk mengirim Status307TemporaryRedirect dengan semua pengalihan. Jika Anda lebih suka mengirim kode status pengalihan permanen saat aplikasi berada di lingkungan non-Pengembangan, bungkus konfigurasi opsi middleware dalam pemeriksaan kondisional untuk lingkungan non-Pengembangan.
Saat mengonfigurasi layanan di Program.cs:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
if (!builder.Environment.IsDevelopment())
{
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status308PermanentRedirect;
options.HttpsPort = 443;
});
}
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
Pendekatan alternatif Middleware Pengalihan HTTPS
Alternatif untuk menggunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) adalah menggunakan MIDDLEware Penulisan Ulang URL (AddRedirectToHttps). AddRedirectToHttps juga dapat mengatur kode status dan port saat pengalihan dijalankan. Untuk informasi selengkapnya, lihat URL Menulis Ulang Middleware.
Saat mengalihkan ke HTTPS tanpa persyaratan untuk aturan pengalihan tambahan, sebaiknya gunakan Middleware Pengalihan HTTPS (UseHttpsRedirection) yang dijelaskan dalam artikel ini.
Http Strict Transport Security Protocol (HSTS)
Per OWASP, HTTP Strict Transport Security (HSTS) adalah peningkatan keamanan keikutsertaan yang ditentukan oleh aplikasi web melalui penggunaan header respons. Saat browser yang mendukung HSTS menerima header ini:
- Browser menyimpan konfigurasi untuk domain yang mencegah pengiriman komunikasi apa pun melalui HTTP. Browser memaksa semua komunikasi melalui HTTPS.
- Browser mencegah pengguna menggunakan sertifikat yang tidak tepercaya atau tidak valid. Browser menonaktifkan perintah yang memungkinkan pengguna untuk memercayai sertifikat tersebut untuk sementara waktu.
Karena HSTS diberlakukan oleh klien, HSTS memiliki beberapa batasan:
- Klien harus mendukung HSTS.
- HSTS memerlukan setidaknya satu permintaan HTTPS yang berhasil untuk menetapkan kebijakan HSTS.
- Aplikasi harus memeriksa setiap permintaan HTTP dan mengalihkan atau menolak permintaan HTTP.
ASP.NET Core mengimplementasikan HSTS dengan UseHsts metode ekstensi. Kode berikut memanggil UseHsts saat aplikasi tidak dalam mode pengembangan:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
UseHsts tidak disarankan dalam pengembangan karena pengaturan HSTS sangat dapat di-cache oleh browser. Secara default, UseHsts tidak termasuk alamat loopback lokal.
Untuk lingkungan produksi yang menerapkan HTTPS untuk pertama kalinya, atur awal HstsOptions.MaxAge ke nilai kecil menggunakan salah TimeSpan satu metode. Atur nilai dari jam ke tidak lebih dari satu hari jika Anda perlu mengembalikan infrastruktur HTTPS ke HTTP. Setelah Anda yakin dengan keberlanjutan konfigurasi HTTPS, tingkatkan nilai HSTS max-age ; nilai yang umum digunakan adalah satu tahun.
Kode yang disorot berikut:
using static Microsoft.AspNetCore.Http.StatusCodes;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
builder.Services.AddHsts(options =>
{
options.Preload = true;
options.IncludeSubDomains = true;
options.MaxAge = TimeSpan.FromDays(60);
options.ExcludedHosts.Add("example.com");
options.ExcludedHosts.Add("www.example.com");
});
builder.Services.AddHttpsRedirection(options =>
{
options.RedirectStatusCode = Status307TemporaryRedirect;
options.HttpsPort = 5001;
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.Run();
- Mengatur parameter
Strict-Transport-Securitypramuat header. Pramuat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk memuat situs HSTS sebelumnya pada penginstalan baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-ageparameterStrict-Transport-Securityheader menjadi 60 hari. Jika tidak diatur, default ke 30 hari. Untuk informasi selengkapnya, lihat arahan usia maks. example.comMenambahkan ke daftar host untuk dikecualikan.
UseHsts mengecualikan host loopback berikut:
localhost: Alamat loopback IPv4.127.0.0.1: Alamat loopback IPv4.[::1]: Alamat loopback IPv6.
Menolak HTTPS/HSTS pada pembuatan proyek
Dalam beberapa skenario layanan backend di mana keamanan koneksi ditangani di tepi jaringan yang menghadap publik, mengonfigurasi keamanan koneksi di setiap simpul tidak diperlukan. Aplikasi web yang dihasilkan dari templat di Visual Studio atau dari perintah baru dotnet mengaktifkan pengalihan HTTPS dan HSTS. Untuk penyebaran yang tidak memerlukan skenario ini, Anda dapat menolak HTTPS/HSTS saat aplikasi dibuat dari templat.
Untuk menolak HTTPS/HSTS:
Hapus centang pada kotak centang Konfigurasi untuk HTTPS .
Percayai sertifikat pengembangan ASP.NET Core HTTPS di Windows dan macOS
Untuk browser Firefox, lihat bagian berikutnya.
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman eksekusi pertama. Misalnya, dotnet --info menghasilkan variasi output berikut:
ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.
Menginstal .NET Core SDK menginstal sertifikat pengembangan ASP.NET Core HTTPS ke penyimpanan sertifikat pengguna lokal. Sertifikat telah diinstal, tetapi tidak tepercaya. Untuk mempercayai sertifikat, lakukan langkah satu kali untuk menjalankan dotnet dev-certs alat:
dotnet dev-certs https --trust
Perintah berikut memberikan bantuan pada dotnet dev-certs alat:
dotnet dev-certs https --help
Peringatan
Jangan membuat sertifikat pengembangan di lingkungan yang akan didistribusikan ulang, seperti gambar kontainer atau komputer virtual. Melakukannya dapat menyebabkan spoofing dan elevasi hak istimewa. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE variabel lingkungan ke false sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewati pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman eksekusi pertama CLI.
Percayai sertifikat HTTPS dengan Firefox untuk mencegah kesalahan SEC_ERROR_INADEQUATE_KEY_USAGE
Browser Firefox menggunakan penyimpanan sertifikatnya sendiri, dan karenanya tidak mempercayai sertifikat IIS Express atau Kestrel pengembang.
Ada dua pendekatan untuk mempercayai sertifikat HTTPS dengan Firefox, membuat file kebijakan atau mengonfigurasi dengan browser FireFox. Mengonfigurasi dengan browser membuat file kebijakan, sehingga dua pendekatan tersebut setara.
Membuat file kebijakan untuk mempercayai sertifikat HTTPS dengan Firefox
Buat file kebijakan (policies.json) di:
- Windows:
%PROGRAMFILES%\Mozilla Firefox\distribution\ - MacOS:
Firefox.app/Contents/Resources/distribution - Linux: Lihat Mempercayai sertifikat dengan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
File kebijakan sebelumnya membuat sertifikat kepercayaan Firefox dari sertifikat tepercaya di penyimpanan sertifikat Windows. Bagian berikutnya menyediakan pendekatan alternatif untuk membuat file kebijakan sebelumnya dengan menggunakan browser Firefox.
Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox
Atur security.enterprise_roots.enabled = true menggunakan instruksi berikut:
- Masukkan
about:configdi browser FireFox. - Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
- Pilih Perlihatkan Semua
- Mengeset
security.enterprise_roots.enabled=true - Keluar dan mulai ulang Firefox
Untuk informasi selengkapnya, lihat Menyiapkan Otoritas Sertifikat (CA) di Firefox dan file mozilla/policy-templates/README.
Cara menyiapkan sertifikat pengembang untuk Docker
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS di Linux
Membangun kepercayaan adalah distribusi dan browser spesifik. Bagian berikut memberikan instruksi untuk beberapa distribusi populer dan browser Chromium (Edge dan Chrome) dan untuk Firefox.
Percayai sertifikat HTTPS di Linux dengan linux-dev-certs
linux-dev-certs adalah alat global .NET sumber terbuka yang didukung komunitas yang menyediakan cara mudah untuk membuat dan memercayai sertifikat pengembang di Linux. Alat ini tidak dipertahankan atau didukung oleh Microsoft.
Perintah berikut menginstal alat dan membuat sertifikat pengembang tepercaya:
dotnet tool update -g linux-dev-certs
dotnet linux-dev-certs install
Untuk informasi selengkapnya atau untuk melaporkan masalah, lihat repositori GitHub linux-dev-certs.
Ubuntu mempercayai sertifikat untuk komunikasi layanan-ke-layanan
Instruksi berikut tidak berfungsi untuk beberapa versi Ubuntu, seperti 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.
Jalankan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM sudo update-ca-certificates
Perintah sebelumnya:
- Pastikan sertifikat pengembang pengguna saat ini dibuat.
- Mengekspor sertifikat dengan izin yang ditingkatkan yang diperlukan untuk
ca-certificatesfolder, menggunakan lingkungan pengguna saat ini. - Menghapus
-Ebendera mengekspor sertifikat pengguna akar, menghasilkannya jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudodan-Etidak diperlukan.
Jalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Percayai sertifikat HTTPS di Linux menggunakan Edge atau Chrome
Untuk browser kromium di Linux:
libnss3-toolsInstal untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdbfolder ada pada komputer.Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Jalankan perintah berikut:
certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n localhost -i /usr/local/share/ca-certificates/aspnet/https.crtKeluar dan mulai ulang browser.
Percayai sertifikat dengan Firefox di Linux
Ekspor sertifikat dengan perintah berikut:
dotnet dev-certs https sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEMJalur dalam perintah sebelumnya khusus untuk Ubuntu. Untuk distribusi lain, pilih jalur yang sesuai atau gunakan jalur untuk Otoritas Sertifikat (CA).
Buat file JSON di
/usr/lib/firefox/distribution/policies.jsondengan perintah berikut:
cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
"policies": {
"Certificates": {
"Install": [
"/usr/local/share/ca-certificates/aspnet/https.crt"
]
}
}
}
EOF
Catatan: Ubuntu 21.10 Firefox hadir sebagai paket snap dan folder penginstalan adalah /snap/firefox/current/usr/lib/firefox.
Lihat Mengonfigurasi kepercayaan sertifikat HTTPS menggunakan browser Firefox di artikel ini untuk cara alternatif mengonfigurasi file kebijakan menggunakan browser.
Percayai sertifikat dengan Fedora 34
Lihat:
- Komentar GitHub ini
- Fedora: Menggunakan Sertifikat Sistem Bersama
- Siapkan lingkungan pengembangan .NET di Fedora.
Percayai sertifikat dengan distro lain
Lihat masalah GitHub ini.
Percayai sertifikat HTTPS dari Subsistem Windows untuk Linux
Instruksi berikut tidak berfungsi untuk beberapa distribusi Linux, seperti Ubuntu 20.04. Untuk informasi selengkapnya, lihat Masalah GitHub dotnet/AspNetCore.Docs #23686.
Subsistem Windows untuk Linux (WSL) menghasilkan sertifikat pengembangan yang ditandatangani sendiri HTTPS, yang secara default tidak dipercaya di Windows. Cara term mudah agar Windows mempercayai sertifikat WSL, adalah dengan mengonfigurasi WSL untuk menggunakan sertifikat yang sama dengan Windows:
Di Windows, ekspor sertifikat pengembang ke file:
dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trustDi mana
$CREDENTIAL_PLACEHOLDER$kata sandi.Di jendela WSL, impor sertifikat yang diekspor pada instans WSL:
dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
Pendekatan sebelumnya adalah operasi satu kali per sertifikat dan per distribusi WSL. Lebih mudah daripada mengekspor sertifikat berulang kali. Jika Anda memperbarui atau meregenerasi sertifikat pada windows, Anda mungkin perlu menjalankan perintah sebelumnya lagi.
Memecahkan masalah sertifikat seperti sertifikat tidak tepercaya
Bagian ini memberikan bantuan ketika sertifikat pengembangan ASP.NET Core HTTPS telah diinstal dan dipercaya, tetapi Anda masih memiliki peringatan browser bahwa sertifikat tidak tepercaya. Sertifikat pengembangan HTTPS Inti ASP.NET digunakan oleh Kestrel.
Untuk memperbaiki sertifikat IIS Express, lihat masalah Stackoverflow ini.
Semua platform - sertifikat tidak tepercaya
Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Kepercayaan sertifikat di-cache oleh browser.
dotnet dev-certs https --clean Fails
Perintah sebelumnya menyelesaikan sebagian besar masalah kepercayaan browser. Jika browser masih tidak mempercayai sertifikat, ikuti saran khusus platform yang mengikutinya.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan solusinya. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpanan sertifikat. Harus
localhostada sertifikat dengan nama yang mudah diingatASP.NET Core HTTPS development certificatebaik di bawahCurrent User > Personal > CertificatesdanCurrent User > Trusted root certification authorities > Certificates - Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi akar Pribadi dan Tepercaya. Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah simbol berisi
+simbol pada ikon untuk menunjukkan bahwa simbol tersebut tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup instans browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi.
Lihat Kesalahan HTTPS menggunakan IIS Express (dotnet/AspNetCore #16892) untuk memecahkan masalah sertifikat dengan Visual Studio.
Sertifikat Linux tidak tepercaya
Periksa apakah sertifikat yang dikonfigurasi untuk kepercayaan adalah sertifikat pengembang HTTPS pengguna yang akan digunakan oleh Kestrel server.
Periksa sertifikat pengembang Kestrel HTTPS default pengguna saat ini di lokasi berikut:
ls -la ~/.dotnet/corefx/cryptography/x509stores/my
File sertifikat pengembang Kestrel HTTPS adalah thumbprint SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa thumbprint kecocokan sertifikat yang diekspor dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, sertifikat tersebut bisa menjadi salah satu hal berikut:
- Sertifikat lama.
- Sertifikat pengembang yang diekspor untuk pengguna root. Untuk kasus ini, ekspor sertifikat.
Sertifikat pengguna akar dapat diperiksa di:
ls -la /root/.dotnet/corefx/cryptography/x509stores/my
Sertifikat SSL IIS Express yang digunakan dengan Visual Studio
Untuk memperbaiki masalah dengan sertifikat IIS Express, pilih Perbaiki dari alat penginstal Visual Studio. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Kebijakan grup mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya
Dalam beberapa kasus, kebijakan grup dapat mencegah sertifikat yang ditandatangani sendiri agar tidak tepercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
ASP.NET Core