Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel

Artikel
02/04/2025

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 9 dari artikel ini.

Kestrel endpoint menyediakan infrastruktur untuk menerima permintaan masuk dan mengarahkannya ke middleware yang tepat. Kombinasi alamat dan protokol menentukan titik akhir.

Alamat menentukan antarmuka jaringan yang digunakan server untuk mendengarkan permintaan masuk, seperti port TCP.
Protokol menentukan komunikasi antara klien dan server, seperti HTTP/1.1, HTTP/2, atau HTTP/3.
Titik akhir dapat diamankan menggunakan https skema atau UseHttps metode URL.

Titik akhir dapat dikonfigurasi menggunakan URL, JSON di appsettings.json, dan kode. Artikel ini membahas cara menggunakan setiap opsi untuk mengonfigurasi titik akhir:

Mengonfigurasi titik akhir
Mengonfigurasi HTTPS
Mengonfigurasi protokol HTTP

Titik akhir bawaan

Proyek ASP.NET Core baru dikonfigurasi untuk mengikat port HTTP acak antara 5000-5300 dan port HTTPS acak antara 7000-7300. Port yang dipilih disimpan dalam file yang dihasilkan dan dapat dimodifikasi Properties/launchSettings.json oleh pengembang. File launchSetting.json hanya digunakan dalam pengembangan lokal.

Jika tidak ada konfigurasi titik akhir, maka Kestrel ikat ke http://localhost:5000.

Mengonfigurasi titik akhir

Kestrel titik akhir mendengarkan koneksi masuk. Saat titik akhir dibuat, itu harus dikonfigurasi dengan alamat yang akan didengarkannya. Biasanya, ini adalah alamat TCP dan nomor port.

Ada beberapa opsi untuk mengonfigurasi titik akhir:

Mengonfigurasi titik akhir dengan URL
Tentukan port saja
Mengonfigurasi titik akhir di appsettings.json
Mengonfigurasi titik akhir dalam kode

Mengonfigurasi titik akhir dengan URL

Bagian berikut menjelaskan cara mengonfigurasi titik akhir menggunakan:

ASPNETCORE_URLS variabel lingkungan.
--urls argumen baris perintah.
urls kunci konfigurasi host.
UseUrls metode perpanjangan.
WebApplication.Urls properti.

Format URL

URL menunjukkan alamat IP atau host beserta port dan protokol tempat server harus mendengarkan. Port dapat dihilangkan jika merupakan default untuk protokol (biasanya 80 dan 443). URL dapat berada dalam salah satu format berikut.

Alamat IPv4 dengan nomor port
```
http://65.55.39.10:80/
```
0.0.0.0 adalah kasus khusus yang mengikat semua alamat IPv4.
Alamat IPv6 dengan nomor port
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] adalah IPv6 setara dengan IPv4 0.0.0.0.
Host wildcard dengan nomor port
```
http://contoso.com:80/
http://*:80/
```
Apa pun yang tidak dikenali sebagai alamat IP yang valid atau localhost diperlakukan sebagai wildcard yang mengikat semua alamat IPv4 dan IPv6. Beberapa orang suka menggunakan * atau + menjadi lebih eksplisit. Untuk mengikat nama host yang berbeda ke aplikasi ASP.NET Core yang berbeda pada port yang sama, gunakan HTTP.sys atau server proksi terbalik.

Contoh server proksi terbalik termasuk IIS, YARP, Nginx, dan Apache.
Nama host localhost dengan nomor port atau IP loopback dengan nomor port
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Ketika localhost ditentukan, Kestrel mencoba mengikat ke kedua antarmuka loopback IPv4 dan IPv6. Jika port yang diminta sedang digunakan oleh layanan lain pada antarmuka loopback, Kestrel gagal memulai. Jika antarmuka loopback tidak tersedia karena alasan lain (paling umum karena IPv6 tidak didukung), Kestrel catat peringatan.

Beberapa awalan URL dapat ditentukan dengan menggunakan pemisah titik koma (;):

http://*:5000;http://localhost:5001;https://hostname:5002

Untuk informasi selengkapnya, lihat Konfigurasi Override.

Awalan URL HTTPS

Awalan URL HTTPS dapat digunakan untuk menentukan titik akhir hanya jika sertifikat default disediakan dalam konfigurasi titik akhir HTTPS. Misalnya, gunakan KestrelServerOptions konfigurasi atau file konfigurasi, seperti yang ditunjukkan nanti di artikel ini.

Untuk informasi selengkapnya, lihat Mengonfigurasi HTTPS.

Tentukan port saja

Aplikasi dan kontainer sering kali hanya diberikan port untuk memantau, seperti port 80, tanpa batasan tambahan seperti host atau path. HTTP_PORTS dan HTTPS_PORTS adalah kunci konfigurasi yang menentukan port mendengarkan untuk server Kestrel dan HTTP.sys. Kunci ini dapat ditentukan sebagai variabel lingkungan yang ditentukan dengan awalan DOTNET_ atau ASPNETCORE_ , atau ditentukan langsung melalui input konfigurasi lainnya, seperti appsettings.json. Masing-masing adalah daftar nilai port yang dibatasi titik koma, seperti yang ditunjukkan dalam contoh berikut:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Contoh sebelumnya adalah singkatan dari konfigurasi berikut, yang menentukan skema (HTTP atau HTTPS) dan host atau IP apa pun.

ASPNETCORE_URLS=http://*:80/;http://*:8080/;https://*:443/;https://*:8081/

Kunci konfigurasi HTTP_PORTS dan HTTPS_PORTS berprioritas lebih rendah dan ditimpa oleh URL atau nilai yang disediakan langsung dalam kode. Sertifikat masih perlu dikonfigurasi secara terpisah melalui mekanisme khusus server untuk HTTPS.

Mengonfigurasi titik akhir di appsettings.json

Kestrel dapat memuat endpoint dari instance IConfiguration. Secara default, konfigurasi Kestrel dimuat dari bagian Kestrel dan endpoint dikonfigurasi di Kestrel:Endpoints:

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpEndpoint": {
        "Url": "http://localhost:8080"
      }
    }
  }
}

Contoh sebelumnya:

Menggunakan appsettings.json sebagai sumber konfigurasi. Namun, sumber apa pun IConfiguration dapat digunakan.
Menambahkan titik akhir bernama MyHttpEndpoint pada port 8080.

Untuk informasi selengkapnya tentang mengonfigurasi titik akhir dengan JSON, lihat bagian selanjutnya dalam artikel ini yang membahas mengonfigurasi HTTPS dan mengonfigurasi protokol HTTP di appsettings.json.

Memuat ulang titik akhir dari konfigurasi

Memuat ulang konfigurasi titik akhir saat sumber konfigurasi berubah diaktifkan secara default. Ini dapat dinonaktifkan menggunakan KestrelServerOptions.Configure(IConfiguration, Boolean).

Jika perubahan disinyalir, langkah-langkah berikut diambil:

Konfigurasi baru dibandingkan dengan yang lama, dan titik akhir apa pun tanpa perubahan konfigurasi tidak dimodifikasi.
Titik akhir yang dihapus atau dimodifikasi diberi waktu 5 detik untuk menyelesaikan permintaan pemrosesan dan dimatikan.
Titik akhir baru atau yang dimodifikasi telah dimulai.

Klien yang terhubung ke titik akhir yang dimodifikasi mungkin terputus atau ditolak saat titik akhir dimulai ulang.

ConfigurationLoader

KestrelServerOptions.Configure mengembalikan KestrelConfigurationLoader. Metode loader Endpoint(String, Action<EndpointConfiguration>) yang dapat digunakan untuk melengkapi pengaturan endpoint yang telah dikonfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader dapat langsung diakses untuk terus melakukan iterasi pada loader yang ada, seperti yang disediakan oleh WebApplicationBuilder.WebHost.

Bagian konfigurasi untuk setiap titik akhir tersedia pada opsi dalam Endpoint metode sehingga pengaturan kustom dapat dibaca.
KestrelServerOptions.Configure(IConfiguration) dapat dipanggil beberapa kali, tetapi hanya konfigurasi terakhir yang digunakan kecuali Load secara eksplisit dipanggil pada instans sebelumnya. Host default tidak memanggil Load sehingga bagian konfigurasi defaultnya dapat diganti.
KestrelConfigurationLoader mencerminkan keluarga API Listen dari KestrelServerOptions sebagai Endpoint overload, sehingga titik akhir kode dan konfigurasi dapat dikonfigurasi di tempat yang sama. Kelebihan beban ini tidak menggunakan nama dan hanya menggunakan pengaturan default dari konfigurasi.

Mengonfigurasi titik akhir dalam kode

KestrelServerOptions menyediakan metode untuk mengonfigurasi titik akhir dalam kode:

Ketika Listen API dan UseUrls API digunakan secara bersamaan, endpoint Listen akan mengambil alih endpoint UseUrls.

Ikat ke soket TCP

Metode Listen, ListenLocalhost, dan ListenAnyIP mengikat soket TCP:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Contoh sebelumnya:

Mengonfigurasi titik akhir yang menerima koneksi pada port 5000 dan 5001.
Mengonfigurasi HTTPS untuk endpoint dengan metode ekstensi UseHttps pada ListenOptions. Untuk informasi selengkapnya, lihat Mengonfigurasi HTTPS dalam kode.

Di Windows, sertifikat yang ditandatangani sendiri dapat dibuat menggunakan New-SelfSignedCertificate cmdlet PowerShell. Untuk contoh yang tidak didukung, lihat UpdateIISExpressSSLForChrome.ps1.

Di macOS, Linux, dan Windows, sertifikat dapat dibuat menggunakan OpenSSL.

Ikat ke soket Unix

Dengarkan soket Unix dengan ListenUnixSocket untuk meningkatkan performa dengan Nginx, seperti yang ditunjukkan dalam contoh ini:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Dalam file konfigurasi Nginx, atur entri ke server>location>proxy_passhttp://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} adalah nama soket yang disediakan untuk ListenUnixSocket (misalnya, kestrel-test.sock dalam contoh sebelumnya).
Pastikan bahwa soket dapat ditulis oleh Nginx (misalnya, chmod go+w /tmp/kestrel-test.sock).

Mengonfigurasi setelan awal endpoint

ConfigureEndpointDefaults(Action<ListenOptions>) menentukan konfigurasi yang berjalan untuk setiap titik akhir yang ditentukan. Memanggil ConfigureEndpointDefaults beberapa kali mengganti konfigurasi yang sudah ada.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.

Pengikatan port dinamis

Ketika nomor 0 port ditentukan, Kestrel secara dinamis mengikat ke port yang tersedia. Contoh berikut menunjukkan cara menentukan port Kestrel mana yang terikat pada runtime:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Mengikat port secara dinamis tidak tersedia dalam keadaan tertentu.

KestrelServerOptions.ListenLocalhost
Mengikat HTTP/1.1 atau HTTP/2 berbasis TCP, dan HTTP/3 berbasis QUIC bersama-sama.

