ASP.NET Core Kestrel web sunucusu için uç noktaları yapılandırma

Kestrel uç noktalar, gelen istekleri dinlemek ve uygun ara yazılıma yönlendirmek için altyapı sağlar. Adres ve protokol birleşimi bir uç noktayı tanımlar.

• Adres, sunucunun TCP bağlantı noktası gibi gelen istekler için dinlediği ağ arabirimini belirtir.
• Protokol http/1.1, HTTP/2 veya HTTP/3 gibi istemci ve sunucu arasındaki iletişimi belirtir.
• Url şeması veya UseHttps yöntemi kullanılarak bir uç noktanın https güvenliği sağlanabilir.

Uç noktalar URL'ler, içindeki JSON appsettings.jsonve kod kullanılarak yapılandırılabilir. Bu makalede, bir uç noktayı yapılandırmak için her seçeneğin nasıl kullanılacağı açıklanır:

• Uç noktaları yapılandırma
• HTTPS'yi yapılandırma
• HTTP protokollerini yapılandırma

Varsayılan uç nokta

Yeni ASP.NET Core projeleri, 5000-5300 arasında rastgele bir HTTP bağlantı noktasına ve 7000-7300 arasında rastgele bir HTTPS bağlantı noktasına bağlanacak şekilde yapılandırılır. Seçilen bağlantı noktaları oluşturulan Properties/launchSettings.json dosyada depolanır ve geliştirici tarafından değiştirilebilir. Dosya launchSetting.json yalnızca yerel geliştirmede kullanılır.

Uç nokta yapılandırması yoksa öğesine Kestrel bağlanır http://localhost:5000.

Uç noktaları yapılandırma

Kestrel uç noktalar gelen bağlantıları dinler. Uç nokta oluşturulduğunda, dinleyeceği adresle yapılandırılması gerekir. Bu genellikle bir TCP adresi ve bağlantı noktası numarasıdır.

Uç noktaları yapılandırmak için çeşitli seçenekler vardır:

• UÇ noktaları URL'lerle yapılandırma
• Yalnızca bağlantı noktalarını belirtin
• appsettings.json'de uç noktaları yapılandırma
• Kodda uç noktaları yapılandırma

UÇ noktaları URL'lerle yapılandırma

Aşağıdaki bölümlerde, kullanarak uç noktaların nasıl yapılandır yapılacağı açıklanmaktadır:

• ASPNETCORE_URLS ortam değişkeni.
• --urls komut satırı bağımsız değişkeni.
• urls ana bilgisayar yapılandırma anahtarı.
• UseUrls uzantı yöntemi.
• WebApplication.Urls mülk.

URL biçimleri

URL'ler, sunucunun dinlemesi gereken bağlantı noktaları ve protokollere sahip IP veya konak adreslerini gösterir. Protokol için varsayılan bağlantı noktasıysa (genellikle 80 ve 443) bağlantı noktası atlanabilir. URL'ler aşağıdaki biçimlerden herhangi birinde olabilir.

• Bağlantı noktası numarası olan IPv4 adresi

  http://65.55.39.10:80/
  

  0.0.0.0 , tüm IPv4 adreslerine bağlanan özel bir durumdur.

• Bağlantı noktası numarasıyla IPv6 adresi

  http://[0:0:0:0:0:ffff:4137:270a]:80/
  

  [::] , IPv4'ün 0.0.0.0IPv6 eşdeğeridir.

• Bağlantı noktası numarasına sahip joker konak

  http://contoso.com:80/
  http://*:80/
  

  Geçerli bir IP adresi olarak tanınmayan veya localhost tüm IPv4 ve IPv6 adreslerine bağlanan joker karakter olarak kabul edilen her şey. Bazı kişiler kullanmak * veya + daha açık olmak ister. Farklı konak adlarını aynı bağlantı noktasındaki farklı ASP.NET Core uygulamalarına bağlamak için HTTP.sys veya ters ara sunucu kullanın.

  Ters ara sunucu örnekleri IIS, YARP, Nginx ve Apache'dir.

