Comprehensive Guide to Configuring Kestrel Server for Non-Localhost Requests in ASP.NET Core

Introduction

When deploying ASP.NET Core applications, the Kestrel server by default listens only to localhost requests, which restricts access from external networks. Based on high-scoring answers from Stack Overflow, this article systematically explains how to configure Kestrel to accept non-localhost requests, covering the evolution from early versions to modern .NET Core.

Early Version Configuration: hosting.json and project.json

In early versions of ASP.NET 5 and MVC 6, Kestrel was configured via the hosting.json file. This file underwent multiple name changes, but when using the "commands" section in project.json, the system automatically reads hosting.json. For example:

"commands": {
    "web": "Microsoft.AspNet.Server.Kestrel"
}

After executing dnx web from the command line, Kestrel loads settings from hosting.json. To listen on port 5000 for all IPv4 addresses, the configuration file should include:

{
    "server.urls": "http://0.0.0.0:5000"
}

To support both IPv4 and IPv6, configure it as:

{
    "server.urls": "http://::5000;http://0.0.0.0:5000"
}

Additionally, custom configuration files can be specified via the ASPNET_ENV environment variable or command-line arguments, e.g.:

SET ASPNET_ENV=Development

and create hosting.Development.json, or define multiple commands in project.json:

"commands": {
    "web": "Microsoft.AspNet.Server.Kestrel",
    "webProd": "Microsoft.AspNet.Server.Kestrel --config prod.json"
}

Security and Firewall Configuration

On Windows servers, firewall and URL registration must be configured to allow external access. Use the following commands to open port 5000:

netsh http add iplisten ipaddress=0.0.0.0:5000
netsh http add iplisten ipaddress=::5000
netsh http add urlacl url=http://+:5000/ user=\Everyone

To enhance security, adjust these settings based on the principle of least privilege. Note that using * as a wildcard (e.g., http://*:5000) listens on all IP addresses, but avoid duplicate configurations with 0.0.0.0 or :: to prevent address double-registration.

Programmatic Configuration in ASP.NET Core RC2 and Later

From RC2 onward, configuration shifted to a programmatic approach. In the Main method, settings are loaded via WebHostBuilder and ConfigurationBuilder:

public static void Main(string[] args)
{
    var config = new ConfigurationBuilder()
        .SetBasePath(Directory.GetCurrentDirectory())
        .AddJsonFile("hosting.json", optional: true)
        .AddEnvironmentVariables(prefix: "ASPNETCORE_")
        .AddCommandLine(args)
        .Build();

    var host = new WebHostBuilder()
        .UseUrls("http://*:1000", "https://*:1234", "http://0.0.0.0:5000")
        .UseEnvironment("Development")
        .UseConfiguration(config)
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .Build();

    host.Run();
}

This code binds multiple addresses by default and overrides settings via .UseConfiguration(config). The configuration priority is: command-line arguments > environment variables > hosting.json > UseUrls defaults. For example, running dotnet.exe run --server.urls=http://0.0.0.0:5000 overrides file settings.

Modern .NET Core Configuration Methods

In ASP.NET Core 2.1 and later, it is recommended to configure Kestrel endpoints in appsettings.json:

"Kestrel": {
  "EndPoints": {
    "Http": {
      "Url": "http://0.0.0.0:5002"
    }
  }
}

The environment variable name has also been updated to ASPNETCORE_URLS, e.g., set ASPNETCORE_URLS=http://localhost:12541/. This simplifies cross-environment configuration.

Summary and Best Practices

Configuring Kestrel to listen for non-localhost requests requires considering version differences, security, and flexibility. Early versions rely on hosting.json, while modern versions favor programmatic or appsettings.json configuration. Key steps include: correctly setting IP addresses (e.g., 0.0.0.0 or *), configuring firewalls, and leveraging environment variables for dynamic control. Always adhere to the principle of least privilege and test external access to ensure configuration effectiveness.