Mengonfigurasi HTTPS

Kestrel mendukung pengamanan titik akhir dengan HTTPS. Data yang dikirim melalui HTTPS dienkripsi menggunakan Keamanan Lapisan Transportasi (TLS) untuk meningkatkan keamanan data yang ditransfer antara klien dan server.

HTTPS memerlukan sertifikat TLS. Sertifikat TLS disimpan di server, dan Kestrel dikonfigurasi untuk menggunakannya. Aplikasi dapat menggunakan sertifikat pengembangan ASP.NET Core HTTPS di lingkungan pengembangan lokal. Sertifikat pengembangan tidak diinstal di lingkungan bukan pengembangan. Dalam produksi, sertifikat TLS harus dikonfigurasi secara eksplisit. Minimal, sertifikat default harus disediakan.

Cara HTTPS dan sertifikat TLS dikonfigurasi tergantung pada bagaimana titik akhir dikonfigurasi:

Jika awalan URL atau hanya menentukan port digunakan untuk mendefinisikan titik akhir, HTTPS dapat digunakan hanya jika sertifikat default disediakan dalam konfigurasi titik akhir HTTPS. Sertifikat default dapat dikonfigurasi dengan salah satu opsi berikut:
Mengonfigurasi HTTPS di appsettings.json
Mengonfigurasi HTTPS dalam kode

Mengonfigurasi HTTPS di appsettings.json

Skema konfigurasi pengaturan aplikasi HTTPS default tersedia untuk Kestrel. Konfigurasikan beberapa titik akhir, termasuk URL dan sertifikat yang akan digunakan, baik dari file di disk atau dari penyimpanan sertifikat.

Setiap titik akhir HTTPS yang tidak menentukan sertifikat (HttpsDefaultCert dalam contoh berikut) kembali ke sertifikat yang ditentukan di bawah Certificates:Default atau sertifikat pengembangan.

Contoh berikut adalah untuk appsettings.json, tetapi sumber konfigurasi apa pun dapat digunakan:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Dalam contoh sebelumnya, kata sandi sertifikat disimpan dalam teks biasa di appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ digunakan sebagai tempat penampung untuk kata sandi sertifikat. Untuk menyimpan kata sandi sertifikat dengan aman di lingkungan pengembangan, lihat Melindungi rahasia dalam pengembangan. Untuk menyimpan kata sandi sertifikat dengan aman di lingkungan produksi, lihat Penyedia konfigurasi Azure Key Vault. Rahasia pengembangan tidak boleh digunakan untuk produksi atau pengujian.

Catatan skema

Nama titik akhir tidak sensitif terhadap huruf besar-kecil. Misalnya, HTTPS dan Httpssetara.
Parameter Url diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkat Urls atas kecuali bahwa parameter tersebut terbatas pada satu nilai. Lihat format URL sebelumnya di artikel ini.
Titik akhir ini menggantikan yang ditentukan dalam konfigurasi Urls tingkat atas alih-alih menambahkannya. Titik akhir yang ditentukan dalam kode melalui Listen bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi.
Bagian Certificate ini bersifat opsional. Jika bagian Certificate tidak ditentukan, default yang didefinisikan dalam Certificates:Default akan digunakan. Jika tidak ada default yang tersedia, sertifikat pengembangan akan digunakan. Jika tidak ada default dan sertifikat pengembangan tidak ada, server akan melempar pengecualian dan gagal memulai.
Bagian ini Certificate mendukung beberapa sumber sertifikat.
Sejumlah titik akhir dapat didefinisikan dalam Configuration, selama tidak menyebabkan konflik port.

Sumber sertifikat

Simpul sertifikat dapat dikonfigurasi untuk memuat sertifikat dari sejumlah sumber:

Path dan Password untuk memuat file .pfx .
Path, KeyPath dan Password untuk memuat .pem/, .crt dan .key files.
Subject dan Store untuk memuat dari penyimpanan sertifikat.

Misalnya, Certificates:Default sertifikat dapat ditentukan sebagai:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

Mengonfigurasi sertifikat klien di appsettings.json

ClientCertificateMode digunakan untuk mengonfigurasi perilaku sertifikat klien.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai defaultnya adalah ClientCertificateMode.NoCertificate, di mana Kestrel tidak meminta atau memerlukan sertifikat dari klien.

Untuk informasi selengkapnya, lihat Mengonfigurasi autentikasi sertifikat di ASP.NET Core.

Mengonfigurasi protokol SSL/TLS di appsettings.json

Protokol SSL adalah protokol yang digunakan untuk mengenkripsi dan mendekripsi lalu lintas antara dua rekan, secara tradisional klien dan server.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default, SslProtocols.None, menyebabkan Kestrel menggunakan default sistem operasi untuk memilih protokol terbaik. Kecuali Anda memiliki alasan khusus untuk memilih protokol, gunakan default.

Mengonfigurasi HTTPS dalam kode

Saat menggunakan Listen API, metode ekstensi UseHttps pada ListenOptions tersedia untuk mengonfigurasi HTTPS.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

ListenOptions.UseHttps Parameter:

filename adalah jalur dan nama file file sertifikat, relatif terhadap direktori yang berisi file konten aplikasi.
password adalah kata sandi yang diperlukan untuk mengakses data sertifikat X.509.
configureOptions Action adalah untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
storeName merupakan tempat penyimpanan sertifikat dari mana sertifikat dimuat.
subject adalah nama subjek untuk sertifikat.
allowInvalid menunjukkan apakah sertifikat yang tidak valid harus dipertimbangkan, seperti sertifikat yang ditandatangani sendiri.
location adalah lokasi penyimpanan untuk memuat sertifikat.
serverCertificate adalah sertifikat X.509.

Untuk daftar UseHttps lengkap kelebihan beban, lihat UseHttps.

Mengonfigurasi sertifikat klien dalam kode

ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

Nilai defaultnya adalah NoCertificate, di mana Kestrel tidak meminta atau memerlukan sertifikat dari klien.

Untuk informasi selengkapnya, lihat Mengonfigurasi autentikasi sertifikat di ASP.NET Core.

Konfigurasi default HTTPS dalam kode

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir HTTPS. Memanggil ConfigureHttpsDefaults beberapa kali menggantikan instans Action sebelumnya dengan Action terakhir yang ditentukan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.

Mengonfigurasi protokol SSL/TLS dalam kode

Protokol SSL adalah protokol yang digunakan untuk mengenkripsi dan mendekripsi lalu lintas antara dua rekan, secara tradisional klien dan server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

Mengonfigurasi filter suite sandi TLS dalam kode

Di Linux, CipherSuitesPolicy dapat digunakan untuk memfilter jabat tangan TLS berdasarkan per koneksi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Mengonfigurasi Indikasi Nama Server

Indikasi Nama Server (SNI) dapat digunakan untuk menghosting beberapa domain pada alamat IP dan port yang sama. SNI dapat digunakan untuk menghemat sumber daya dengan melayani beberapa situs dari satu server.

Agar SNI berfungsi, klien mengirim nama host untuk sesi aman ke server selama jabat tangan TLS sehingga server dapat memberikan sertifikat yang benar. Klien menggunakan sertifikat yang dilengkapi untuk komunikasi terenkripsi dengan server selama sesi aman yang mengikuti jabat tangan TLS.

Semua situs web harus berjalan pada instans yang sama Kestrel . Kestrel tidak mendukung berbagi penggunaan alamat IP dan port antara beberapa instans tanpa menggunakan proksi terbalik.

SNI dapat dikonfigurasi dengan dua cara:

Konfigurasikan pemetaan antara nama host dan opsi HTTPS di Konfigurasi. Misalnya, JSON dalam appsettings.json file.
Buat titik akhir dalam kode dan pilih sertifikat menggunakan nama host dengan ServerCertificateSelector callback.

Mengonfigurasi SNI pada appsettings.json

Kestrel mendukung SNI yang ditentukan dalam konfigurasi. Titik akhir dapat dikonfigurasi dengan Sni objek yang berisi pemetaan antara nama host dan opsi HTTPS. Nama host koneksi dicocokkan dengan opsi dan digunakan untuk koneksi tersebut.

Konfigurasi berikut menambahkan titik akhir bernama MySniEndpoint yang menggunakan SNI untuk memilih opsi HTTPS berdasarkan nama host:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Opsi HTTPS yang dapat diubah oleh SNI:

Certificate mengonfigurasi sumber sertifikat.
Protocolsmengonfigurasi protokol HTTP yang diizinkan.
SslProtocolsmengonfigurasi protokol SSL yang diizinkan.
ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

Nama host mendukung pencocokan kartubebas:

Kecocokan persis. Misalnya, a.example.org cocok dengan a.example.org.
Awalan karakter pengganti. Jika ada beberapa kecocokan pengganti, maka pola terpanjang dipilih. Misalnya, *.example.org cocok dengan b.example.org dan c.example.org.
Kartubebas penuh. * cocok dengan semua hal lainnya, termasuk klien yang tidak menggunakan SNI dan tidak mengirimkan nama host.

Konfigurasi SNI yang cocok diterapkan ke titik akhir untuk koneksi, menggantikan nilai pada titik akhir. Jika koneksi tidak cocok dengan nama host SNI yang dikonfigurasi, maka koneksi ditolak.

Mengonfigurasi SNI dengan kode

Kestrel mendukung SNI dengan beberapa API panggilan balik:

ServerCertificateSelector
ServerOptionsSelectionCallback
TlsHandshakeCallbackOptions

SNI dengan `ServerCertificateSelector`

Kestrel mendukung SNI dengan panggilan balik ServerCertificateSelector. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat yang sesuai:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI dengan `ServerOptionsSelectionCallback`

Kestrel mendukung konfigurasi TLS dinamis tambahan melalui ServerOptionsSelectionCallback panggilan balik. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat dan konfigurasi TLS yang sesuai. Sertifikat default dan ConfigureHttpsDefaults tidak digunakan dengan panggilan balik ini.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI dengan `TlsHandshakeCallbackOptions`

Kestrel mendukung konfigurasi TLS dinamis tambahan melalui TlsHandshakeCallbackOptions.OnConnection panggilan balik. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat yang sesuai, konfigurasi TLS, dan opsi server lainnya. Sertifikat default dan ConfigureHttpsDefaults tidak digunakan dengan panggilan balik ini.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

Konfigurasi protokol HTTP

Kestrel mendukung semua versi HTTP yang umum digunakan. Titik akhir dapat dikonfigurasi untuk mendukung versi HTTP yang berbeda menggunakan HttpProtocols enum, yang menentukan opsi versi HTTP yang tersedia.

TLS diperlukan untuk mendukung lebih dari satu versi HTTP. Jabat tangan TLS Application-Layer Protocol Negotiation (ALPN) digunakan untuk menegosiasikan protokol koneksi antara klien dan server ketika titik akhir mendukung beberapa protokol.