• Bağlantı noktası numarası veya bağlantı noktası numarası ile geri döngü IP'siyle ana bilgisayar adı localhost

  http://localhost:5000/
  http://127.0.0.1:5000/
  http://[::1]:5000/
  

  Belirtildiğinde localhost , Kestrel hem IPv4 hem de IPv6 geri döngü arabirimlerine bağlanmaya çalışır. İstenen bağlantı noktası herhangi bir geri döngü arabiriminde başka bir hizmet tarafından kullanılıyorsa başlatılamaz Kestrel . Geri döngü arabirimi herhangi bir nedenle kullanılamıyorsa (en yaygın olarak IPv6 desteklenmediğinden), Kestrel bir uyarı günlüğe kaydeder.

Noktalı virgül (;) sınırlayıcı kullanılarak birden çok URL ön eki belirtilebilir:

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

Daha fazla bilgi için bkz . Yapılandırmayı geçersiz kılma.

HTTPS URL ön ekleri

HTTPS URL ön ekleri yalnızca HTTPS uç noktası yapılandırmasında varsayılan bir sertifika sağlandığında uç noktaları tanımlamak için kullanılabilir. Örneğin, bu makalenin ilerleyen bölümlerinde gösterildiği gibi yapılandırma veya yapılandırma dosyası kullanınKestrelServerOptions.

Daha fazla bilgi için bkz . HTTPS'yi yapılandırma.

Yalnızca bağlantı noktalarını belirtin

Uygulamalara ve kapsayıcılara genellikle konak veya yol gibi ek kısıtlamalar olmadan yalnızca 80 numaralı bağlantı noktası gibi dinlemeleri için bir bağlantı noktası verilir. HTTP_PORTS ve HTTPS_PORTS, ve HTTP.sys sunucuları için Kestrel dinleme bağlantı noktalarını belirten yapılandırma anahtarlarıdır. Bu anahtarlar, veya ASPNETCORE_ ön ekleriyle DOTNET_ tanımlanan ortam değişkenleri olarak belirtilebilir veya gibi appsettings.jsonbaşka bir yapılandırma girişi aracılığıyla doğrudan belirtilebilir. Her biri, aşağıdaki örnekte gösterildiği gibi noktalı virgülle ayrılmış bağlantı noktası değerleri listesidir:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Yukarıdaki örnek, şemayı (HTTP veya HTTPS) ve herhangi bir konağı veya IP'yi belirten aşağıdaki yapılandırmanın kısaltmasıdır.

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

HTTP_PORTS ve HTTPS_PORTS yapılandırma anahtarları daha düşük önceliklidir ve doğrudan kodda sağlanan URL'ler veya değerler tarafından geçersiz kılınabilir. Sertifikaların yine de HTTPS için sunucuya özgü mekanikler aracılığıyla ayrı olarak yapılandırılması gerekir.

appsettings.json'de uç noktaları yapılandırma

Kestrel bir IConfiguration örnekten uç noktaları yükleyebilir. Varsayılan olarak, Kestrel yapılandırma bölümünden Kestrel yüklenir ve uç noktalar içinde Kestrel:Endpointsyapılandırılır:

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

Yukarıdaki örnek:

• Yapılandırma kaynağı olarak kullanır appsettings.json . Ancak, herhangi bir IConfiguration kaynak kullanılabilir.
• 8080 numaralı bağlantı noktasına adlı MyHttpEndpoint bir uç nokta ekler.

JSON ile uç noktaları yapılandırma hakkında daha fazla bilgi için, bu makalede https yapılandırmayı ve appsettings.json'de HTTP protokollerini yapılandırmayı ele alan sonraki bölümlere bakın.

Uç noktaları yapılandırmadan yeniden yükleme

Yapılandırma kaynağı değiştiğinde uç nokta yapılandırması varsayılan olarak yeniden yükleniyor. kullanılarak KestrelServerOptions.Configure(IConfiguration, Boolean)devre dışı bırakılabilir.

Bir değişiklik sinyali alınırsa aşağıdaki adımlar uygulanır:

• Yeni yapılandırma eski yapılandırmayla karşılaştırılır ve yapılandırma değişikliği olmayan uç noktalar değiştirilmez.
• Kaldırılan veya değiştirilen uç noktalara işleme isteklerini tamamlamak ve kapatmak için 5 saniye verilir.
• Yeni veya değiştirilmiş uç noktalar başlatılır.

