Настройка конечных точек для веб-сервера Kestrel для ASP.NET Core

По умолчанию платформа ASP.NET Core привязана к:

  • http://localhost:5000
  • https://localhost:5001 (если присутствует локальный сертификат разработки)

Укажите URL-адреса с помощью следующих параметров:

  • Переменная среды ASPNETCORE_URLS.
  • Аргументы командной строки --urls.
  • Ключ конфигурации узла urls.
  • Метод расширения UseUrls.

Значение, указанное с помощью этих подходов, может быть одной или несколькими конечными точками HTTP и HTTPS (HTTPS при наличии сертификата по умолчанию). Настройте значение в виде списка с разделением точкой с запятой (например, "Urls": "http://localhost:8000;http://localhost:8001").

Дополнительные сведения о таких подходах см. в разделах URL-адреса сервера и Переопределение конфигурации.

Сертификат разработки создается, когда:

В некоторых браузерах требуется явное разрешение доверять локальному сертификату разработки.

Шаблоны проектов настраивают приложения так, чтобы они запускались на базе HTTPS по умолчанию и включали поддержку перенаправления HTTPS и HSTS.

Вызовите методы Listen или ListenUnixSocket из KestrelServerOptions, чтобы настроить префиксы URL-адресов и порты для Kestrel.

UseUrls, аргумент командной строки --urls, ключ конфигурации узла urls и переменная среды ASPNETCORE_URLS тоже работают, однако на них распространяются ограничения, указанные далее в этой статье (для конфигурации конечной точки HTTPS требуется сертификат по умолчанию).

Конфигурация KestrelServerOptions:

ConfigureEndpointDefaults(Action<ListenOptions>)

Указывает конфигурацию Action для выполнения каждой заданной конечной точки. Если вызвать ConfigureEndpointDefaults несколько раз, предыдущие элементы Action будут заменены последним элементом Action.

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

Примечание

К конечным точкам, созданным путем вызова Listen перед вызовом ConfigureEndpointDefaults, не будут применяться значения по умолчанию.

Configure(IConfiguration)

Позволяет Kestrel загружать конечные точки из IConfiguration. Для Kestrel конфигурация должна быть ограничена разделом конфигурации.

Перегрузку Configure(IConfiguration, bool) можно использовать для включения перезагрузки конечных точек при изменении источника конфигурации.

IHostBuilder.ConfigureWebHostDefaults по умолчанию вызывает Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true), чтобы загрузить конфигурацию Kestrel и включить перезагрузку.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Если включена перезагрузка конфигурации и сообщается об изменении, выполняются приведенные ниже действия.

  • Новая конфигурация сравнивается со старой, все конечные точки без изменений конфигурации не изменяются.
  • Для удаленных или измененных конечных точек выделяется 5 секунд для завершения обработки запросов и завершения работы.
  • Запускаются новые или измененные конечные точки.

Клиенты, подключающиеся к измененной конечной точке, могут быть отключены или получить отказ в подключении при перезапуске конечной точки.

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>)

Указывает конфигурацию Action для выполнения каждой конечной точки HTTPS. Если вызвать ConfigureHttpsDefaults несколько раз, предыдущие элементы Action будут заменены последним элементом Action.

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

Примечание

К конечным точкам, созданным путем вызова Listen перед вызовом ConfigureHttpsDefaults, не будут применяться значения по умолчанию.

ListenOptions.UseHttps

Настройте Kestrel для использования протокола HTTPS.

Расширения ListenOptions.UseHttps:

  • UseHttps: настройте Kestrel для использования протокола HTTPS с сертификатом по умолчанию. Создает исключение, если сертификат по умолчанию не настроен.
  • 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:

  • filename — это путь и имя файла сертификата, связанного с каталогом, где находятся файлы содержимого приложения.
  • password — это пароль для доступа к данным сертификата X.509.
  • configureOptions — это Action для настройки HttpsConnectionAdapterOptions. Возвращает ListenOptions.
  • storeName — это хранилище сертификатов, из которого выполняется загрузка сертификата.
  • subject — это имя субъекта для сертификата.
  • allowInvalid указывает, следует ли учитывать недопустимые сертификаты, например самозаверяющие сертификаты.
  • location — это расположение хранилища, из которого загружается сертификат.
  • serverCertificate — это сертификат X.509.