`HttpProtocols` nilai	Protokol koneksi diizinkan
`Http1`	HTTP/1.1 saja. Dapat digunakan dengan atau tanpa TLS.
`Http2`	Hanya HTTP/2. Dapat digunakan tanpa TLS hanya jika klien mendukung mode Pengetahuan Sebelumnya.
`Http3`	Hanya HTTP/3. Membutuhkan TLS. Klien mungkin perlu dikonfigurasi untuk menggunakan HTTP/3 saja.
`Http1AndHttp2`	HTTP/1.1 dan HTTP/2. HTTP/2 mengharuskan klien untuk memilih HTTP/2 dalam Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS dalam jabat tangan; jika tidak, koneksi default ke HTTP/1.1.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 dan HTTP/3. Permintaan klien pertama biasanya menggunakan HTTP/1.1 atau HTTP/2, dan `alt-svc` header respons meminta klien untuk meningkatkan ke HTTP/3. HTTP/2 dan HTTP/3 memerlukan TLS; jika tidak, koneksi default ke HTTP/1.1.

Nilai protokol default untuk titik akhir adalah HttpProtocols.Http1AndHttp2.

Pembatasan TLS untuk HTTP/2:

TLS versi 1.2 atau yang lebih baru
Negosiasi ulang dinonaktifkan
Pemadatan dinonaktifkan
Ukuran minimum pertukaran kunci sementara
- Kurva elips Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bit
- Bidang terbatas Diffie-Hellman (DHE) [TLS12]: minimum 2048 bit
Cipher suite tidak dilarang.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] dengan kurva elips P-256 [FIPS186] didukung secara default.

Mengonfigurasi protokol HTTP di appsettings.json

Contoh berikut appsettings.json menetapkan protokol koneksi HTTP/1.1 untuk titik akhir tertentu:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokol default dapat dikonfigurasi di bagian .Kestrel:EndpointDefaults Contoh berikut appsettings.json menetapkan HTTP/1.1 sebagai protokol koneksi default untuk semua titik akhir:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Protokol yang ditentukan dalam kode mengesampingkan nilai yang ditetapkan oleh konfigurasi.

Mengonfigurasi protokol HTTP dalam kode

ListenOptions.Protocols digunakan untuk menentukan protokol dengan HttpProtocols enum.

Contoh berikut mengonfigurasi titik akhir untuk koneksi HTTP/1.1, HTTP/2, dan HTTP/3 pada port 8000. Koneksi diamankan oleh TLS dengan sertifikat yang disediakan:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Sesuaikan titik akhir pipa bernama Kestrel

Dukungan named pipe Kestrelmencakup opsi kustomisasi lanjutan. Properti CreateNamedPipeServerStream pada opsi pipa bernama memungkinkan penyesuaian pipa untuk setiap titik akhir.

Ini berguna, misalnya, dalam aplikasi Kestrel yang memerlukan dua titik akhir pipa dengan keamanan akses yang berbeda. Opsi CreateNamedPipeServerStream dapat digunakan untuk membuat pipa dengan pengaturan keamanan kustom, tergantung pada nama pipa.

using System.IO.Pipes;
using System.Security.AccessControl;
using System.Security.Principal;

var builder = WebApplication.CreateBuilder();

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenNamedPipe("defaultPipe");
    options.ListenNamedPipe("securedPipe");
});

builder.WebHost.UseNamedPipes(options =>
{
    options.CreateNamedPipeServerStream = (context) =>
    {
        var pipeName = context.NamedPipeEndPoint.PipeName;
        
        switch (pipeName)
        {
            case "defaultPipe":
                return NamedPipeTransportOptions.CreateDefaultNamedPipeServerStream(context);
            case "securedPipe":
                var allowSecurity = new PipeSecurity();
                allowSecurity.AddAccessRule(new PipeAccessRule("Users", PipeAccessRights.FullControl, AccessControlType.Allow));

                return NamedPipeServerStreamAcl.Create(pipeName, PipeDirection.InOut,
                    NamedPipeServerStream.MaxAllowedServerInstances, PipeTransmissionMode.Byte,
                    context.PipeOptions, inBufferSize: 0, outBufferSize: 0, allowSecurity);
            default:
                throw new InvalidOperationException($"Unexpected pipe name: {pipeName}");
        }
    };
});

var app = builder.Build();

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

app.Run();

Lihat juga

ASP.NET Core dikonfigurasi untuk mengikat port HTTP acak antara 5000-5300 dan port HTTPS acak antara 7000-7300. Konfigurasi default ini ditentukan dalam file yang dihasilkan Properties/launchSettings.json dan dapat diubah. Jika tidak ada port yang ditentukan, Kestrel ikat ke http://localhost:5000.

Tentukan URL menggunakan:

ASPNETCORE_URLS variabel lingkungan.
--urls argumen baris perintah.
urls kunci konfigurasi host.
UseUrls metode perpanjangan.

Nilai yang disediakan menggunakan pendekatan ini dapat berupa satu atau beberapa titik akhir HTTP dan HTTPS (HTTPS jika sertifikasi default tersedia). Konfigurasikan nilai sebagai daftar yang dipisahkan titik koma (misalnya, "Urls": "http://localhost:8000;http://localhost:8001").

Untuk informasi selengkapnya tentang pendekatan ini, lihat URL Server dan Override konfigurasi.

Sertifikat pengembangan dibuat:

Ketika .NET SDK telah diinstal.
Alat dev-certs digunakan untuk membuat sertifikat.

Sertifikat pengembangan hanya tersedia untuk pengguna yang menghasilkan sertifikat. Beberapa browser memerlukan pemberian izin eksplisit untuk mempercayai sertifikat pengembangan lokal.

Templat proyek mengonfigurasi aplikasi untuk dijalankan di HTTPS secara bawaan dan menyertakan pengalihan HTTPS dan dukungan HSTS.

Panggil metode pada KestrelServerOptions atau ListenUnixSocket untuk mengonfigurasi awalan URL dan port untuk Kestrel.

UseUrls --urls, argumen baris perintah, urls kunci konfigurasi host, dan ASPNETCORE_URLS variabel lingkungan juga berfungsi tetapi memiliki batasan yang dicatat nanti di bagian ini (sertifikat default harus tersedia untuk konfigurasi titik akhir HTTPS).

KestrelServerOptions Konfigurasi:

Mengonfigurasi EndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir yang ditentukan. Memanggil ConfigureEndpointDefaults beberapa kali akan menggantikan Action sebelumnya dengan Action terakhir yang ditentukan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.

Konfigurasikan(IConfiguration)

Kestrel Memungkinkan untuk memuat titik akhir dari IConfiguration. Konfigurasi harus dilingkupkan pada bagian konfigurasi untuk Kestrel. "Overload Configure(IConfiguration, bool) dapat digunakan untuk mengaktifkan pemuatan ulang endpoint ketika sumber konfigurasi berubah."

Secara bawaan, Kestrel konfigurasi dimuat dari bagian Kestrel dan kemampuan memuat ulang perubahan diaktifkan.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Jika konfigurasi muat ulang diaktifkan dan perubahan disinyalir maka langkah-langkah berikut diambil:

Konfigurasi baru dibandingkan dengan yang lama, titik akhir apa pun tanpa perubahan konfigurasi tidak dimodifikasi.
Titik akhir yang dihapus atau dimodifikasi diberi waktu 5 detik untuk menyelesaikan permintaan pemrosesan dan dimatikan.
Titik akhir yang baru atau yang telah dimodifikasi telah dimulai.

Klien yang terhubung ke titik akhir yang dimodifikasi mungkin terputus atau ditolak saat titik akhir dimulai ulang.

MengonfigurasiHttpsDefaults

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir HTTPS. Memanggil ConfigureHttpsDefaults beberapa kali akan menggantikan Action sebelumnya dengan Action terakhir yang ditentukan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.

ListenOptions.UseHttps

Konfigurasikan Kestrel untuk menggunakan HTTPS.

ListenOptions.UseHttps Ekstensi:

UseHttps: Konfigurasikan Kestrel untuk menggunakan HTTPS dengan sertifikat default. Melemparkan pengecualian jika tidak ada sertifikat default yang dikonfigurasi.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps Parameter:

filename adalah jalur dan nama file file sertifikat, relatif terhadap direktori yang berisi file konten aplikasi.
password adalah kata sandi yang diperlukan untuk mengakses data sertifikat X.509.
configureOptions Action digunakan untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
storeName adalah penyimpanan sertifikat dari mana sertifikat dimuat.
subject adalah nama subjek untuk sertifikat.
allowInvalid menunjukkan apakah sertifikat yang tidak valid harus dipertimbangkan, seperti sertifikat yang ditandatangani sendiri.
location adalah lokasi penyimpanan untuk memuat sertifikat.
serverCertificate adalah sertifikat X.509.

Dalam produksi, HTTPS harus dikonfigurasi secara eksplisit. Minimal, sertifikat default harus disediakan.

Jika sertifikat sedang dibaca dari disk, alih-alih dari Penyimpanan Sertifikat Windows, direktori yang berisi harus memiliki izin yang sesuai untuk mencegah akses yang tidak sah.

Konfigurasi yang didukung dijelaskan berikutnya:

Tidak ada konfigurasi
Ganti sertifikat default dari konfigurasi
Mengubah default dalam kode

Tidak ada konfigurasi

Kestrel mendengarkan di http://localhost:5000.

Ganti sertifikat default dari konfigurasi

Dalam contoh berikut appsettings.json :

Atur AllowInvalid ke true untuk mengizinkan penggunaan sertifikat yang tidak valid (misalnya, sertifikat yang ditandatangani sendiri).
Titik akhir HTTPS apa pun yang tidak menentukan sertifikat (HttpsDefaultCert dalam contoh berikut) kembali ke sertifikasi yang ditentukan di bawah Certificates:Default atau sertifikat pengembangan.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Dalam contoh sebelumnya, kata sandi sertifikat disimpan dalam teks biasa di appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ digunakan sebagai tempat penampung untuk setiap kata sandi sertifikat. Untuk menyimpan kata sandi sertifikat dengan aman di lingkungan pengembangan, lihat Melindungi rahasia dalam pengembangan. Untuk menyimpan kata sandi sertifikat dengan aman di lingkungan produksi, lihat Penyedia konfigurasi Azure Key Vault. Rahasia pengembangan tidak boleh digunakan untuk produksi atau pengujian.

Catatan skema:

Nama titik akhir tidak peka huruf besar/kecil. Misalnya, HTTPS dan Httpssetara.
Parameter Url diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkat Urls atas kecuali bahwa parameter tersebut terbatas pada satu nilai.
Endpoint ini menggantikan yang ditentukan dalam konfigurasi tingkat Urls atas, bukan menambahkannya. Titik akhir yang ditentukan dalam kode melalui Listen bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi.
Bagian Certificate ini bersifat opsional. Jika bagian Certificate tidak ditentukan, default yang telah ditentukan di Certificates:Default akan digunakan. Jika tidak ada default yang tersedia, sertifikat pengembangan akan digunakan. Jika tidak ada default dan sertifikat pengembangan tidak ada, server akan melempar pengecualian dan gagal memulai.
Bagian ini Certificate mendukung beberapa sumber sertifikat.
Sejumlah titik akhir dapat didefinisikan dalam Konfigurasi selama tidak menyebabkan konflik port.

Sumber sertifikat

Simpul sertifikat dapat dikonfigurasi untuk memuat sertifikat dari sejumlah sumber:

Path dan Password untuk memuatkan file .pfx.
Path, KeyPath dan Password untuk memuat file .pem, /.crt dan .key.
Subject dan Store untuk memuat dari penyimpanan sertifikat.

Misalnya, Certificates:Default sertifikat dapat ditentukan sebagai:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

Configure(IConfiguration) mengembalikan sebuah KestrelConfigurationLoader dengan metode Endpoint(String, Action<EndpointConfiguration>) yang dapat digunakan untuk melengkapi pengaturan titik akhir yang dikonfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader dapat langsung diakses untuk terus melakukan iterasi pada loader yang ada, seperti yang disediakan oleh WebApplicationBuilder.WebHost.

Bagian konfigurasi untuk setiap titik akhir tersedia pada opsi dalam Endpoint metode sehingga pengaturan kustom dapat dibaca.
Beberapa konfigurasi dapat dimuat dengan memanggil Configure(IConfiguration) lagi menggunakan bagian yang berbeda. Hanya konfigurasi terakhir yang digunakan, kecuali Load secara eksplisit dipanggil pada instans sebelumnya. Metapackage tidak memanggil Load sehingga bagian konfigurasi defaultnya dapat diganti.
KestrelConfigurationLoader mencerminkan Listen keluarga API dari KestrelServerOptions sebagai Endpoint kelebihan beban, sehingga titik akhir kode dan konfigurasi dapat dikonfigurasi di tempat yang sama. Kelebihan beban ini tidak menggunakan nama dan hanya menggunakan pengaturan default dari konfigurasi.

Mengubah default dalam kode

ConfigureEndpointDefaults dan ConfigureHttpsDefaults dapat digunakan untuk mengubah pengaturan default untuk ListenOptions dan HttpsConnectionAdapterOptions, termasuk mengganti sertifikat default yang ditentukan dalam skenario sebelumnya. ConfigureEndpointDefaults dan ConfigureHttpsDefaults harus dipanggil sebelum pengaturan titik akhir.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Mengonfigurasi titik akhir menggunakan Indikasi Nama Server

Indikasi Nama Server (SNI) dapat digunakan untuk menghosting beberapa domain pada alamat IP dan port yang sama. Agar SNI berfungsi, klien mengirim nama host untuk sesi aman ke server selama jabat tangan TLS sehingga server dapat memberikan sertifikat yang benar. Klien menggunakan sertifikat yang dilengkapi untuk komunikasi terenkripsi dengan server selama sesi aman yang mengikuti jabat tangan TLS.

SNI dapat dikonfigurasi dengan dua cara:

Buat endpoint dalam kode dan pilih sertifikat menggunakan nama host dengan callback ServerCertificateSelector.
Konfigurasikan pemetaan antara nama host dan opsi HTTPS di Konfigurasi. Misalnya, JSON dalam appsettings.json file.