Değiştirilen uç noktaya bağlanan istemcilerin bağlantısı kesilebilir veya uç nokta yeniden başlatılırken reddedilebilir.

ConfigurationLoader

KestrelServerOptions.Configure bir KestrelConfigurationLoaderdöndürür. Yükleyicinin Endpoint(String, Action<EndpointConfiguration>) , yapılandırılmış bir uç noktanın ayarlarını desteklemek için kullanılabilecek yöntemi:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader , tarafından WebApplicationBuilder.WebHostsağlanan gibi mevcut yükleyicide yinelemeye devam etmek için doğrudan erişilebilir.

• Her uç noktanın yapılandırma bölümü, özel ayarların okunabilmesi için yöntemindeki Endpoint seçeneklerde kullanılabilir.
• KestrelServerOptions.Configure(IConfiguration) birden çok kez çağrılabilir, ancak önceki örneklerde açıkça çağrılmadığı sürece Load yalnızca son yapılandırma kullanılır. Varsayılan ana bilgisayar, varsayılan yapılandırma bölümünün değiştirilebilmesi için çağrı Load yapmaz.
• KestrelConfigurationLoaderListen, API KestrelServerOptions ailesini aşırı yükleme olarak Endpoint yansıtır, bu nedenle kod ve yapılandırma uç noktaları aynı yerde yapılandırılabilir. Bu aşırı yüklemeler adları kullanmaz ve yalnızca yapılandırmadan varsayılan ayarları kullanır.

Kodda uç noktaları yapılandırma

KestrelServerOptions kodda uç noktaları yapılandırmak için yöntemler sağlar:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Hem hem de Listen UseUrls API'leri aynı anda kullanıldığında, Listen uç noktalar uç noktaları geçersiz kılarUseUrls.

TCP yuvasına bağlama

Listen, ListenLocalhostve ListenAnyIP yöntemleri bir TCP yuvasına bağlanır:

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

Yukarıdaki örnek:

• 5000 ve 5001 numaralı bağlantı noktalarını dinleyen uç noktaları yapılandırılır.
• üzerinde uzantı yöntemiyle bir uç nokta için HTTPS'yi UseHttps yapılandırıyor ListenOptions. Daha fazla bilgi için bkz . Kodda HTTPS'yi yapılandırma.

Windows'da otomatik olarak imzalanan sertifikalar PowerShell cmdlet'i New-SelfSignedCertificatekullanılarak oluşturulabilir. Desteklenmeyen bir örnek için bkz UpdateIISExpressSSLForChrome.ps1. .

macOS, Linux ve Windows'da sertifikalar OpenSSL kullanılarak oluşturulabilir.

Unix yuvasına bağlama

Bu örnekte gösterildiği gibi Nginx ile geliştirilmiş performans için ile unix yuvasını ListenUnixSocket dinleyin:

var builder = WebApplication.CreateBuilder(args);

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

• Nginx yapılandırma dosyasında girdisini server>proxy_pass>locationolarak http://unix:/tmp/{KESTREL SOCKET}:/;ayarlayın. {KESTREL SOCKET} , verilen ListenUnixSocket yuvanın adıdır (örneğin, kestrel-test.sock önceki örnekte).
• Yuvanın Nginx tarafından yazılabilir olduğundan emin olun (örneğin, chmod go+w /tmp/kestrel-test.sock).

Uç nokta varsayılanlarını yapılandırma

ConfigureEndpointDefaults(Action<ListenOptions>) belirtilen her uç nokta için çalışan yapılandırmayı belirtir. Birden çok kez çağrılması ConfigureEndpointDefaults önceki yapılandırmanın yerini alır.

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureEndpointDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Dinamik bağlantı noktası bağlama

Bağlantı noktası numarası 0 belirtildiğinde, Kestrel kullanılabilir bir bağlantı noktasına dinamik olarak bağlanır. Aşağıdaki örnekte çalışma zamanında hangi bağlantı noktası Kestrel bağlı olduğunu belirleme adımları gösterilmektedir:

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

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

        // ...
    }
});