В рабочей среде необходимо явно настроить HTTPS. Как минимум необходимо указать сертификат по умолчанию.

Поддерживаемые конфигурации, описанные далее:

  • Отсутствие конфигурации
  • Замена сертификата по умолчанию из конфигурации
  • Изменение значений по умолчанию в коде

Отсутствие конфигурации

Kestrel ожидает передачи данных через http://localhost:5000 и https://localhost:5001 (если доступен сертификат по умолчанию).

Замена сертификата по умолчанию из конфигурации

Kestrel имеет доступ к схеме конфигурации параметров приложения HTTPS по умолчанию. Настройте несколько конечных точек, включая URL-адреса и сертификаты для использования, либо из файла на диске, либо из хранилища сертификатов.

В следующем примере appsettings.json :

  • Установите для AllowInvalid значение true, чтобы разрешить использование недопустимых сертификатов (например, самозаверяющих сертификатов).
  • Любая конечная точка HTTPS, которая не указывает сертификат (HttpsDefaultCert в следующем примере), будет использовать сертификат, определенный в разделе Certificates:Default, или сертификат разработки.
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "<certificate password>"
        }
      },
      "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": "<certificate password>"
      }
    }
  }
}

Примечания к схеме.

  • В имена конечных точек регистр не учитывается. Например, выражение HTTPS and Https являются эквивалентными.
  • Параметр Url является обязательным для каждой конечной точки. Формат этого параметра такой же, как для параметра конфигурации Urls верхнего уровня, только он ограничен одиночным значением.
  • Эти конечные точки заменяют конечные точки, определенные в конфигурации Urls верхнего уровня, а не дополняют их. Конечные точки, определенные в коде через Listen, объединяются с конечными точками, определенными в разделе конфигурации.
  • Раздел Certificate является необязательным. Если раздел Certificate не указан, используются значения по умолчанию, определенные в Certificates:Default. Если значения по умолчанию недоступны, используется сертификат разработки. Если значений по умолчанию нет и сертификат разработки отсутствует, сервер выдаст исключение и не сможет запуститься.
  • Раздел Certificate поддерживает несколько источников сертификатов.
  • В конфигурации можно определить любое количество конечных точек, если это не приводит к конфликту портов.

Источники сертификатов

Узлы сертификатов можно настроить для загрузки сертификатов из нескольких источников:

  • Path и Password для загрузки файлов .pfx;
  • Path, KeyPath и Password для загрузки файлов .pem/ .crt и .key;
  • Subject и Store для загрузки из хранилища сертификатов.

Например, сертификат из раздела Certificates:Default можно указать следующим образом:

"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}")) возвращает KestrelConfigurationLoader с методом .Endpoint(string name, listenOptions => { }), который может использоваться в качестве дополнения для параметров настроенной конечной точки:

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

Можно обратиться напрямую к KestrelServerOptions.ConfigurationLoader, чтобы и далее выполнять итерацию с существующим загрузчиком, например, предоставленным CreateDefaultBuilder.

  • Раздел конфигурации для каждой конечной точки доступен в параметрах в методе Endpoint, чтобы можно было прочитать пользовательские параметры.
  • Можно загрузить несколько конфигураций, снова вызвав options.Configure(context.Configuration.GetSection("{SECTION}")) с другим разделом. Используется только последняя конфигурация, если явным образом не вызвать Load в предыдущих экземплярах. Метапакет не вызывает Load, чтобы можно было заменить его раздел конфигурации по умолчанию.
  • KestrelConfigurationLoader отражает семейство API Listen из KestrelServerOptions как перегрузки Endpoint, чтобы можно было настроить конечные точки кода и конфигурации в одном месте. Эти перегрузки не используют имена и используют только параметры по умолчанию из конфигурации.

Изменение значений по умолчанию в коде