SNI dengan `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI dengan `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI dengan `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI dalam konfigurasi

Konfigurasi berikut menambahkan titik akhir bernama MySniEndpoint yang menggunakan SNI untuk memilih opsi HTTPS berdasarkan nama host:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Opsi HTTPS yang dapat digantikan oleh SNI:

Certificate mengonfigurasi sumber sertifikat.
Protocolsmengonfigurasi protokol HTTP yang diizinkan.
SslProtocolsmengonfigurasi protokol SSL yang diizinkan.
ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

Nama host mendukung pencocokan kartubebas:

Kecocokan persis. Misalnya, a.example.org cocok dengan a.example.org.
Awalan wildcard. Jika ada beberapa kecocokan kartubebas maka pola terpanjang dipilih. Misalnya, *.example.org sesuai dengan b.example.org dan c.example.org.
Kartu liar penuh. * cocok dengan semua hal lainnya, termasuk klien yang tidak menggunakan SNI dan tidak mengirimkan nama host.

Konfigurasi SNI yang cocok diterapkan ke titik akhir untuk koneksi, mengambil alih nilai pada titik akhir. Jika koneksi tidak cocok dengan nama host SNI yang dikonfigurasi, koneksi ditolak.

Persyaratan SNI

Semua situs web harus berjalan pada instans yang sama Kestrel . Kestrel tidak mendukung berbagi alamat IP dan port di beberapa instans tanpa proksi terbalik.

Protokol SSL/TLS

Protokol SSL adalah protokol yang digunakan untuk mengenkripsi dan mendekripsi lalu lintas antara dua rekan, secara tradisional klien dan server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default, SslProtocols.None, menyebabkan Kestrel menggunakan default sistem operasi untuk memilih protokol terbaik. Kecuali Anda memiliki alasan khusus untuk memilih protokol, gunakan default.

Sertifikat Klien

ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default adalah ClientCertificateMode.NoCertificate di mana Kestrel tidak akan meminta atau memerlukan sertifikat dari klien.

Untuk informasi selengkapnya, lihat Mengonfigurasi autentikasi sertifikat di ASP.NET Core.

Pengelogan koneksi

Panggil UseConnectionLogging untuk memancarkan log level debug untuk komunikasi tingkat byte pada dalam koneksi. Pengelogan koneksi sangat membantu untuk memecahkan masalah dalam komunikasi tingkat rendah, seperti selama enkripsi TLS dan di belakang proksi. Jika UseConnectionLogging ditempatkan sebelum UseHttps, lalu lintas terenkripsi dicatat. Jika UseConnectionLogging ditempatkan setelah UseHttps, lalu lintas yang didekripsi dicatat. Ini adalah Middleware Koneksi bawaan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Ikat ke soket TCP

Metode ini Listen mengikat ke soket TCP, dan opsi lambda mengizinkan konfigurasi sertifikat X.509:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Contoh mengonfigurasi HTTPS untuk suatu titik akhir dengan ListenOptions. Gunakan API yang sama untuk mengonfigurasi pengaturan lain Kestrel untuk titik akhir tertentu.

Di Windows, sertifikat yang ditandatangani sendiri dapat dibuat menggunakan New-SelfSignedCertificate cmdlet PowerShell. Untuk contoh yang tidak didukung, lihat UpdateIISExpressSSLForChrome.ps1.

Di macOS, Linux, dan Windows, sertifikat dapat dibuat menggunakan OpenSSL.

Ikat ke soket Unix

Dengarkan soket Unix dengan ListenUnixSocket untuk meningkatkan performa dengan Nginx, seperti yang ditunjukkan dalam contoh ini:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Dalam file konfigurasi Nginx, atur entri ke server>location>proxy_passhttp://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} adalah nama soket yang disediakan untuk ListenUnixSocket (misalnya, kestrel-test.sock dalam contoh sebelumnya).
Pastikan bahwa soket dapat ditulis oleh Nginx (misalnya, chmod go+w /tmp/kestrel-test.sock).

Port 0

Ketika nomor 0 port ditentukan, Kestrel secara dinamis mengikat port yang tersedia. Contoh berikut menunjukkan cara menentukan port Kestrel mana yang terikat pada runtime:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Pengikatan port secara dinamis tidak tersedia dalam situasi tertentu.

ListenLocalhost
Mengikat HTTP/1.1 atau HTTP/2 berbasis TCP, dan HTTP/3 berbasis QUIC bersama-sama.

Batasan

Konfigurasikan titik akhir dengan pendekatan berikut:

UseUrls
--urls argumen baris perintah
urls kunci konfigurasi host
ASPNETCORE_URLS Variabel lingkungan

Metode ini berguna untuk membuat kode berfungsi dengan server selain Kestrel. Namun, perhatikan batasan berikut:

HTTPS tidak dapat digunakan dengan pendekatan ini kecuali sertifikat default disediakan dalam konfigurasi titik akhir HTTPS (misalnya, menggunakan KestrelServerOptions konfigurasi atau file konfigurasi seperti yang ditunjukkan sebelumnya dalam artikel ini).
Ketika pendekatan Listen dan UseUrls digunakan secara bersamaan, titik akhir Listen diambil alih oleh titik akhir UseUrls.

Konfigurasi titik akhir IIS

Saat menggunakan IIS, pengikatan URL untuk pengikatan penimpaan IIS diatur oleh Listen atau UseUrls. Untuk informasi selengkapnya, lihat modul ASP.NET Core.

OpsiDengar.Protokol

Properti Protocols menetapkan protokol HTTP (HttpProtocols) yang diaktifkan pada titik akhir koneksi atau untuk server. Tetapkan nilai untuk properti Protocols dari enumerasi HttpProtocols.

`HttpProtocols` nilai enum	Protokol koneksi diizinkan
`Http1`	HTTP/1.1 saja. Dapat digunakan dengan atau tanpa TLS.
`Http2`	Hanya HTTP/2. Dapat digunakan tanpa TLS hanya jika klien mendukung mode Pengetahuan Awal.
`Http3`	Hanya HTTP/3. Membutuhkan TLS. Klien mungkin perlu dikonfigurasi untuk menggunakan HTTP/3 saja.
`Http1AndHttp2`	HTTP/1.1 dan HTTP/2. HTTP/2 mengharuskan klien untuk memilih HTTP/2 dalam proses negosiasi Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS; jika tidak, koneksi akan default ke HTTP/1.1.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 dan HTTP/3. Permintaan klien pertama biasanya menggunakan HTTP/1.1 atau HTTP/2, dan `alt-svc` header respons meminta klien untuk meningkatkan ke HTTP/3. HTTP/2 dan HTTP/3 memerlukan TLS; jika tidak, koneksi default ke HTTP/1.1.

Nilai default ListenOptions.Protocols untuk titik akhir apa pun adalah HttpProtocols.Http1AndHttp2.

Pembatasan TLS untuk HTTP/2:

TLS versi 1.2 atau yang lebih baru
Negosiasi ulang dinonaktifkan
Pemadatan dinonaktifkan
Ukuran pertukaran kunci sementara minimum
- Kurva eliptik Diffie-Hellman (ECDHE) [RFC4492]: 224 bit minimum
- Bidang terbatas Diffie-Hellman (DHE) [TLS12]: minimum 2048 bit
Cipher suite tidak dilarang.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] dengan kurva elips P-256 [FIPS186] didukung secara default.

Contoh berikut mengizinkan koneksi HTTP/1.1 dan HTTP/2 pada port 8000. Koneksi diamankan oleh TLS dengan sertifikat yang disediakan:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Di Linux, CipherSuitesPolicy dapat digunakan untuk memfilter jabat tangan TLS berdasarkan per koneksi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware Koneksi

Middleware koneksi kustom dapat memfilter jabat tangan TLS untuk setiap koneksi untuk cipher tertentu jika perlu.

Contoh berikut melemparkan NotSupportedException untuk algoritma sandi apa pun yang tidak didukung aplikasi. Atau, tentukan dan bandingkan ITlsHandshakeFeature.CipherAlgorithm dengan daftar suite sandi yang diterima.

Algoritma sandi CipherAlgorithmType.Null tidak menggunakan enkripsi.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Mengatur protokol HTTP dari konfigurasi

Secara bawaan, konfigurasi Kestrel dimuat dari bagian Kestrel. Contoh berikut appsettings.json menetapkan HTTP/1.1 sebagai protokol koneksi default untuk semua titik akhir:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Contoh berikut appsettings.json menetapkan protokol koneksi HTTP/1.1 untuk titik akhir tertentu:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokol yang ditentukan dalam kode menggantikan nilai yang ditetapkan oleh konfigurasi.

Awalan URL

Saat menggunakan UseUrlsargumen baris perintah, --urlsurls kunci konfigurasi host, atau ASPNETCORE_URLS variabel lingkungan, awalan URL dapat berada dalam salah satu format berikut.

Hanya awalan URL HTTP yang valid. Kestrel tidak mendukung HTTPS saat mengonfigurasi pengikatan URL menggunakan UseUrls.

Alamat IPv4 dengan nomor port
```
http://65.55.39.10:80/
```
0.0.0.0 adalah kasus khusus yang mengikat semua alamat IPv4.
Alamat IPv6 dengan nomor port
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] adalah IPv6 setara dengan IPv4 0.0.0.0.
Nama host dengan nomor port
```
http://contoso.com:80/
http://*:80/
```
Nama host, *, dan +, tidak istimewa. Apa pun yang tidak dikenali sebagai alamat IP yang valid atau localhost mengikat semua IP IPv4 dan IPv6. Untuk mengikat nama host yang berbeda ke aplikasi ASP.NET Core yang berbeda pada port yang sama, gunakan HTTP.sys atau server proksi terbalik. Contoh server proksi terbalik termasuk IIS, Nginx, atau Apache.

Peringatan

Hosting dalam konfigurasi proksi terbalik memerlukan pemfilteran terhadap host.
Nama host localhost dengan nomor port atau IP loopback dengan nomor port
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Ketika localhost ditentukan, Kestrel akan mencoba untuk menghubungkan ke antarmuka loopback IPv4 dan IPv6. Jika port yang diminta sedang digunakan oleh layanan lain pada antarmuka loopback, Kestrel gagal memulai. Jika antarmuka loopback tidak tersedia karena alasan lain (paling umum karena IPv6 tidak didukung), Kestrel catat peringatan.

http://localhost:5000
https://localhost:5001 (saat sertifikat pengembangan lokal ada)

Tentukan URL menggunakan:

ASPNETCORE_URLS variabel lingkungan.
--urls argumen baris perintah.
urls kunci konfigurasi host.
UseUrls metode ekstensi.

Untuk informasi selengkapnya tentang pendekatan ini, lihat URL Server dan Override konfigurasi.

Sertifikat pengembangan dibuat:

Ketika .NET SDK diinstal.
Alat dev-certs digunakan untuk membuat sertifikat.

Sertifikat pengembangan hanya tersedia untuk pengguna yang menghasilkan sertifikat. Beberapa browser memerlukan pemberian izin eksplisit untuk mempercayai sertifikat pengembangan lokal.

Template proyek mengonfigurasi aplikasi agar berjalan pada HTTPS secara default dan menyertakan pengalihan HTTPS dan dukungan HSTS.

Panggil metode Listen atau ListenUnixSocket pada KestrelServerOptions untuk mengonfigurasi prefix URL dan port untuk Kestrel.

KestrelServerOptions Konfigurasi:

Mengonfigurasi Pengaturan Default untuk Endpoint

ConfigureEndpointDefaults(Action<ListenOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir yang ditentukan. Memanggil ConfigureEndpointDefaults beberapa kali menggantikan Action sebelumnya dengan yang terakhir ditentukan Action.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.

Konfigurasikan(IConfiguration)

Memungkinkan Kestrel untuk memuat titik akhir dari IConfiguration. Konfigurasi harus dibatasi pada bagian konfigurasi untuk Kestrel. Kelebihan Configure(IConfiguration, bool) beban dapat digunakan untuk mengaktifkan memuat ulang titik akhir saat sumber konfigurasi berubah.

Secara bawaan, konfigurasi Kestrel dimuat dari bagian Kestrel dan mengaktifkan pemuatan ulang perubahan:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Jika konfigurasi muat ulang diaktifkan dan perubahan disinyalir maka langkah-langkah berikut diambil:

Konfigurasi baru dibandingkan dengan yang lama, titik akhir apa pun tanpa perubahan konfigurasi tidak dimodifikasi.
Titik akhir yang dihapus atau dimodifikasi diberi waktu 5 detik untuk menyelesaikan permintaan pemrosesan dan dimatikan.
Titik akhir baru atau yang dimodifikasi dimulai.

Klien yang terhubung ke titik akhir yang dimodifikasi mungkin terputus atau ditolak saat titik akhir dimulai ulang.

MengonfigurasiHttpsDefaults

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir HTTPS. Memanggil ConfigureHttpsDefaults beberapa kali menggantikan Action sebelumnya dengan Action terakhir yang ditentukan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.

ListenOptions.UseHttps

Konfigurasikan Kestrel untuk menggunakan HTTPS.

ListenOptions.UseHttps Ekstensi:

UseHttps: Konfigurasikan Kestrel untuk menggunakan HTTPS dengan sertifikat default. Melemparkan pengecualian jika tidak ada sertifikat default yang dikonfigurasi.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps Parameter-parameternya:

filename adalah jalur dan nama file file sertifikat, relatif terhadap direktori yang berisi file konten aplikasi.
password adalah kata sandi yang diperlukan untuk mengakses data sertifikat X.509.
configureOptions Action adalah untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
storeName adalah penyimpanan sertifikat untuk memuat sertifikat.
subject adalah nama subjek untuk sertifikat.
allowInvalid menunjukkan apakah sertifikat yang tidak valid harus dipertimbangkan, seperti sertifikat yang ditandatangani sendiri.
location adalah lokasi penyimpanan untuk memuat sertifikat.
serverCertificate adalah sertifikat X.509.

Dalam produksi, HTTPS harus dikonfigurasi secara eksplisit. Minimal, sertifikat default harus disediakan.

Konfigurasi yang didukung dijelaskan berikutnya:

Tidak ada konfigurasi
Ganti sertifikat default dari konfigurasi
Mengubah default dalam kode

Tidak ada konfigurasi

Kestrel mendengarkan pada http://localhost:5000 dan https://localhost:5001 (jika sertifikat default tersedia).

Ganti sertifikat default dari konfigurasi

Dalam contoh berikut appsettings.json :

Atur AllowInvalid ke true untuk mengizinkan penggunaan sertifikat yang tidak valid (misalnya, sertifikat yang ditandatangani sendiri).
Titik akhir HTTPS apa pun yang tidak menentukan sertifikat (HttpsDefaultCert dalam contoh berikut) kembali ke sertifikasi yang ditentukan di bawah Certificates:Default atau sertifikat pengembangan.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Catatan skema:

Nama titik akhir tidak peka huruf besar/kecil. Misalnya, HTTPS dan Httpssetara.
Parameter Url diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkat Urls atas kecuali bahwa parameter tersebut terbatas pada satu nilai.
Titik akhir ini menggantikan yang ditentukan dalam konfigurasi tingkat Urls atas, bukan untuk menambahkannya. Titik akhir yang ditentukan dalam kode melalui Listen bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi.
Bagian Certificate ini bersifat opsional. Jika bagian Certificate tidak ditentukan, default yang ditentukan di Certificates:Default digunakan. Jika tidak ada default yang tersedia, sertifikat pengembangan akan digunakan. Jika tidak ada default dan sertifikat pengembangan tidak ada, server akan melempar pengecualian dan gagal memulai.
Bagian ini Certificate mendukung beberapa sumber sertifikat.
Sejumlah titik akhir dapat didefinisikan dalam Konfigurasi selama tidak menyebabkan konflik port.

Sumber sertifikat

Simpul sertifikat dapat dikonfigurasi untuk memuat sertifikat dari sejumlah sumber:

Path dan Password untuk memuat file .pfx.
Path, KeyPath dan Password untuk memuat file .pem/, .crt, dan .key.
Subject dan Store untuk memuat dari penyimpanan sertifikat.

Misalnya, Certificates:Default sertifikat dapat ditentukan sebagai:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

Configure(IConfiguration) mengembalikan sebuah KestrelConfigurationLoader yang memiliki metode Endpoint(String, Action<EndpointConfiguration>) yang dapat digunakan untuk melengkapi pengaturan titik akhir yang dikonfigurasi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

KestrelServerOptions.ConfigurationLoader dapat langsung diakses untuk terus melakukan iterasi pada loader yang ada, seperti yang disediakan oleh WebApplicationBuilder.WebHost.

Bagian konfigurasi untuk setiap titik akhir tersedia pada opsi dalam Endpoint metode sehingga pengaturan kustom dapat dibaca.
Beberapa konfigurasi dapat dimuat dengan memanggil Configure(IConfiguration) lagi dengan bagian yang berbeda. Hanya konfigurasi terakhir yang digunakan, kecuali Load secara eksplisit dipanggil pada instans sebelumnya. Metapackage tidak memanggil Load sehingga bagian konfigurasi defaultnya dapat diganti.
KestrelConfigurationLoader mencerminkan Listen keluarga API dari KestrelServerOptions sebagai Endpoint kelebihan beban, sehingga titik akhir kode dan konfigurasi dapat dikonfigurasi di tempat yang sama. Kelebihan beban ini tidak menggunakan nama dan hanya menggunakan pengaturan default dari konfigurasi.

Mengubah default dalam kode

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Mengonfigurasi titik akhir menggunakan Indikasi Nama Server

SNI dapat dikonfigurasi dengan dua cara:

Buatlah sebuah endpoint dalam kode dan pilih sertifikat menggunakan nama host dengan ServerCertificateSelector panggilan balik.
Konfigurasikan pemetaan antara nama host dan opsi HTTPS di Konfigurasi. Misalnya, JSON dalam appsettings.json file.

SNI dengan `ServerCertificateSelector`

Kestrel mendukung SNI melalui ServerCertificateSelector fungsi callback. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat yang sesuai:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI dengan `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI dengan `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI dalam konfigurasi

Konfigurasi berikut menambahkan titik akhir bernama MySniEndpoint yang menggunakan SNI untuk memilih opsi HTTPS berdasarkan nama host:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Pilihan HTTPS yang dapat diubah oleh SNI:

Certificate mengonfigurasi sumber sertifikat.
Protocolsmengonfigurasi protokol HTTP yang diizinkan.
SslProtocolsmengonfigurasi protokol SSL yang diizinkan.
ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

Nama host mendukung pencocokan kartubebas:

Kecocokan persis. Misalnya, a.example.org cocok dengan a.example.org.
Awalan wildcard. Jika ada beberapa pencocokan kartu bebas maka pola terpanjang yang dipilih. Misalnya, *.example.org cocok dengan b.example.org dan c.example.org.
Kartubebas penuh. * sesuai dengan semua hal lainnya, termasuk klien yang tidak menggunakan SNI dan tidak mengirimkan nama host.

Konfigurasi SNI yang cocok diterapkan pada titik akhir untuk koneksi, menggantikan nilai yang ada pada titik akhir tersebut. Jika koneksi tidak cocok dengan nama host SNI yang dikonfigurasi, koneksi ditolak.

Persyaratan SNI

Semua situs web harus berjalan pada instans yang sama Kestrel . Kestrel tidak mendukung penggunaan alamat IP dan port yang sama di beberapa instance tanpa proksi terbalik.

Protokol SSL/TLS

Protokol SSL adalah protokol yang digunakan untuk mengenkripsi dan mendekripsi lalu lintas antara dua rekan, secara tradisional klien dan server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default, SslProtocols.None, menyebabkan Kestrel menggunakan pengaturan default sistem operasi untuk memilih protokol terbaik. Kecuali Anda memiliki alasan khusus untuk memilih protokol, gunakan default.

Sertifikat Klien

ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default adalah ClientCertificateMode.NoCertificate di mana Kestrel tidak akan meminta atau memerlukan sertifikat dari klien.

Untuk informasi selengkapnya, lihat Mengonfigurasi autentikasi sertifikat di ASP.NET Core.

Pengelogan koneksi

Panggil UseConnectionLogging untuk mengeluarkan log pada tingkat Debug untuk komunikasi tingkat byte pada koneksi. Pengelogan koneksi sangat membantu untuk memecahkan masalah dalam komunikasi tingkat rendah, seperti selama enkripsi TLS dan di belakang proksi. Jika UseConnectionLogging ditempatkan sebelum UseHttps, lalu lintas terenkripsi dicatat. Jika UseConnectionLogging ditempatkan setelah UseHttps, lalu lintas yang didekripsi dicatat. Ini adalah Middleware Koneksi bawaan.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Ikat ke soket TCP

Metode ini Listen mengikat ke soket TCP, dan opsi lambda mengizinkan konfigurasi sertifikat X.509:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Contoh mengonfigurasi HTTPS untuk titik akhir dengan ListenOptions. Gunakan API yang sama untuk mengonfigurasi pengaturan lain Kestrel untuk titik akhir tertentu.

Di Windows, sertifikat yang ditandatangani sendiri dapat dibuat menggunakan New-SelfSignedCertificate cmdlet PowerShell. Untuk contoh yang tidak didukung, lihat UpdateIISExpressSSLForChrome.ps1.

Di macOS, Linux, dan Windows, sertifikat dapat dibuat menggunakan OpenSSL.

Ikat ke soket Unix

Dengarkan soket Unix dengan ListenUnixSocket untuk meningkatkan performa dengan Nginx, seperti yang ditunjukkan dalam contoh ini:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Dalam file konfigurasi Nginx, atur entri ke server>location>proxy_passhttp://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} adalah nama soket yang disediakan untuk ListenUnixSocket (misalnya, kestrel-test.sock dalam contoh sebelumnya).
Pastikan bahwa soket dapat ditulis oleh Nginx (misalnya, chmod go+w /tmp/kestrel-test.sock).

Port 0

Ketika nomor 0 port ditentukan, Kestrel secara dinamis mengikat port yang tersedia. Contoh berikut menunjukkan cara menentukan port Kestrel mana yang terikat pada runtime:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Batasan

Konfigurasikan titik akhir dengan pendekatan berikut:

UseUrls
--urls argumen baris perintah
urls kunci konfigurasi host
ASPNETCORE_URLS Variabel lingkungan

Metode ini berguna untuk membuat kode berfungsi dengan server selain Kestrel. Namun, perhatikan batasan berikut:

HTTPS tidak dapat digunakan dengan pendekatan ini kecuali sertifikat default disediakan dalam konfigurasi titik akhir HTTPS (misalnya, menggunakan KestrelServerOptions konfigurasi atau file konfigurasi seperti yang ditunjukkan sebelumnya dalam artikel ini).
Ketika pendekatan Listen dan UseUrls digunakan secara bersamaan, titik akhir Listen menggantikan titik akhir UseUrls.

Konfigurasi titik akhir IIS

Saat menggunakan IIS, pengikatan URL untuk penimpaan IIS diatur oleh Listen atau UseUrls. Untuk informasi selengkapnya, lihat modul ASP.NET Core.

ListenOptions.Protocols

Properti Protocols menetapkan protokol HTTP (HttpProtocols) yang diaktifkan pada titik akhir koneksi atau untuk server. Tetapkan nilai ke Protocols properti dari HttpProtocols enum.

`HttpProtocols` nilai enum	Protokol koneksi diizinkan
`Http1`	HTTP/1.1 saja. Dapat digunakan dengan atau tanpa TLS.
`Http2`	Hanya HTTP/2. Dapat digunakan tanpa TLS hanya jika klien mendukung mode Pengetahuan Awal.
`Http1AndHttp2`	HTTP/1.1 dan HTTP/2. HTTP/2 mengharuskan klien untuk memilih HTTP/2 di dalam Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS; jika tidak dilakukan, koneksi akan default ke HTTP/1.1.

Nilai default ListenOptions.Protocols untuk titik akhir apa pun adalah HttpProtocols.Http1AndHttp2.

Pembatasan TLS untuk HTTP/2:

TLS versi 1.2 atau yang lebih baru
Negosiasi ulang dinonaktifkan
Pemadatan dinonaktifkan
Ukuran pertukaran kunci sementara (ephemeral) minimum:
- Kurva eliptik Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bit
- Bidang terbatas Diffie-Hellman (DHE) [TLS12]: minimum 2048 bit
Cipher suite tidak dilarang.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] dengan kurva elips P-256 [FIPS186] didukung secara default.

Contoh berikut mengizinkan koneksi HTTP/1.1 dan HTTP/2 pada port 8000. Koneksi diamankan oleh TLS dengan sertifikat yang disediakan:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Di Linux, CipherSuitesPolicy dapat digunakan untuk memfilter jabat tangan TLS berdasarkan per koneksi:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware Koneksi

Middleware koneksi kustom dapat memfilter jabat tangan TLS untuk setiap koneksi guna sandi tertentu apabila diperlukan.

Contoh berikut melemparkan NotSupportedException untuk algoritma sandi apa pun yang tidak didukung aplikasi. Atau, definisikan ITlsHandshakeFeature.CipherAlgorithm dan bandingkan dengan daftar suite sandi yang dapat diterima.

Tidak ada enkripsi yang digunakan dengan algoritma sandi CipherAlgorithmType.Null.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Mengatur protokol HTTP dari konfigurasi

Secara bawaan, konfigurasi Kestrel dimuat dari bagian Kestrel. Contoh berikut appsettings.json menetapkan HTTP/1.1 sebagai protokol koneksi default untuk semua titik akhir:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Contoh berikut appsettings.json menetapkan protokol koneksi HTTP/1.1 untuk titik akhir tertentu:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokol yang ditentukan dalam kode mengesampingkan nilai yang ditetapkan oleh konfigurasi.

Awalan URL

Saat menggunakan UseUrlsargumen baris perintah, --urlsurls kunci konfigurasi host, atau ASPNETCORE_URLS variabel lingkungan, awalan URL dapat berada dalam salah satu format berikut.

Hanya awalan URL HTTP yang valid. Kestrel tidak mendukung HTTPS saat mengonfigurasi pengikatan URL menggunakan UseUrls.

Alamat IPv4 dengan nomor port
```
http://65.55.39.10:80/
```
0.0.0.0 adalah kasus khusus yang mengikat semua alamat IPv4.
Alamat IPv6 dengan nomor port
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] adalah IPv6 setara dengan IPv4 0.0.0.0.
Nama host dengan nomor port
```
http://contoso.com:80/
http://*:80/
```
Nama host, *, dan +, tidak istimewa. Apa pun yang tidak dikenali sebagai alamat IP yang valid atau localhost akan terhubung ke semua IP IPv4 dan IPv6. Untuk mengikat nama host yang berbeda ke aplikasi ASP.NET Core yang berbeda pada port yang sama, gunakan HTTP.sys atau server proksi terbalik. Contoh server proksi terbalik termasuk IIS, Nginx, atau Apache.

Peringatan

Hosting dalam konfigurasi proksi terbalik memerlukan pemfilteran host.
Nama host localhost dengan nomor port atau IP loopback dengan nomor port
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Ketika localhost ditentukan, Kestrel berupaya mengikat ke antarmuka loopback IPv4 dan IPv6. Jika port yang diminta sedang digunakan oleh layanan lain pada antarmuka loopback, Kestrel gagal memulai. Jika antarmuka loopback tidak tersedia karena alasan lain (paling umum karena IPv6 tidak didukung), Kestrel catat peringatan.

Secara default, ASP.NET Core mengikat ke:

http://localhost:5000
https://localhost:5001 (saat sertifikat pengembangan lokal ada)

Tentukan URL menggunakan:

ASPNETCORE_URLS variabel lingkungan.
--urls argumen baris perintah.
urls kunci konfigurasi host.
UseUrls metode ekstensi.

Untuk informasi selengkapnya tentang pendekatan ini, lihat URL Server dan Mengambil alih konfigurasi.

Sertifikat pengembangan dibuat:

Ketika .NET SDK diinstal.
Alat dev-certs digunakan untuk membuat sertifikat.

Beberapa browser memerlukan pemberian izin eksplisit untuk mempercayai sertifikat pengembangan lokal.

Template proyek mengonfigurasi aplikasi untuk berjalan pada HTTPS secara default dan menyertakan pengalihan HTTPS dan dukungan untuk HSTS.

Panggil Listen atau ListenUnixSocket pada KestrelServerOptions untuk mengonfigurasi awalan URL dan port untuk Kestrel.

KestrelServerOptions Konfigurasi:

MengonfigurasiEndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir yang ditentukan. Memanggil ConfigureEndpointDefaults beberapa kali menggantikan Action sebelumnya dengan Action terakhir yang ditentukan.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureEndpointDefaults tidak akan menerapkan default.

Konfigurasikan(IConfiguration)

Memungkinkan Kestrel memuat titik akhir dari IConfiguration. Konfigurasi harus dibatasi pada bagian konfigurasi untuk Kestrel.

Kelebihan Configure(IConfiguration, bool) beban dapat digunakan untuk mengaktifkan memuat ulang titik akhir saat sumber konfigurasi berubah.

IHostBuilder.ConfigureWebHostDefaults secara default memanggil Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) untuk memuat konfigurasi Kestrel dan mengaktifkan pemuatan ulang.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Jika konfigurasi muat ulang diaktifkan dan perubahan disinyalir maka langkah-langkah berikut diambil:

Konfigurasi baru dibandingkan dengan yang lama, titik akhir apa pun tanpa perubahan konfigurasi tidak dimodifikasi.
Titik akhir yang dihapus atau dimodifikasi diberi waktu 5 detik untuk menyelesaikan permintaan pemrosesan dan dimatikan.
Titik akhir baru atau yang dimodifikasi dimulai.

Klien yang terhubung ke titik akhir yang dimodifikasi mungkin terputus atau ditolak saat titik akhir dimulai ulang.

MengonfigurasiHttpsDefaults

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) menentukan konfigurasi Action yang akan dijalankan untuk setiap titik akhir HTTPS. Memanggil ConfigureHttpsDefaults berkali-kali akan menggantikan Action sebelumnya dengan Action terakhir yang ditentukan.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

Catatan

Titik akhir yang dibuat dengan memanggil Listensebelum memanggil ConfigureHttpsDefaults tidak akan menerapkan default.

OpsiDengar.GunakanHttps

Konfigurasikan Kestrel untuk menggunakan HTTPS.

ListenOptions.UseHttps Ekstensi:

UseHttps: Konfigurasikan Kestrel untuk menggunakan HTTPS dengan sertifikat default. Melemparkan pengecualian jika tidak ada sertifikat default yang dikonfigurasi.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps Parameter-parameternya:

filename adalah jalur dan nama file file sertifikat, relatif terhadap direktori yang berisi file konten aplikasi.
password adalah kata sandi yang diperlukan untuk mengakses data sertifikat X.509.
configureOptions Action dapat digunakan untuk mengonfigurasi HttpsConnectionAdapterOptions. Mengembalikan ListenOptions.
storeName adalah penyimpanan sertifikat tempat memuat sertifikat.
subject adalah nama subjek untuk sertifikat.
allowInvalid menunjukkan apakah sertifikat yang tidak valid harus dipertimbangkan, seperti sertifikat yang ditandatangani sendiri.
location adalah lokasi penyimpanan untuk memuat sertifikat.
serverCertificate adalah sertifikat X.509.

Dalam produksi, HTTPS harus dikonfigurasi secara eksplisit. Minimal, sertifikat default harus disediakan.

Konfigurasi yang didukung dijelaskan berikutnya:

Tidak ada konfigurasi
Ganti sertifikat default dari konfigurasi
Mengubah default dalam kode

Tidak ada konfigurasi

Kestrel menangani permintaan pada http://localhost:5000 dan https://localhost:5001 (jika sertifikat default tersedia).

Ganti sertifikat default dari konfigurasi

Dalam contoh berikut appsettings.json :

Atur AllowInvalid ke true untuk mengizinkan penggunaan sertifikat yang tidak valid (misalnya, sertifikat yang ditandatangani sendiri).
Titik akhir HTTPS apa pun yang tidak menentukan sertifikat (HttpsDefaultCert dalam contoh berikut) kembali ke sertifikasi yang ditentukan di bawah Certificates:Default atau sertifikat pengembangan.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Catatan skema:

Nama titik akhir tidak sensitif terhadap huruf besar/kecil. Misalnya, HTTPS dan Httpssetara.
Parameter Url diperlukan untuk setiap titik akhir. Format untuk parameter ini sama dengan parameter konfigurasi tingkat Urls atas kecuali bahwa parameter tersebut terbatas pada satu nilai.
Titik akhir ini menggantikan yang didefinisikan dalam konfigurasi tingkat atas Urls, alih-alih menambahkannya. Titik akhir yang ditentukan dalam kode melalui Listen bersifat kumulatif dengan titik akhir yang ditentukan di bagian konfigurasi.
Bagian Certificate ini bersifat opsional. Jika bagian Certificate tidak ditentukan, default yang didefinisikan dalam Certificates:Default akan digunakan. Jika tidak ada default yang tersedia, sertifikat pengembangan akan digunakan. Jika tidak ada default dan sertifikat pengembangan tidak ada, server akan melempar pengecualian dan gagal memulai.
Bagian Certificate mendukung beberapa sumber sertifikat.
Sejumlah titik akhir dapat didefinisikan dalam Konfigurasi selama tidak menyebabkan konflik port.

Sumber sertifikat

Simpul sertifikat dapat dikonfigurasi untuk memuat sertifikat dari sejumlah sumber:

Path dan Password untuk memuat file .pfx .
Path, KeyPath dan Password untuk memuat file .pem, .crt, dan .key.
Subject dan Store untuk memuat dari penyimpanan sertifikat.

Misalnya, Certificates:Default sertifikat dapat ditentukan sebagai:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

options.Configure(context.Configuration.GetSection("{SECTION}")) mengembalikan sebuah KestrelConfigurationLoader dengan metode .Endpoint(string name, listenOptions => { }) yang dapat digunakan untuk melengkapi pengaturan endpoint yang telah dikonfigurasi.

webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader dapat langsung diakses untuk terus melakukan iterasi pada loader yang ada, seperti yang disediakan oleh CreateDefaultBuilder.

Bagian konfigurasi untuk setiap titik akhir tersedia pada opsi dalam Endpoint metode sehingga pengaturan kustom dapat dibaca.
Beberapa konfigurasi dapat dimuat dengan memanggil options.Configure(context.Configuration.GetSection("{SECTION}")) lagi dengan bagian berbeda. Hanya konfigurasi terakhir yang digunakan, kecuali Load secara eksplisit dipanggil pada instans sebelumnya. Metapackage tidak memanggil Load sehingga bagian konfigurasi defaultnya dapat diganti.
KestrelConfigurationLoader mencerminkan Listen keluarga API dari KestrelServerOptions sebagai Endpoint kelebihan beban, sehingga titik akhir kode dan konfigurasi dapat dikonfigurasi di tempat yang sama. Kelebihan beban ini tidak menggunakan nama dan hanya mengambil pengaturan default dari konfigurasi yang ada.

Mengubah default dalam kode

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Mengonfigurasi titik akhir menggunakan Indikasi Nama Server

SNI dapat dikonfigurasi dengan dua cara:

Buat endpoint dalam kode dan pilih sertifikat menggunakan nama host dengan ServerCertificateSelector callback.
Konfigurasikan pemetaan antara nama host dan opsi HTTPS di Konfigurasi. Misalnya, JSON dalam appsettings.json file.

SNI dengan `ServerCertificateSelector`

Kestrel mendukung SNI melalui ServerCertificateSelector panggilan balik. Panggilan balik dipanggil sekali per koneksi untuk memungkinkan aplikasi memeriksa nama host dan memilih sertifikat yang sesuai. Kode panggilan balik berikut dapat digunakan dalam pemanggilan metode ConfigureWebHostDefaults pada file Program.cs proyek:

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(StringComparer.OrdinalIgnoreCase)
            {
                { "localhost", localhostCert },
                { "example.com", exampleCert },
                { "sub.example.com", subExampleCert },
            };            

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI dengan `ServerOptionsSelectionCallback`

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost", StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                    {
                        ServerCertificate = localhostCert,
                        // Different TLS requirements for this host
                        ClientCertificateRequired = true,
                    });
                }

                return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                {
                    ServerCertificate = exampleCert,
                });
            }, state: null);
        });
    });
});

SNI dalam konfigurasi

Konfigurasi berikut menambahkan titik akhir bernama MySniEndpoint yang menggunakan SNI untuk memilih opsi HTTPS berdasarkan nama host:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Peringatan

Opsi HTTPS yang dapat ditimpa oleh SNI:

Certificate mengonfigurasi sumber sertifikat.
Protocolsmengonfigurasi protokol HTTP yang diizinkan.
SslProtocolsmengonfigurasi protokol SSL yang diizinkan.
ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

Nama host mendukung pencocokan wildcard:

Kecocokan yang persis. Misalnya, a.example.org cocok dengan a.example.org.
Awalan karakter pengganti. Jika ada beberapa kecocokan wildcard, maka pola yang paling panjang dipilih. Misalnya, *.example.org cocok dengan b.example.org dan c.example.org.
Kartubebas penuh. * mencakup semua hal lainnya, termasuk klien yang tidak menggunakan SNI dan tidak mengirim nama host.

Konfigurasi SNI yang sesuai diterapkan ke titik akhir untuk koneksi, menggantikan nilai yang ada di sana. Jika koneksi tidak cocok dengan nama host SNI yang dikonfigurasi, koneksi ditolak.

Persyaratan SNI

Berjalan pada kerangka kerja netcoreapp2.1 target atau yang lebih baru. Pada net461 atau lebih baru, fungsi callback dipanggil tetapi name selalu null. name juga null jika klien tidak memberikan parameter nama host dalam jabat tangan TLS.
Semua situs web berjalan pada instans yang sama Kestrel . Kestrel tidak mendukung berbagi alamat IP dan port di beberapa instans tanpa proksi terbalik.

Protokol SSL/TLS

Protokol SSL adalah protokol yang digunakan untuk mengenkripsi dan mendekripsi lalu lintas antara dua rekan, secara tradisional klien dan server.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default, SslProtocols.None, menyebabkan Kestrel menggunakan default sistem operasi untuk memilih protokol terbaik. Kecuali Anda memiliki alasan khusus untuk memilih protokol, gunakan default.

Sertifikat Klien

ClientCertificateMode mengonfigurasi persyaratan sertifikat klien.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Peringatan

Nilai default adalah ClientCertificateMode.NoCertificate di mana Kestrel tidak akan meminta atau memerlukan sertifikat dari klien.

Untuk informasi selengkapnya, lihat Mengonfigurasi autentikasi sertifikat di ASP.NET Core.

Pengelogan koneksi

Panggil UseConnectionLogging untuk memancarkan log tingkat Debug untuk komunikasi tingkat byte pada koneksi. Pengelogan koneksi sangat membantu untuk memecahkan masalah dalam komunikasi tingkat rendah, seperti selama enkripsi TLS dan di belakang proksi. Jika UseConnectionLogging ditempatkan sebelum UseHttps, lalu lintas terenkripsi dicatat. Jika UseConnectionLogging ditempatkan setelah UseHttps, lalu lintas yang didekripsi dicatat. Ini adalah Middleware Koneksi bawaan.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Ikat ke soket TCP

Metode ini Listen mengikat ke soket TCP, dan opsi lambda mengizinkan konfigurasi sertifikat X.509:

public static void Main(string[] args)
{
    CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

Contoh ini mengonfigurasi HTTPS untuk sebuah titik akhir menggunakan ListenOptions. Gunakan API yang sama untuk mengonfigurasi pengaturan lain Kestrel untuk titik akhir tertentu.

Di Windows, sertifikat yang ditandatangani sendiri dapat dibuat menggunakan New-SelfSignedCertificate cmdlet PowerShell. Untuk contoh yang tidak didukung, lihat UpdateIISExpressSSLForChrome.ps1.

Di macOS, Linux, dan Windows, sertifikat dapat dibuat menggunakan OpenSSL.

Mengaitkan ke soket Unix

Dengarkan soket Unix dengan ListenUnixSocket untuk meningkatkan performa dengan Nginx, seperti yang ditunjukkan dalam contoh ini:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})

Dalam file konfigurasi Nginx, atur entri ke server>location>proxy_passhttp://unix:/tmp/{KESTREL SOCKET}:/; . {KESTREL SOCKET} adalah nama soket yang disediakan untuk ListenUnixSocket (misalnya, kestrel-test.sock dalam contoh sebelumnya).
Pastikan bahwa soket dapat ditulis oleh Nginx (misalnya, chmod go+w /tmp/kestrel-test.sock).

Port 0

Ketika nomor 0 port ditentukan, Kestrel secara dinamis mengikat port yang tersedia. Contoh berikut menunjukkan cara menentukan port Kestrel mana yang terikat pada runtime:

public void Configure(IApplicationBuilder app)
{
    var serverAddressesFeature =
        app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync("<p>Request URL: " +
            $"{context.Request.GetDisplayUrl()}<p>");
    });
}

Saat aplikasi dijalankan, output jendela konsol menunjukkan port dinamis tempat aplikasi dapat dicapai:

Listening on the following addresses: http://127.0.0.1:48508

Batasan

Konfigurasikan titik akhir dengan pendekatan berikut:

UseUrls
--urls argumen garis perintah
urls kunci konfigurasi host
ASPNETCORE_URLS Variabel lingkungan

Metode ini berguna untuk membuat kode berfungsi dengan server selain Kestrel. Namun, perhatikan batasan berikut:

HTTPS tidak dapat digunakan dengan pendekatan ini kecuali sertifikat default disediakan dalam konfigurasi titik akhir HTTPS (misalnya, menggunakan KestrelServerOptions konfigurasi atau file konfigurasi seperti yang ditunjukkan sebelumnya dalam artikel ini).
Ketika pendekatan Listen dan UseUrls digunakan secara bersamaan, titik akhir Listen menggantikan titik akhir UseUrls.

Konfigurasi poin akhir IIS

Saat menggunakan IIS, pengikatan URL untuk penimpaan oleh IIS diatur oleh Listen atau UseUrls. Untuk informasi selengkapnya, lihat modul ASP.NET Core.

ListenOptions.Protocols

Properti Protocols menetapkan protokol HTTP (HttpProtocols) yang diaktifkan pada titik akhir koneksi atau untuk server. Tetapkan sebuah nilai ke properti Protocols dari enum HttpProtocols.

`HttpProtocols` nilai enum	Protokol koneksi diizinkan
`Http1`	HTTP/1.1 saja. Dapat digunakan dengan atau tanpa TLS.
`Http2`	Hanya HTTP/2. Dapat digunakan tanpa TLS hanya jika klien mendukung Mode Pengetahuan Sebelumnya.
`Http1AndHttp2`	HTTP/1.1 dan HTTP/2. HTTP/2 mengharuskan klien untuk memilih HTTP/2 dalam tahap 'handshake' Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS; jika tidak, koneksi akan beralih ke HTTP/1.1.

Nilai default ListenOptions.Protocols untuk titik akhir apa pun adalah HttpProtocols.Http1AndHttp2.

Pembatasan TLS untuk HTTP/2:

TLS versi 1.2 atau yang lebih baru
Negosiasi ulang dinonaktifkan
Pemadatan dinonaktifkan
Ukuran minimum tingkat pertukaran kunci ephemeral:
- Kurva eliptik Diffie-Hellman (ECDHE) [RFC4492]: 224 bit minimum
- Bidang terbatas Diffie-Hellman (DHE) [TLS12]: minimum 2048 bit
Cipher suite tidak dilarang.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] dengan kurva elips P-256 [FIPS186] didukung secara default.

Contoh berikut mengizinkan koneksi HTTP/1.1 dan HTTP/2 pada port 8000. Koneksi diamankan oleh TLS dengan sertifikat yang disediakan:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Di Linux, CipherSuitesPolicy dapat digunakan untuk memfilter jabat tangan TLS berdasarkan per koneksi:

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Middleware Koneksi

Middleware koneksi kustom dapat memfilter jabat tangan TLS untuk setiap koneksi berdasarkan enkripsi tertentu jika perlu.

Tidak ada enkripsi yang digunakan dengan algoritma CipherAlgorithmType.Null.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});

using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

Pemfilteran koneksi juga dapat dikonfigurasi melalui IConnectionBuilder lambda:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Mengatur protokol HTTP dari konfigurasi

CreateDefaultBuilder memanggil serverOptions.Configure(context.Configuration.GetSection("Kestrel")) secara default untuk memuat konfigurasi Kestrel.

Contoh berikut appsettings.json menetapkan HTTP/1.1 sebagai protokol koneksi default untuk semua titik akhir:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Contoh berikut appsettings.json menetapkan protokol koneksi HTTP/1.1 untuk titik akhir tertentu:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokol yang ditentukan dalam kode akan menimpa nilai yang ditetapkan oleh konfigurasi.

Awalan URL

Saat menggunakan UseUrlsargumen baris perintah, --urlsurls kunci konfigurasi host, atau ASPNETCORE_URLS variabel lingkungan, awalan URL dapat berada dalam salah satu format berikut.

Hanya awalan URL HTTP yang valid. Kestrel tidak mendukung HTTPS saat mengonfigurasi pengikatan URL menggunakan UseUrls.

Alamat IPv4 dengan nomor port
```
http://65.55.39.10:80/
```
0.0.0.0 adalah kasus khusus yang mengikat semua alamat IPv4.
Alamat IPv6 dengan nomor port
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] adalah IPv6 setara dengan IPv4 0.0.0.0.
Nama host dengan nomor port
```
http://contoso.com:80/
http://*:80/
```
Nama host, *, dan +, tidak istimewa. Apa pun yang tidak dikenali sebagai alamat IP yang valid atau localhost mengikat semua IP IPv4 dan IPv6. Untuk mengikat nama host yang berbeda ke aplikasi ASP.NET Core yang berbeda pada port yang sama, gunakan HTTP.sys atau server proksi terbalik. Contoh server proksi terbalik termasuk IIS, Nginx, atau Apache.

Peringatan

Hosting dalam konfigurasi proksi terbalik memerlukan pemfilteran host.
Nama host localhost dengan nomor port, atau IP loopback dengan nomor port
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Ketika localhost ditentukan, Kestrel mencoba untuk mengikat ke kedua antarmuka loopback IPv4 dan IPv6. Jika port yang diminta sedang digunakan oleh layanan lain pada antarmuka loopback, Kestrel gagal memulai. Jika antarmuka loopback tidak tersedia karena alasan lain (paling umum karena IPv6 tidak didukung), Kestrel catat peringatan.

Bagikan melalui

Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel

Titik akhir bawaan

Mengonfigurasi titik akhir

Mengonfigurasi titik akhir dengan URL

Format URL

Awalan URL HTTPS

Tentukan port saja

Mengonfigurasi titik akhir di appsettings.json

Memuat ulang titik akhir dari konfigurasi

ConfigurationLoader

Mengonfigurasi titik akhir dalam kode

Ikat ke soket TCP

Ikat ke soket Unix

Mengonfigurasi setelan awal endpoint

Pengikatan port dinamis

Mengonfigurasi HTTPS

Mengonfigurasi HTTPS di appsettings.json

Catatan skema

Sumber sertifikat

Mengonfigurasi sertifikat klien di appsettings.json

Mengonfigurasi protokol SSL/TLS di appsettings.json

Mengonfigurasi HTTPS dalam kode

Mengonfigurasi sertifikat klien dalam kode

Konfigurasi default HTTPS dalam kode

Mengonfigurasi protokol SSL/TLS dalam kode

Mengonfigurasi filter suite sandi TLS dalam kode

Mengonfigurasi Indikasi Nama Server

Mengonfigurasi SNI pada appsettings.json

Mengonfigurasi SNI dengan kode

SNI dengan ServerCertificateSelector

SNI dengan ServerOptionsSelectionCallback

SNI dengan TlsHandshakeCallbackOptions

Konfigurasi protokol HTTP

Mengonfigurasi protokol HTTP di appsettings.json

Mengonfigurasi protokol HTTP dalam kode

Sesuaikan titik akhir pipa bernama Kestrel

Lihat juga

Mengonfigurasi EndpointDefaults

Konfigurasikan(IConfiguration)

MengonfigurasiHttpsDefaults

ListenOptions.UseHttps

Tidak ada konfigurasi

Ganti sertifikat default dari konfigurasi

Sumber sertifikat

ConfigurationLoader

Mengubah default dalam kode

Mengonfigurasi titik akhir menggunakan Indikasi Nama Server

SNI dengan ServerCertificateSelector

SNI dengan ServerOptionsSelectionCallback

SNI dengan TlsHandshakeCallbackOptions

SNI dalam konfigurasi

Persyaratan SNI

Protokol SSL/TLS

Sertifikat Klien

Pengelogan koneksi

Ikat ke soket TCP

Ikat ke soket Unix

Port 0

Batasan

Konfigurasi titik akhir IIS

OpsiDengar.Protokol

Middleware Koneksi

Mengatur protokol HTTP dari konfigurasi

Awalan URL

Mengonfigurasi Pengaturan Default untuk Endpoint

Konfigurasikan(IConfiguration)

MengonfigurasiHttpsDefaults

ListenOptions.UseHttps

Tidak ada konfigurasi

Ganti sertifikat default dari konfigurasi

Sumber sertifikat

ConfigurationLoader

Mengubah default dalam kode

Mengonfigurasi titik akhir menggunakan Indikasi Nama Server

SNI dengan ServerCertificateSelector

SNI dengan ServerOptionsSelectionCallback

SNI dengan TlsHandshakeCallbackOptions

SNI dalam konfigurasi

Persyaratan SNI

SNI dengan `ServerCertificateSelector`

SNI dengan `ServerOptionsSelectionCallback`

SNI dengan `TlsHandshakeCallbackOptions`

SNI dengan `ServerCertificateSelector`

SNI dengan `ServerOptionsSelectionCallback`

SNI dengan `TlsHandshakeCallbackOptions`

SNI dengan `ServerCertificateSelector`

SNI dengan `ServerOptionsSelectionCallback`

SNI dengan `TlsHandshakeCallbackOptions`

SNI dengan `ServerCertificateSelector`

SNI dengan `ServerOptionsSelectionCallback`