Mengonfigurasi titik akhir untuk server web ASP.NET Core Kestrel

Kestrel titik akhir menyediakan infrastruktur untuk mendengarkan permintaan masuk dan merutekannya ke middleware yang sesuai. Kombinasi alamat dan protokol menentukan titik akhir.

• Alamat menentukan antarmuka jaringan yang didengarkan server untuk 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 default

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, titik akhir 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 ekstensi.
• properti WebApplication.Urls.

Format URL

URL menunjukkan IP atau alamat host dengan port dan protokol yang harus didengarkan server. 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 kartubebas 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 localhost host 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 upaya untuk 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.

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

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

Untuk informasi selengkapnya, lihat Mengambil alih konfigurasi.

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 didengarkan, seperti port 80, tanpa batasan tambahan seperti host atau jalur. HTTP_PORTS dan HTTPS_PORTS adalah kunci konfigurasi yang menentukan port mendengarkan untuk Kestrel server HTTP.sys dan . 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 titik akhir dari IConfiguration instans. Secara default, Kestrel konfigurasi dimuat dari bagian Kestrel dan titik akhir dikonfigurasi di Kestrel:Endpoints:

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

Contoh sebelumnya:

• appsettings.json Menggunakan 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 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 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.
• 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 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.

Mengonfigurasi titik akhir dalam kode

KestrelServerOptions menyediakan metode untuk mengonfigurasi titik akhir dalam kode:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Listen Ketika API UseUrls dan digunakan secara bersamaan, Listen titik akhir mengambil alih UseUrls titik akhir.

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 mendengarkan di port 5000 dan 5001.
• Mengonfigurasi HTTPS untuk titik akhir dengan UseHttps metode ekstensi 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>http://unix:/tmp/{KESTREL SOCKET}:/;location>proxy_pass . {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 default titik akhir

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

var builder = WebApplication.CreateBuilder(args);

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

Catatan

Titik akhir yang dibuat dengan memanggil Listen sebelum 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);

        // ...
    }
});

Pengikatan port secara dinamis tidak tersedia dalam beberapa situasi:

• 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 nondevelopment. 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 menentukan port hanya digunakan untuk menentukan titik akhir, HTTPS hanya dapat digunakan 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 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. Lihat format URL sebelumnya di artikel ini.
• Titik akhir ini menggantikan yang ditentukan dalam konfigurasi tingkat Urls atas daripada 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 akan 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 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 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>"
}

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

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.

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

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.

Nilai default, SslProtocols.None, menyebabkan Kestrel penggunaan 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, UseHttps metode ekstensi aktif 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.
• configureOptionsAction 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.

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.

Mengonfigurasi default HTTPS dalam kode

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

var builder = WebApplication.CreateBuilder(args);

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

Catatan

Titik akhir yang dibuat dengan memanggil Listen sebelum 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 alamat IP dan port di beberapa instans tanpa 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 panggilan balik.

Mengonfigurasi SNI di 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

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.

Opsi HTTPS yang dapat ditimpa oleh SNI:

• Certificatemengonfigurasi sumber sertifikat.
• Protocolsmengonfigurasi protokol HTTP yang diizinkan.
• SslProtocolsmengonfigurasi protokol SSL yang diizinkan.
• ClientCertificateModemengonfigurasi persyaratan sertifikat klien.

Nama host mendukung pencocokan kartubebas:

• Kecocokan persis. Misalnya, a.example.org cocok a.example.orgdengan .
• Awalan kartubebas. Jika ada beberapa kecocokan kartubebas, maka pola terpanjang dipilih. Misalnya, *.example.org kecocokan b.example.org dan c.example.org.
• Kartubebas penuh. * cocok dengan yang lain, termasuk klien yang tidak menggunakan SNI dan tidak mengirim 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, maka koneksi ditolak.

Mengonfigurasi SNI dengan kode

Kestrel mendukung SNI dengan beberapa API panggilan balik:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

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:

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

Mengonfigurasi 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 jabat tangan Negosiasi Protokol Lapisan Aplikasi (ALPN) TLS; 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 pertukaran kunci ephemeral minimum:
  • 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 nilai penimpaan kode 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;
    });
});

Lihat juga

• Kestrel server web di ASP.NET Core
• Mengonfigurasi opsi untuk server web ASP.NET Core Kestrel