Bağlantı noktasını dinamik olarak bağlama bazı durumlarda kullanılamaz:

• KestrelServerOptions.ListenLocalhost
• TCP tabanlı HTTP/1.1 veya HTTP/2 ve QUIC tabanlı HTTP/3'ün birbirine bağlanması.

HTTPS’yi yapılandırma

Kestrel HTTPS ile uç noktaların güvenliğini sağlamayı destekler. HTTPS üzerinden gönderilen veriler, istemci ile sunucu arasında aktarılan verilerin güvenliğini artırmak için Aktarım Katmanı Güvenliği (TLS) kullanılarak şifrelenir.

HTTPS bir TLS sertifikası gerektirir. TLS sertifikası sunucuda depolanır ve Kestrel bunu kullanacak şekilde yapılandırılır. Bir uygulama, yerel geliştirme ortamında ASP.NET Core HTTPS geliştirme sertifikasını kullanabilir. Geliştirme sertifikası, geliştirme olmayan ortamlarda yüklü değildir. Üretimde bir TLS sertifikası açıkça yapılandırılmalıdır. En azından varsayılan bir sertifika sağlanmalıdır.

HTTPS ve TLS sertifikasının yapılandırılma şekli, uç noktaların nasıl yapılandırıldığına bağlıdır:

• URL ön ekleri veya bağlantı noktalarını belirtme yalnızca uç noktaları tanımlamak için kullanılıyorsa, HTTPS yalnızca HTTPS uç nokta yapılandırmasında varsayılan bir sertifika sağlandığında kullanılabilir. Varsayılan sertifika aşağıdaki seçeneklerden biriyle yapılandırılabilir:
• appsettings.json'de HTTPS'yi yapılandırma
• Kodda HTTPS'yi yapılandırma

appsettings.json'de HTTPS'yi yapılandırma

için Kestrelvarsayılan BIR HTTPS uygulama ayarları yapılandırma şeması sağlanır. Disk üzerindeki bir dosyadan veya bir sertifika deposundan URL'ler ve kullanılacak sertifikalar dahil olmak üzere birden çok uç nokta yapılandırın.

Sertifika belirtmeyen herhangi bir HTTPS uç noktası (HttpsDefaultCert aşağıdaki örnekte) veya geliştirme sertifikası altında Certificates:Default tanımlanan sertifikaya geri döner.

Aşağıdaki örnek içindir appsettings.json, ancak herhangi bir yapılandırma kaynağı kullanılabilir:

{
  "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$"
      }
    }
  }
}

Uyarı

Yukarıdaki örnekte, sertifika parolası içinde appsettings.jsondüz metin olarak depolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

Şema notları

• Uç nokta adları büyük /küçük harfe duyarlı değildir. Örneğin ve HTTPS Https eşdeğerdir.
• Url Parametresi her uç nokta için gereklidir. Bu parametrenin biçimi, tek bir değerle sınırlı olması dışında üst düzey Urls yapılandırma parametresiyle aynıdır. Bu makalenin önceki bölümlerinde yer alan URL biçimlerine bakın.
• Bu uç noktalar, bunlara eklemek yerine üst düzey Urls yapılandırmada tanımlananların yerini alır. aracılığıyla Listen kodda tanımlanan uç noktalar, yapılandırma bölümünde tanımlanan uç noktalarla birikmeli olarak bulunur.
• Bölüm Certificate isteğe bağlıdır. Certificate Bölüm belirtilmezse, içinde Certificates:Default tanımlanan varsayılanlar kullanılır. Varsayılan değer yoksa geliştirme sertifikası kullanılır. Varsayılan değer yoksa ve geliştirme sertifikası yoksa, sunucu bir özel durum oluşturur ve başlatılamaz.
• Certificate bölümü birden çok sertifika kaynağını destekler.
• Bağlantı noktası çakışmalarına neden olmayan herhangi bir sayıda uç nokta içinde Configurationtanımlanabilir.

Sertifika kaynakları

Sertifika düğümleri, çeşitli kaynaklardan sertifika yüklenecek şekilde yapılandırılabilir:

• Pathve Password .pfx dosyalarını yüklemek için.
• Pathve KeyPath .pem.crt/ ve .key dosyalarını yüklemek için.Password
• Subject ve Store sertifika deposundan yüklemek için.

Örneğin, Certificates:Default sertifika şu şekilde belirtilebilir:

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

appsettings.json'de istemci sertifikalarını yapılandırma

ClientCertificateMode , istemci sertifikası davranışını yapılandırmak için kullanılır.

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

Uyarı

Yukarıdaki örnekte, sertifika parolası içinde appsettings.jsondüz metin olarak depolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

Varsayılan değer, istemciden sertifika istemediği veya gerektirmediği Kestrel değeridirClientCertificateMode.NoCertificate.

Daha fazla bilgi için bkz . ASP.NET Core'da sertifika kimlik doğrulamasını yapılandırma.

appsettings.json'de SSL/TLS protokollerini yapılandırma

SSL Protokolleri, geleneksel olarak istemci ve sunucu olmak üzere iki eş arasındaki trafiği şifrelemek ve şifresini çözmek için kullanılan protokollerdir.

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

Uyarı

Yukarıdaki örnekte, sertifika parolası içinde appsettings.jsondüz metin olarak depolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

varsayılan değeri, SslProtocols.Noneen iyi protokolü seçmek için işletim sistemi varsayılanlarının kullanılmasına neden olur Kestrel . Protokol seçmek için belirli bir nedeniniz yoksa varsayılanı kullanın.

Kodda HTTPS'yi yapılandırma

API kullanılırken Listen , https'yi UseHttps yapılandırmak için üzerindeki ListenOptions uzantı yöntemi kullanılabilir.

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 Parametre:

• filename , uygulamanın içerik dosyalarını içeren dizine göre bir sertifika dosyasının yolu ve dosya adıdır.
• password , X.509 sertifika verilerine erişmek için gereken paroladır.
• configureOptions , öğesini yapılandırmak için bir Action 'dir HttpsConnectionAdapterOptions. ListenOptionsdöndürür.
• storeName , sertifikanın yüklendiği sertifika deposudur.
• subject sertifikanın konu adıdır.
• allowInvalid otomatik olarak imzalanan sertifikalar gibi geçersiz sertifikaların dikkate alınması gerekip gerekmediğini gösterir.
• location , sertifikanın yüklenecek depo konumudur.
• serverCertificate X.509 sertifikasıdır.

Aşırı yüklemelerin UseHttps tam listesi için bkz UseHttps. .

Kodda istemci sertifikalarını yapılandırma

ClientCertificateMode istemci sertifikası gereksinimlerini yapılandırmaktadır.

var builder = WebApplication.CreateBuilder(args);

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

Varsayılan değer, istemciden sertifika istemediği veya gerektirmediği Kestrel değeridirNoCertificate.

Daha fazla bilgi için bkz . ASP.NET Core'da sertifika kimlik doğrulamasını yapılandırma.

Kodda HTTPS varsayılanlarını yapılandırma

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>), her HTTPS uç noktası için çalıştırılacak bir yapılandırma Action belirtir. Birden çok kez çağrılması ConfigureHttpsDefaults , önceki Action örneklerin yerini belirtilen son Action örnekle değiştirir.

var builder = WebApplication.CreateBuilder(args);

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

Not

Çağrıdan ConfigureHttpsDefaults önce çağrılarak Listen oluşturulan uç noktalarda varsayılan değerler uygulanmaz.

Kodda SSL/TLS protokollerini yapılandırma

SSL protokolleri, geleneksel olarak istemci ve sunucu olmak üzere iki eş arasındaki trafiği şifrelemek ve şifresini çözmek için kullanılan protokollerdir.

var builder = WebApplication.CreateBuilder(args);

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

Kodda TLS şifreleme paketleri filtresini yapılandırma

Linux'ta TLS CipherSuitesPolicy el sıkışmalarını bağlantı başına göre filtrelemek için kullanılabilir:

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,
                    // ...
                });
        };
    });
});

Sunucu Adı Gösterimini Yapılandır

Sunucu Adı Göstergesi (SNI), aynı IP adresi ve bağlantı noktasında birden çok etki alanını barındırmak için kullanılabilir. SNI, bir sunucudan birden çok siteye hizmet vererek kaynakları korumak için kullanılabilir.

