Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
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 oleh UseHttpsRedirection, mengalami kegagalan pada ERR_INVALID_REDIRECT
dalam permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection
untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya gunakan ASP.NET Core untuk aplikasi web produksi.
- 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.
Gunakan Pengalihan HTTPS
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 variabel lingkungan
ASPNETCORE_HTTPS_PORT
atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penyimpanan tautan dapat menyebabkan perilaku 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_port
pengaturan host:Dalam pengaturan host.
Dengan mengatur
ASPNETCORE_HTTPS_PORT
variabel 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 yang mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core menetapkan URL HTTPS di dalam
Properties/launchsettings.json
untuk keduanya, yaitu Kestrel dan IIS Express.launchsettings.json
hanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penerapan tepi yang menghadap publik dari server Kestrel atau server HTTP.sys. 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 Forwarded Headers Middleware sebelum memanggil HTTPS Redirection Middleware. Middleware Header yang Diteruskan memperbarui Request.Scheme
, dengan menggunakan header X-Forwarded-Proto
. 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 mengalami loop 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
Kode berikut yang disorot memanggil AddHttpsRedirection 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();
Memanggil AddHttpsRedirection
hanya diperlukan untuk mengubah nilai dari HttpsPort
atau RedirectStatusCode
.
Kode yang disorot sebelumnya:
-
HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang dari kelas StatusCodes untuk penugasan ke
RedirectStatusCode
. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen di lingkungan produksi
Middleware secara default mengirimkan Status307TemporaryRedirect pada 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 untuk 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 Middleware Penulisan Ulang URL.
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 yang bersifat opsional 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 HstsOptions.MaxAge ke nilai kecil menggunakan salah satu TimeSpan 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 pramuat dari header
Strict-Transport-Security
. Pra-muat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk pra-muat situs HSTS pada instalasi baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-age
parameterStrict-Transport-Security
header menjadi 60 hari. Jika tidak diatur, secara otomatis diatur menjadi 30 hari. Untuk informasi selengkapnya, lihat direktif max-age. - Menambahkan
example.com
ke daftar host untuk dikecualikan.
UseHsts
mengecualikan host loopback berikut ini:
-
localhost
: Alamat balik IPv4. -
127.0.0.1
: Alamat balik IPv4. -
[::1]
: Alamat loopback IPv6 tersebut.
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 dotnet new 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 ASP.NET Core
.NET Core SDK menyertakan sertifikat pengembangan HTTPS. Sertifikat diinstal sebagai bagian dari pengalaman penggunaan 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 tentang alat dotnet dev-certs
.
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 peningkatan hak akses. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE
variabel lingkungan ke false
sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewatkan pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman pertama menjalankan 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 lokasi yang tepat.
Untuk memperoleh kepercayaan browser (misalnya di Edge atau Firefox), alat certutil
harus berada dalam jalur.
Kepercayaan OpenSSL
Ketika sertifikat pengembangan ASP.NET Core tepercaya, sertifikat tersebut diekspor ke folder di direktori beranda pengguna 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, sebagai alternatif, Anda dapat menyerahkan -CAfile
atau -CApath
pada setiap pemanggilan curl
individu.
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 kondisi buruk (misalnya jika dotnet dev-certs https --clean
gagal menghapusnya), sering kali dimungkinkan untuk memperbaiki keadaan menggunakan alat c_rehash
.
Mengabaikan
Jika Anda menggunakan browser lain dengan penyimpanan Network Security Services (NSS) sendiri, Anda dapat menggunakan variabel lingkungan DOTNET_DEV_CERTS_NSSDB_PATHS
untuk menentukan daftar direktori NSS yang dipisahkan dengan tanda titik dua (misalnya, direktori yang berisi cert9.db
) tempat Anda 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 sertifikat berubah, alat ini tidak akan mengetahui tentang sertifikat di lokasi sebelumnya (misalnya untuk menghapusnya).
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 ASP.NET Core 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 jendela browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya 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 tercantum di bawah ini.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan larutan tersebut. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpan sertifikat. Harus ada
localhost
sertifikat dengan nama ramahASP.NET Core HTTPS development certificate
di bawahCurrent User > Personal > Certificates
danCurrent User > Trusted root certification authorities > Certificates
- Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi root "Personal" dan "Tepercaya". Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 ada simbol
+
pada ikon untuk menunjukkan bahwa itu tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 HTTPS Kestrel adalah sidik jari SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean
, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa apakah sidik jari sertifikat yang diekspor cocok dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, itu mungkin salah satu dari berikut ini:
- Sertifikat lama.
- Sebuah sertifikat pengembang diekspor untuk pengguna root. Ekspor sertifikat untuk kasus ini.
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 untuk dapat dipercaya
Dalam beberapa kasus, kebijakan grup mungkin mencegah sertifikat yang ditandatangani sendiri tidak dapat dipercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Catatan
Jika Anda menggunakan .NET 9 atau SDK 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 oleh UseHttpsRedirection, mengalami kegagalan pada ERR_INVALID_REDIRECT
dalam permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection
untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya gunakan ASP.NET Core untuk aplikasi web produksi.
- 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.
Gunakan Pengalihan HTTPS
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 variabel lingkungan
ASPNETCORE_HTTPS_PORT
atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penyimpanan tautan dapat menyebabkan perilaku 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_port
pengaturan host:Dalam pengaturan host.
Dengan mengatur
ASPNETCORE_HTTPS_PORT
variabel 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 yang mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core menetapkan URL HTTPS di dalam
Properties/launchsettings.json
untuk keduanya, yaitu Kestrel dan IIS Express.launchsettings.json
hanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penerapan tepi yang menghadap publik dari server Kestrel atau server HTTP.sys. 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 Forwarded Headers Middleware sebelum memanggil HTTPS Redirection Middleware. Middleware Header yang Diteruskan memperbarui Request.Scheme
, dengan menggunakan header X-Forwarded-Proto
. 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 mengalami loop 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
Kode berikut yang disorot memanggil AddHttpsRedirection 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();
Memanggil AddHttpsRedirection
hanya diperlukan untuk mengubah nilai dari HttpsPort
atau RedirectStatusCode
.
Kode yang disorot sebelumnya:
-
HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang dari kelas StatusCodes untuk penugasan ke
RedirectStatusCode
. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen di lingkungan produksi
Middleware secara default mengirimkan Status307TemporaryRedirect pada 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 untuk 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 Middleware Penulisan Ulang URL.
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 yang bersifat opsional 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 HstsOptions.MaxAge ke nilai kecil menggunakan salah satu TimeSpan 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 pramuat dari header
Strict-Transport-Security
. Pra-muat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk pra-muat situs HSTS pada instalasi baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-age
parameterStrict-Transport-Security
header menjadi 60 hari. Jika tidak diatur, secara otomatis diatur menjadi 30 hari. Untuk informasi selengkapnya, lihat direktif max-age. - Menambahkan
example.com
ke daftar host untuk dikecualikan.
UseHsts
mengecualikan host loopback berikut ini:
-
localhost
: Alamat balik IPv4. -
127.0.0.1
: Alamat balik IPv4. -
[::1]
: Alamat loopback IPv6 tersebut.
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 dotnet new 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 penggunaan 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 tentang alat dotnet dev-certs
.
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 peningkatan hak akses. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE
variabel lingkungan ke false
sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewatkan pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman pertama menjalankan 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 bagian Percayai sertifikat menggunakan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
Kebijakan dalam file sebelumnya menyebabkan Firefox mempercayai sertifikat dari sertifikat yang dipercayai di dalam simpanan 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:config
di 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 bergantung pada distribusi dan browser tertentu. 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 folder
ca-certificates
, menggunakan lingkungan pengguna saat ini. - Menghapus penanda
-E
mengekspor sertifikat root, dan menghasilkan sertifikat tersebut jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudo
dan-E
tidak 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:
Instal
libnss3-tools
untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdb
folder 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 PEM
Jalur 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.crt
Keluar 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 PEM
Jalur 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.json
dengan 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 pada 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$ --trust
$CREDENTIAL_PLACEHOLDER$
adalah 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 yang dijelaskan 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 ASP.NET Core 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 jendela browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya 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 tercantum di bawah ini.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan larutan tersebut. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpan sertifikat. Harus ada
localhost
sertifikat dengan nama ramahASP.NET Core HTTPS development certificate
di bawahCurrent User > Personal > Certificates
danCurrent User > Trusted root certification authorities > Certificates
- Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi root "Personal" dan "Tepercaya". Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 ada simbol
+
pada ikon untuk menunjukkan bahwa itu tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 HTTPS Kestrel adalah sidik jari SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean
, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa apakah sidik jari sertifikat yang diekspor cocok dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, itu mungkin salah satu dari berikut ini:
- Sertifikat lama.
- Sebuah sertifikat pengembang diekspor untuk pengguna root. Ekspor sertifikat untuk kasus ini.
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 untuk dapat dipercaya
Dalam beberapa kasus, kebijakan grup mungkin mencegah sertifikat yang ditandatangani sendiri tidak dapat dipercaya. 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 gunakan ASP.NET Core untuk aplikasi web produksi.
- 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.
Gunakan Pengalihan HTTPS
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 variabel lingkungan
ASPNETCORE_HTTPS_PORT
atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penyimpanan tautan dapat menyebabkan perilaku 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_port
pengaturan host:Dalam pengaturan host.
Dengan mengatur
ASPNETCORE_HTTPS_PORT
variabel 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 yang 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 penerapan tepi yang menghadap publik dari server Kestrel atau server HTTP.sys. 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 menangani 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 Forwarded Headers Middleware sebelum memanggil HTTPS Redirection Middleware. Middleware Header yang Diteruskan memperbarui Request.Scheme
, dengan menggunakan header X-Forwarded-Proto
. 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 mengalami loop 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
Kode berikut yang disorot memanggil AddHttpsRedirection 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;
});
}
Memanggil AddHttpsRedirection
hanya diperlukan untuk mengubah nilai dari HttpsPort
atau RedirectStatusCode
.
Kode yang disorot sebelumnya:
-
HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang dari kelas StatusCodes untuk penugasan ke
RedirectStatusCode
. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen di lingkungan produksi
Middleware secara default mengirimkan Status307TemporaryRedirect pada 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 untuk 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 Middleware Penulisan Ulang URL.
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 yang bersifat opsional 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 HstsOptions.MaxAge ke nilai kecil menggunakan salah satu TimeSpan 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 pramuat dari header
Strict-Transport-Security
. Pra-muat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk pra-muat situs HSTS pada instalasi baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-age
parameterStrict-Transport-Security
header menjadi 60 hari. Jika tidak diatur, secara otomatis diatur menjadi 30 hari. Untuk informasi selengkapnya, lihat direktif max-age. - Menambahkan
example.com
ke daftar host untuk dikecualikan.
UseHsts
mengecualikan host loopback berikut ini:
-
localhost
: Alamat balik IPv4. -
127.0.0.1
: Alamat balik IPv4. -
[::1]
: Alamat loopback IPv6 tersebut.
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 dotnet new 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 penggunaan 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 tentang alat dotnet dev-certs
.
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 peningkatan hak akses. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE
variabel lingkungan ke false
sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewatkan pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman pertama menjalankan 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 menggunakan Firefox di Linux nanti di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
Kebijakan dalam file sebelumnya menyebabkan Firefox mempercayai sertifikat dari sertifikat yang dipercayai di dalam simpanan 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:config
di browser FireFox. - Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
- Pilih Perlihatkan Semua.
- Atur
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 bergantung pada distribusi dan browser tertentu. 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 folder
ca-certificates
, menggunakan lingkungan pengguna saat ini. -
-E
Hapus penanda untuk mengekspor sertifikat pengguna root, buat jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudo
dan-E
tidak 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:
Instal
libnss3-tools
untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdb
folder 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 PEM
Jalur 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.crt
Keluar 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 PEM
Jalur 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.json
dengan 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
Percayakan 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 pada 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$
$CREDENTIAL_PLACEHOLDER$
adalah 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 yang dijelaskan 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 ASP.NET Core 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 semua jendela browser yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya di-cache oleh browser.
Eksekusi '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 tercantum di bawah ini.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan larutan tersebut. 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 penyimpan sertifikat. Harus ada
localhost
sertifikat dengan nama ramahASP.NET Core HTTPS development certificate
di bawahCurrent User > Personal > Certificates
danCurrent User > Trusted root certification authorities > Certificates
- Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi root "Personal" dan "Tepercaya". Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup semua jendela browser yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya di-cache oleh browser.
OS X - sertifikat tidak tepercaya
- Buka Akses Rantai Kunci.
- Pilih rantai kunci Sistem.
- Periksa keberadaan sertifikat localhost.
- Periksa apakah ada simbol
+
pada ikon untuk menunjukkan bahwa itu tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup semua jendela browser yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya 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 HTTPS Kestrel adalah sidik jari SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean
, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa apakah sidik jari sertifikat yang diekspor cocok dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, itu mungkin salah satu dari berikut ini:
- Sertifikat lama.
- Sebuah sertifikat pengembang diekspor untuk pengguna root. Ekspor sertifikat untuk kasus ini.
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 atau SDK 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 oleh UseHttpsRedirection, mengalami kegagalan pada ERR_INVALID_REDIRECT
dalam permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection
untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya gunakan ASP.NET Core untuk aplikasi web produksi.
- 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.
Gunakan Pengalihan HTTPS
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 variabel lingkungan
ASPNETCORE_HTTPS_PORT
atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penyimpanan tautan dapat menyebabkan perilaku 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_port
pengaturan host:Dalam pengaturan host.
Dengan mengatur
ASPNETCORE_HTTPS_PORT
variabel 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 yang mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core menetapkan URL HTTPS di dalam
Properties/launchsettings.json
untuk keduanya, yaitu Kestrel dan IIS Express.launchsettings.json
hanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penerapan tepi yang menghadap publik dari server Kestrel atau server HTTP.sys. 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 Forwarded Headers Middleware sebelum memanggil HTTPS Redirection Middleware. Middleware Header yang Diteruskan memperbarui Request.Scheme
, dengan menggunakan header X-Forwarded-Proto
. 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 mengalami loop 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
Kode berikut yang disorot memanggil AddHttpsRedirection 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();
Memanggil AddHttpsRedirection
hanya diperlukan untuk mengubah nilai dari HttpsPort
atau RedirectStatusCode
.
Kode yang disorot sebelumnya:
-
HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang dari kelas StatusCodes untuk penugasan ke
RedirectStatusCode
. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen di lingkungan produksi
Middleware secara default mengirimkan Status307TemporaryRedirect pada 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 untuk 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 Middleware Penulisan Ulang URL.
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 yang bersifat opsional 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 HstsOptions.MaxAge ke nilai kecil menggunakan salah satu TimeSpan 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 pramuat dari header
Strict-Transport-Security
. Pra-muat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk pra-muat situs HSTS pada instalasi baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-age
parameterStrict-Transport-Security
header menjadi 60 hari. Jika tidak diatur, secara otomatis diatur menjadi 30 hari. Untuk informasi selengkapnya, lihat direktif max-age. - Menambahkan
example.com
ke daftar host untuk dikecualikan.
UseHsts
mengecualikan host loopback berikut ini:
-
localhost
: Alamat balik IPv4. -
127.0.0.1
: Alamat balik IPv4. -
[::1]
: Alamat loopback IPv6 tersebut.
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 dotnet new 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 penggunaan 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 tentang alat dotnet dev-certs
.
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 peningkatan hak akses. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE
variabel lingkungan ke false
sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewatkan pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman pertama menjalankan 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 bagian Percayai sertifikat menggunakan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
Kebijakan dalam file sebelumnya menyebabkan Firefox mempercayai sertifikat dari sertifikat yang dipercayai di dalam simpanan 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:config
di 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 bergantung pada distribusi dan browser tertentu. 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 folder
ca-certificates
, menggunakan lingkungan pengguna saat ini. - Menghapus penanda
-E
mengekspor sertifikat root, dan menghasilkan sertifikat tersebut jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudo
dan-E
tidak 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:
Instal
libnss3-tools
untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdb
folder 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 PEM
Jalur 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.crt
Keluar 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 PEM
Jalur 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.json
dengan 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 pada 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$ --trust
$CREDENTIAL_PLACEHOLDER$
adalah 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 yang dijelaskan 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 ASP.NET Core 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 jendela browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya 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 tercantum di bawah ini.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan larutan tersebut. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpan sertifikat. Harus ada
localhost
sertifikat dengan nama ramahASP.NET Core HTTPS development certificate
di bawahCurrent User > Personal > Certificates
danCurrent User > Trusted root certification authorities > Certificates
- Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi root "Personal" dan "Tepercaya". Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 ada simbol
+
pada ikon untuk menunjukkan bahwa itu tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 HTTPS Kestrel adalah sidik jari SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean
, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa apakah sidik jari sertifikat yang diekspor cocok dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, itu mungkin salah satu dari berikut ini:
- Sertifikat lama.
- Sebuah sertifikat pengembang diekspor untuk pengguna root. Ekspor sertifikat untuk kasus ini.
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 untuk dapat dipercaya
Dalam beberapa kasus, kebijakan grup mungkin mencegah sertifikat yang ditandatangani sendiri tidak dapat dipercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
Catatan
Jika Anda menggunakan .NET 9 atau SDK 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 oleh UseHttpsRedirection, mengalami kegagalan pada ERR_INVALID_REDIRECT
dalam permintaan preflight CORS.
Proyek API dapat menolak permintaan HTTP daripada menggunakan UseHttpsRedirection
untuk mengalihkan permintaan ke HTTPS.
Memerlukan HTTPS
Sebaiknya gunakan ASP.NET Core untuk aplikasi web produksi.
- 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.
Gunakan Pengalihan HTTPS
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 variabel lingkungan
ASPNETCORE_HTTPS_PORT
atau IServerAddressesFeature.
Sebaiknya gunakan pengalihan sementara daripada pengalihan permanen. Penyimpanan tautan dapat menyebabkan perilaku 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_port
pengaturan host:Dalam pengaturan host.
Dengan mengatur
ASPNETCORE_HTTPS_PORT
variabel 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 yang mengonfigurasi server. Middleware secara tidak langsung menemukan port HTTPS melalui IServerAddressesFeature. Pendekatan ini tidak berfungsi dalam penyebaran proksi terbalik.
Templat web ASP.NET Core menetapkan URL HTTPS di dalam
Properties/launchsettings.json
untuk keduanya, yaitu Kestrel dan IIS Express.launchsettings.json
hanya digunakan pada komputer lokal.Konfigurasikan titik akhir URL HTTPS untuk penerapan tepi yang menghadap publik dari server Kestrel atau server HTTP.sys. 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 Forwarded Headers Middleware sebelum memanggil HTTPS Redirection Middleware. Middleware Header yang Diteruskan memperbarui Request.Scheme
, dengan menggunakan header X-Forwarded-Proto
. 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 mengalami loop 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
Kode berikut yang disorot memanggil AddHttpsRedirection 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();
Memanggil AddHttpsRedirection
hanya diperlukan untuk mengubah nilai dari HttpsPort
atau RedirectStatusCode
.
Kode yang disorot sebelumnya:
-
HttpsRedirectionOptions.RedirectStatusCode Mengatur ke Status307TemporaryRedirect, yang merupakan nilai default. Gunakan bidang dari kelas StatusCodes untuk penugasan ke
RedirectStatusCode
. - Mengatur port HTTPS ke 5001.
Mengonfigurasi pengalihan permanen di lingkungan produksi
Middleware secara default mengirimkan Status307TemporaryRedirect pada 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 untuk 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 Middleware Penulisan Ulang URL.
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 yang bersifat opsional 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 HstsOptions.MaxAge ke nilai kecil menggunakan salah satu TimeSpan 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 pramuat dari header
Strict-Transport-Security
. Pra-muat bukan bagian dari spesifikasi RFC HSTS, tetapi didukung oleh browser web untuk pra-muat situs HSTS pada instalasi baru. Untuk informasi selengkapnya, lihat https://hstspreload.org/ . - Mengaktifkan includeSubDomain, yang menerapkan kebijakan HSTS ke subdomain Host.
- Secara eksplisit mengatur
max-age
parameterStrict-Transport-Security
header menjadi 60 hari. Jika tidak diatur, secara otomatis diatur menjadi 30 hari. Untuk informasi selengkapnya, lihat direktif max-age. - Menambahkan
example.com
ke daftar host untuk dikecualikan.
UseHsts
mengecualikan host loopback berikut ini:
-
localhost
: Alamat balik IPv4. -
127.0.0.1
: Alamat balik IPv4. -
[::1]
: Alamat loopback IPv6 tersebut.
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 dotnet new 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 penggunaan 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 tentang alat dotnet dev-certs
.
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 peningkatan hak akses. Untuk membantu mencegah hal ini, atur DOTNET_GENERATE_ASPNET_CERTIFICATE
variabel lingkungan ke false
sebelum memanggil .NET CLI untuk pertama kalinya. Ini akan melewatkan pembuatan otomatis sertifikat pengembangan ASP.NET Core selama pengalaman pertama menjalankan 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 bagian Percayai sertifikat menggunakan Firefox di Linux di artikel ini.
Tambahkan JSON berikut ke file kebijakan Firefox:
{
"policies": {
"Certificates": {
"ImportEnterpriseRoots": true
}
}
}
Kebijakan dalam file sebelumnya menyebabkan Firefox mempercayai sertifikat dari sertifikat yang dipercayai di dalam simpanan 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:config
di 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 bergantung pada distribusi dan browser tertentu. 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 folder
ca-certificates
, menggunakan lingkungan pengguna saat ini. - Menghapus penanda
-E
mengekspor sertifikat root, dan menghasilkan sertifikat tersebut jika perlu. Setiap sertifikat yang baru dibuat memiliki thumbprint yang berbeda. Saat berjalan sebagai root,sudo
dan-E
tidak 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:
Instal
libnss3-tools
untuk distribusi Anda.Membuat atau memverifikasi
$HOME/.pki/nssdb
folder 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 PEM
Jalur 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.crt
Keluar 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 PEM
Jalur 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.json
dengan 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 pada 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$ --trust
$CREDENTIAL_PLACEHOLDER$
adalah 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 yang dijelaskan 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 ASP.NET Core 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 jendela browser apa pun yang terbuka. Buka jendela browser baru ke aplikasi. Sertifikat kepercayaannya 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 tercantum di bawah ini.
Docker - sertifikat tidak tepercaya
- Hapus folder C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
- Bersihkan larutan tersebut. Hapus folder bin dan obj.
- Mulai ulang alat pengembangan. Misalnya, Visual Studio atau Visual Studio Code.
Windows - sertifikat tidak tepercaya
- Periksa sertifikat di penyimpan sertifikat. Harus ada
localhost
sertifikat dengan nama ramahASP.NET Core HTTPS development certificate
di bawahCurrent User > Personal > Certificates
danCurrent User > Trusted root certification authorities > Certificates
- Hapus semua sertifikat yang ditemukan dari otoritas sertifikasi root "Personal" dan "Tepercaya". Jangan hapus sertifikat localhost IIS Express.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 ada simbol
+
pada ikon untuk menunjukkan bahwa itu tepercaya untuk semua pengguna. - Hapus sertifikat dari rantai kunci sistem.
- Jalankan perintah berikut:
dotnet dev-certs https --clean
dotnet dev-certs https --trust
Tutup jendela 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 HTTPS Kestrel adalah sidik jari SHA1. Ketika file dihapus melalui dotnet dev-certs https --clean
, file akan diregenerasi saat diperlukan dengan thumbprint yang berbeda.
Periksa apakah sidik jari sertifikat yang diekspor cocok dengan perintah berikut:
openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
Jika sertifikat tidak cocok, itu mungkin salah satu dari berikut ini:
- Sertifikat lama.
- Sebuah sertifikat pengembang diekspor untuk pengguna root. Ekspor sertifikat untuk kasus ini.
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 untuk dapat dipercaya
Dalam beberapa kasus, kebijakan grup mungkin mencegah sertifikat yang ditandatangani sendiri tidak dapat dipercaya. Untuk informasi lebih lanjut, lihat masalah GitHub ini.
Informasi Tambahan
ASP.NET Core