Можно использовать ConfigureEndpointDefaults и ConfigureHttpsDefaults для изменения параметров по умолчанию для ListenOptions и HttpsConnectionAdapterOptions, включая переопределение сертификата по умолчанию, указанного в предыдущем сценарии. Необходимо вызвать ConfigureEndpointDefaults и ConfigureHttpsDefaults, прежде чем настраивать конечные точки.

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

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

Настройка конечных точек посредством указания имени сервера

Можно использовать указание имени сервера (SNI) для размещения нескольких доменов в одном IP-адресе и порте. Для использования SNI клиент отправляет имя узла для безопасного сеанса серверу во время подтверждения TLS, чтобы сервер предоставил правильный сертификат. Клиент использует предоставленный сертификат для зашифрованного соединения с сервером во время безопасного сеанса, который следует после подтверждения TLS.

SNI можно настроить двумя способами:

  • Создав конечную точку в коде и выбрав сертификат, используя имя узла с обратным вызовом ServerCertificateSelector.
  • Настроив сопоставление имен узлов и параметров HTTPS в конфигурации. Например, JSON в файле appsettings.json.

SNI с обратным вызовом ServerCertificateSelector

Kestrel поддерживает SNI через обратный вызов ServerCertificateSelector. Функция обратного вызова используется один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат. Приведенный ниже код обратного вызова можно использовать в вызове метода ConfigureWebHostDefaults файла Program.cs проекта:

//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 с обратным вызовом ServerOptionsSelectionCallback

Kestrel поддерживает дополнительную динамическую конфигурацию TLS через обратный вызов ServerOptionsSelectionCallback. Функция обратного вызова вызывается один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат и конфигурацию TLS. Сертификаты по умолчанию и ConfigureHttpsDefaults не используются с этой функцией обратного вызова.

//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 с обратным вызовом TlsHandshakeCallbackOptions

Kestrel поддерживает дополнительную динамическую конфигурацию TLS через обратный вызов TlsHandshakeCallbackOptions.OnConnection. Функция обратного вызова вызывается один раз за подключение, чтобы приложение проверило имя узла и выбрало соответствующий сертификат, конфигурацию TLS и другие параметры сервера. Сертификаты по умолчанию и ConfigureHttpsDefaults не используются с этой функцией обратного вызова.

//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(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 в конфигурации

Kestrel поддерживает SNI, как определено в конфигурации. Конечную точку можно настроить с помощью объекта Sni, который содержит сопоставление имен узлов и параметров HTTPS. Имя узла подключения сопоставляется с параметрами, которые затем используются для этого подключения.

Следующая конфигурация добавляет конечную точку с именем MySniEndpoint, которая использует SNI для выбора параметров HTTPS на основе имени узла:

{
  "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": "<certificate password>"
            }
          },
          "*": {
            // 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": "<certificate password>"
      }
    }
  }
}

Параметры HTTPS, которые можно переопределить с помощью SNI:

Имя узла поддерживает сопоставление с подстановочными знаками:

  • Точное соответствие. Например, a.example.org соответствует a.example.org.
  • Префикс подстановочного знака. Если определяется несколько совпадений с подстановочными знаками, будет выбран самый длинный шаблон. Например, *.example.org соответствует b.example.org и c.example.org.
  • Подстановочный знак полностью. * соответствует всем остальным элементам, в том числе клиентам, которые не используют SNI и не отправляют имя узла.

Соответствующая конфигурация SNI применяется к конечной точке подключения, переопределяя значения в этой конечной точке. Подключение будет отклонено, если оно не соответствует настроенному имени узла SNI.

Требования SNI

  • Запуск на целевой платформе netcoreapp2.1 или более поздней версии. В net461 или более поздней версии обратный вызов выполняется, но name всегда имеет значение null. name также имеет значение null, если клиент не предоставляет параметр имени узла при подтверждении TLS.
  • Все веб-сайты выполняются на одном и том же экземпляре Kestrel. Kestrel не поддерживает совместное использование IP-адреса и порта на нескольких экземплярах без обратного прокси-сервера.

Протоколы SSL/TLS

Протоколы SSL — это протоколы, используемые для шифрования и расшифровки трафика между двумя одноранговыми узлами, обычно клиентом и сервером.

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": "<certificate password>"
        }
      }
    }
  }
}