SNI'nin çalışması için istemci, sunucunun doğru sertifikayı sağlayabilmesi için TLS el sıkışması sırasında güvenli oturum için ana bilgisayar adını sunucuya gönderir. İstemci, TLS el sıkışmasını izleyen güvenli oturum sırasında sunucuyla şifreli iletişim için döşenmiş sertifikayı kullanır.

Tüm web siteleri aynı Kestrel örnekte çalıştırılmalıdır. Kestrel ip adresini ve bağlantı noktasını ters ara sunucu olmadan birden çok örnek arasında paylaşmayı desteklemez.

SNI iki şekilde yapılandırılabilir:

• Yapılandırma'da konak adları ve HTTPS seçenekleri arasında bir eşleme yapılandırın. Örneğin, dosyadaki appsettings.json JSON.
• Kodda bir uç nokta oluşturun ve geri arama ile ServerCertificateSelector konak adını kullanarak bir sertifika seçin.

appsettings.json'de SNI'yi yapılandırma

Kestrel yapılandırmada tanımlanan SNI'leri destekler. Uç nokta, konak adları ve HTTPS seçenekleri arasında eşleme içeren bir nesneyle Sni yapılandırılabilir. Bağlantı ana bilgisayar adı seçeneklerle eşleştirilir ve bu bağlantı için kullanılır.

Aşağıdaki yapılandırma, konak adına göre HTTPS seçeneklerini seçmek için SNI kullanan adlı MySniEndpoint bir uç nokta ekler:

{
  "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$"
      }
    }
  }
}

Uyarı

Yukarıdaki örnekte, sertifika parolası içinde appsettings.jsondüz metin olarak depolanır. Belirteç $CREDENTIAL_PLACEHOLDER$ , sertifikanın parolası için yer tutucu olarak kullanılır. Sertifika parolalarını geliştirme ortamlarında güvenli bir şekilde depolamak için bkz . Geliştirmede gizli dizileri koruma. Sertifika parolalarını üretim ortamlarında güvenli bir şekilde depolamak için bkz . Azure Key Vault yapılandırma sağlayıcısı. Geliştirme gizli dizileri üretim veya test için kullanılmamalıdır.

SNI tarafından geçersiz kılınabilecek HTTPS seçenekleri:

• Certificatesertifika kaynağını yapılandırıyor.
• Protocols izin verilen HTTP protokollerini yapılandırıyor.
• SslProtocols izin verilen SSL protokollerini yapılandırıyor.
• ClientCertificateModeistemci sertifikası gereksinimlerini yapılandırmaktadır.

Ana bilgisayar adı joker karakter eşleştirmeyi destekler:

• Tam eşleşme. Örneğin, a.example.org ile eşleşir a.example.org.
• Joker karakter ön eki. Birden çok joker karakter eşleşmesi varsa en uzun desen seçilir. Örneğin, *.example.org ve c.example.orgile eşleşirb.example.org.
• Tam joker karakter. * , SNI kullanmayan ve ana bilgisayar adı göndermeyen istemciler de dahil olmak üzere diğer her şeyle eşleşir.

Eşleşen SNI yapılandırması, bağlantının uç noktasına uygulanır ve uç nokta üzerindeki değerleri geçersiz kılılır. Bir bağlantı yapılandırılmış bir SNI ana bilgisayar adıyla eşleşmiyorsa, bağlantı reddedilir.

SNI'yi kodla yapılandırma

Kestrel birkaç geri çağırma API'siyle SNI'yı destekler:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI ile ServerCertificateSelector

Kestrel geri çağırma yoluyla SNI'yi ServerCertificateSelector destekler. Uygulamanın ana bilgisayar adını incelemesine ve uygun sertifikayı seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır:

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 ile ServerOptionsSelectionCallback

Kestrel geri çağırma yoluyla ServerOptionsSelectionCallback ek dinamik TLS yapılandırmasını destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı ve TLS yapılandırmasını seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır. Varsayılan sertifikalar ve ConfigureHttpsDefaults bu geri çağırma ile kullanılmaz.

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 ile TlsHandshakeCallbackOptions

