Bagikan melalui


Menerapkan HTTPS di ASP.NET Core

Oleh David Galvan dan Rick Anderson

artikel ini memperlihatkan cara:

  • Memerlukan HTTPS untuk semua permintaan.
  • Mengalihkan semua permintaan HTTP ke HTTPS.

Tidak ada API yang dapat mencegah klien mengirim data sensitif pada permintaan pertama.

Peringatan

Proyek API

Jangan gunakan RequireHttpsAttribute pada API Web yang menerima informasi sensitif. RequireHttpsAttribute menggunakan kode status HTTP untuk mengalihkan browser dari HTTP ke HTTPS. Klien API mungkin tidak memahami atau mematuhi pengalihan dari HTTP ke HTTPS. Klien tersebut dapat mengirim informasi melalui HTTP. API Web harus:

  • Tidak mendengarkan di HTTP.
  • Tutup koneksi dengan kode status 400 (Permintaan Buruk) dan tidak melayani permintaan.

Untuk menonaktifkan pengalihan HTTP dalam API, atur ASPNETCORE_URLS variabel lingkungan atau gunakan --urls bendera baris perintah. Untuk informasi selengkapnya, lihat Menggunakan beberapa lingkungan di ASP.NET Core dan 8 cara untuk mengatur URL untuk aplikasi ASP.NET Core oleh Andrew Lock.

Proyek HSTS dan API

Proyek API default tidak menyertakan HSTS karena HSTS umumnya hanya merupakan instruksi browser. Penelepon lain, seperti aplikasi telepon atau desktop, tidak mematuhi instruksi. Bahkan dalam browser, satu panggilan terautentikasi ke API melalui HTTP memiliki risiko pada jaringan yang tidak aman. Pendekatan aman adalah mengonfigurasi proyek API untuk hanya mendengarkan dan merespons melalui HTTPS.

Pengalihan HTTP ke HTTPS menyebabkan ERR_INVALID_REDIRECT pada permintaan preflight CORS

Permintaan ke titik akhir menggunakan HTTP, yang dialihkan ke HTTPS 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:

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 HttpsRedirectionOptions.HttpsPort.

  • Atur https_portpengaturan 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:

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 parameter Strict-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 .

Dialog Aplikasi Web ASP.NET Core baru memperlihatkan kotak centang Konfigurasi untuk HTTPS yang tidak dipilih.

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 ramah ASP.NET Core HTTPS development certificate di bawah Current User > Personal > Certificates dan Current 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:

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 HttpsRedirectionOptions.HttpsPort.

  • Atur https_portpengaturan 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:

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 parameter Strict-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 .

Dialog Aplikasi Web ASP.NET Core baru memperlihatkan kotak centang Konfigurasi untuk HTTPS yang tidak dipilih.

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:

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:

  1. Masukkan about:config di browser FireFox.
  2. Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
  3. Pilih Perlihatkan Semua
  4. Mengeset security.enterprise_roots.enabled = true
  5. 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.

  1. Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.

  2. 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:

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 ramah ASP.NET Core HTTPS development certificate di bawah Current User > Personal > Certificates dan Current 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:

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 HttpsRedirectionOptions.HttpsPort.

  • Atur https_portpengaturan 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:

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 parameter Strict-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 .

Dialog informasi tambahan untuk templat New ASP.NET Core Web App, memperlihatkan 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:

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:

  1. Masukkan about:config di browser FireFox.
  2. Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
  3. Pilih Perlihatkan Semua.
  4. Atur security.enterprise_roots.enabled = true.
  5. 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

  1. Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.

  2. 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 ramah ASP.NET Core HTTPS development certificate di bawah Current User > Personal > Certificates dan Current 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:

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 HttpsRedirectionOptions.HttpsPort.

  • Atur https_portpengaturan 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:

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 parameter Strict-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 .

Dialog Aplikasi Web ASP.NET Core baru memperlihatkan kotak centang Konfigurasi untuk HTTPS yang tidak dipilih.

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:

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:

  1. Masukkan about:config di browser FireFox.
  2. Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
  3. Pilih Perlihatkan Semua
  4. Mengeset security.enterprise_roots.enabled = true
  5. 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.

  1. Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.

  2. 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:

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 ramah ASP.NET Core HTTPS development certificate di bawah Current User > Personal > Certificates dan Current 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:

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 HttpsRedirectionOptions.HttpsPort.

  • Atur https_portpengaturan 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:

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 parameter Strict-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 .

Dialog Aplikasi Web ASP.NET Core baru memperlihatkan kotak centang Konfigurasi untuk HTTPS yang tidak dipilih.

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:

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:

  1. Masukkan about:config di browser FireFox.
  2. Pilih Terima Risiko dan Lanjutkan jika Anda menerima risiko.
  3. Pilih Perlihatkan Semua
  4. Mengeset security.enterprise_roots.enabled = true
  5. 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.

  1. Instal OpenSSL 1.1.1h atau yang lebih baru. Lihat distribusi Anda untuk petunjuk tentang cara memperbarui OpenSSL.

  2. 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:

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 ramah ASP.NET Core HTTPS development certificate di bawah Current User > Personal > Certificates dan Current 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