Значение по умолчанию SslProtocols.None указывает Kestrel использовать параметры операционной системы по умолчанию для выбора оптимального протокола. Если вам не требуется по какой-либо причине выбрать определенный протокол, используйте значение по умолчанию.

Сертификаты клиента

ClientCertificateMode настраивает требования к сертификату клиента.

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": "<certificate password>"
        }
      }
    }
  }
}

По умолчанию используется значение ClientCertificateMode.NoCertificate, где Kestrel не будет запрашивать или требовать сертификат от клиента.

Для получения дополнительной информации см. Настройка проверки подлинности сертификата в ASP.NET Core.

Ведение журнала подключения

Вызовите UseConnectionLogging, чтобы выдать журналы уровня отладки для обмена данными на уровне байтов в рамках подключения. Ведение журнала подключения полезно для устранения неполадок, связанных с низкоуровневым взаимодействием, например при TLS-шифровании и работе за прокси-серверами. Если UseConnectionLogging поместить перед UseHttps, в журнале регистрируется зашифрованный трафик. Если UseConnectionLogging поместить после UseHttps, в журнале регистрируется расшифрованный трафик. Это встроенное ПО промежуточного слоя подключения.

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

Привязка к TCP-сокету

Метод Listen выполняет привязку к TCP-сокету, а лямбда-выражение параметров позволяет настроить конфигурацию сертификата 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>();
        });

В этом примере настраивается HTTPS для конечной точки с помощью ListenOptions. С помощью этого API можно настроить и другие параметры Kestrel для отдельных конечных точек.

В Windows самозаверяющие сертификаты создаются с помощью командлета PowerShell New-SelfSignedCertificate. Примеры, которые не поддерживаются, см. в разделе UpdateIISExpressSSLForChrome.ps1.

В macOS, Linux и Windows сертификаты создаются с помощью OpenSSL.

Привязка к сокету UNIX

Вы можете прослушивать сокет UNIX с помощью ListenUnixSocket, чтобы улучшить производительность Nginx, как показано в следующем примере:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})
  • В файле конфигурации Nginx установите для записи server > location > proxy_pass значение http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} — это имя сокета, предоставленного для ListenUnixSocket (как kestrel-test.sock в предыдущем примере).
  • Убедитесь, что сокет доступен для записи Nginx (например, chmod go+w /tmp/kestrel-test.sock).

Порт 0

Если указать номер порта 0, Kestrel будет динамически привязан к доступному порту. В следующем примере показано, как определить, к какому порту привязан Kestrel во время выполнения:

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

Когда приложение выполняется, в выходных данных в окне консоли указывается динамический порт, по которому можно связаться с приложением:

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

Ограничения

Настройте конечные точки с помощью следующих подходов:

  • UseUrls
  • Аргументы командной строки --urls.
  • Ключ конфигурации узла urls.
  • Переменная среды ASPNETCORE_URLS.

Эти методы удобны, если нужно, чтобы код работал с серверами, отличающимися от Kestrel. Не забывайте о следующих ограничениях.

  • С этими подходами нельзя использовать HTTPS, если в конфигурации конечной точки HTTPS не предоставлен сертификат по умолчанию (например, с помощью конфигурации KestrelServerOptions или файла конфигурации, как показано выше в этой статье).
  • Если подходы Listen и UseUrls используются одновременно, конечные точки Listen переопределяют конечные точки UseUrls.

Конфигурация конечной точки IIS

При использовании служб IIS привязки URL-адресов для IIS переопределяют привязки, заданные Listen или UseUrls. Дополнительные сведения см. в статье Модуль ASP.NET Core.

ListenOptions.Protocols

Свойство Protocols устанавливает протоколы HTTP (HttpProtocols), разрешенные для конечной точки подключения или для сервера. Значение свойства Protocols должно входить в перечисление HttpProtocols.