Kestrel geri çağırma yoluyla TlsHandshakeCallbackOptions.OnConnection ek dinamik TLS yapılandırmasını destekler. Uygulamanın konak adını incelemesine ve uygun sertifikayı, TLS yapılandırmasını ve diğer sunucu seçeneklerini seçmesine izin vermek için bağlantı başına bir kez geri arama çağrılır. Varsayılan sertifikalar ve ConfigureHttpsDefaults bu geri çağırma ile kullanılmaz.

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

HTTP protokollerini yapılandırma

Kestrel yaygın olarak kullanılan tüm HTTP sürümlerini destekler. Uç noktalar, kullanılabilir HTTP sürümü seçeneklerini belirten sabit listesi kullanılarak HttpProtocols farklı HTTP sürümlerini destekleyecek şekilde yapılandırılabilir.

Birden fazla HTTP sürümünü desteklemek için TLS gereklidir. TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışması, bir uç nokta birden çok protokolü desteklediğinde istemci ile sunucu arasında bağlantı protokolü anlaşması yapmak için kullanılır.

HttpProtocols değer	Bağlantı protokolüne izin verilir
Http1	Yalnızca HTTP/1.1. TLS ile veya TLS olmadan kullanılabilir.
Http2	Yalnızca HTTP/2. TLS olmadan yalnızca istemci Önceki Bilgi modunu destekliyorsa kullanılabilir.
Http3	Yalnızca HTTP/3. TLS gerektirir. İstemcinin yalnızca HTTP/3 kullanacak şekilde yapılandırılması gerekebilir.
Http1AndHttp2	HTTP/1.1 ve HTTP/2. HTTP/2, istemcinin TLS Uygulama Katmanı Protokolü Anlaşması (ALPN) el sıkışmasında HTTP/2'yi seçmesini gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1 olur.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 ve HTTP/3. İlk istemci isteği normalde HTTP/1.1 veya HTTP/2 kullanır ve alt-svc yanıt üst bilgisi istemciden HTTP/3'e yükseltmesini ister. HTTP/2 ve HTTP/3 TLS gerektirir; aksi takdirde, bağlantı varsayılan olarak HTTP/1.1'dir.

Uç nokta için varsayılan protokol değeri şeklindedir HttpProtocols.Http1AndHttp2.

HTTP/2 için TLS kısıtlamaları:

• TLS sürüm 1.2 veya üzeri
• Yeniden anlaşma devre dışı bırakıldı
• Sıkıştırma devre dışı bırakıldı
• Minimum kısa ömürlü anahtar değişimi boyutları:
  • Eliptik eğri Diffie-Hellman (ECDHE) [RFC4492]: en az 224 bit
  • Sonlu alan Diffie-Hellman (DHE) [TLS12]: 2048 bit minimum
• Şifre paketi yasak değildir.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] ile P-256 üç nokta eğrisi [FIPS186] varsayılan olarak desteklenir.

appsettings.json'de HTTP protokollerini yapılandırma

Aşağıdaki appsettings.json örnekte, belirli bir uç nokta için HTTP/1.1 bağlantı protokolü oluşturulur:

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

Bölümünde varsayılan bir protokol yapılandırılabilir Kestrel:EndpointDefaults . Aşağıdaki appsettings.json örnek, tüm uç noktalar için varsayılan bağlantı protokolü olarak HTTP/1.1'i oluşturur:

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

Yapılandırmaya göre ayarlanan kod geçersiz kılma değerlerinde belirtilen protokoller.

Kodda HTTP protokollerini yapılandırma

ListenOptions.Protocols , sabit listesiyle HttpProtocols protokolleri belirtmek için kullanılır.

Aşağıdaki örnek, bağlantı noktası 8000'de HTTP/1.1, HTTP/2 ve HTTP/3 bağlantıları için bir uç nokta yapılandırılır. Bağlantıların güvenliği, sağlanan bir sertifikayla TLS tarafından sağlanır:

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

Ayrıca bkz.

• Kestrel ASP.NET Core'da web sunucusu
• ASP.NET Core Kestrel web sunucusu seçeneklerini yapılandırma