Значение перечисления HttpProtocols Допустимый протокол подключения
Http1 Только HTTP/1.1. Можно использовать с протоколом TLS или без него.
Http2 Только HTTP/2. Может использоваться без TLS только в том случае, если клиент поддерживает режим предварительного знания.
Http1AndHttp2 HTTP/1.1 и HTTP/2. Для использования HTTP/2 требуется, чтобы клиент выбрал HTTP/2 при подтверждении согласования протокола уровня приложений (ALPN); в противном случае используется подключение по умолчанию HTTP/1.1.

Значение ListenOptions.Protocols по умолчанию для любой конечной точки равно HttpProtocols.Http1AndHttp2.

Ограничения TLS для HTTP/2:

  • TSL 1.2 или более поздней версии.
  • Повторное согласование отключено.
  • Сжатие отключено.
  • Минимальные размеры обмена временными ключами:
    • эллиптическая кривая Диффи—Хелмана (ECDHE) [RFC4492]: не менее 224 бит;
    • конечное поле Диффи—Хелмана (DHE) [TLS12]: не менее 2048 бит.
  • Набор шифров не запрещен.

По умолчанию поддерживается TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] с эллиптической кривой P-256 [FIPS186].

Следующий пример разрешает подключения HTTP/1.1 и HTTP/2 через порт 8000. Эти подключения шифруются по протоколу TLS с использованием предоставленного сертификата:

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

В Linux для фильтрации подтверждений TLS по каждому соединению можно использовать CipherSuitesPolicy:

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

ПО промежуточного слоя подключения

При необходимости можно использовать ПО промежуточного слоя подключения для фильтрации подтверждений TLS для каждого подключения по конкретным шифрам.

Следующий пример вызывает NotSupportedException для любого алгоритма шифрования, который не поддерживается приложением. Также можно определить и сравнить ITlsHandshakeFeature.CipherAlgorithm со списком приемлемых наборов шифров.

При использовании алгоритма шифрования 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();
            });
        }
    }
}

Фильтрацию соединений также можно настроить с помощью лямбды IConnectionBuilder:

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

Установка протокола HTTP из конфигурации

CreateDefaultBuilder по умолчанию вызывает serverOptions.Configure(context.Configuration.GetSection("Kestrel")), чтобы загрузить конфигурацию Kestrel.

В следующем примере appsettings.json для всех конечных точек устанавливается протокол подключения по умолчанию HTTP/1.1:

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

В следующем примере appsettings.json для отдельной конечной точки устанавливается протокол подключения HTTP/1.1:

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

Указанные в коде протоколы переопределяют значения, заданные в конфигурации.

Префиксы URL-адресов

Если вы используете UseUrls, аргумент командной строки --urls, ключ конфигурации узла urls или переменную среды ASPNETCORE_URLS, префиксы URL-адресов могут иметь любой из указанных ниже форматов.

Допустимы только префиксы URL-адресов HTTP. Kestrel не поддерживает HTTP при настройке привязок URL-адресов с помощью UseUrls.

  • IPv4-адрес с номером порта

    http://65.55.39.10:80/
    

    0.0.0.0 является особым случаем, соответствующим привязке ко всем IPv4-адресам.

  • IPv6-адрес с номером порта

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

    [::] является IPv6-аналогом IPv4-адреса 0.0.0.0.

  • Имя узла с номером порта

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

    Имена узлов, * и +, не являются особыми. Все, что не распознается как допустимый IP-адрес или localhost, привязывается ко всем IP-адресам IPv4 и IPv6. Чтобы привязать разные имена узлов к разным приложениям ASP.NET Core по одному порту, используйте HTTP.sys или обратный прокси-сервер. В качестве обратного прокси-сервера можно использовать IIS, Nginx или Apache.

    Предупреждение

    Для размещения в конфигурации обратного прокси-сервера требуется фильтрация узлов.

  • Имя узла localhost с номером порта или IP-адрес замыкания на себя с номером порта

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

    Если указать localhost, Kestrel попытается привязаться к обоим интерфейсам замыкания на себя IPv4 и IPv6. Если запрошенный порт уже используется другой службой в одном из интерфейсов замыкания на себя, Kestrel не будет запущен. Если один из интерфейсов замыкания на себя недоступен по любой другой причине (чаще всего из-за отсутствия поддержки IPv6), Kestrel зарегистрирует предупреждение.