skip to content

What does the AllowedHosts setting in an ASP.NET Core appsettings.json do, and how should a production app configure host filtering?

level: middleimportance: should knowfreq 38%

answer

  1. Kestrel answers any Host header
  2. template default "*" means off
  3. semicolon-separated, *.domain wildcards
  4. 400: The request hostname is invalid
  5. added for you by WebApplication

basics

~10 s

AllowedHosts feeds the host filtering middleware that WebApplication adds automatically: requests whose Host header is not in the semicolon-separated list get 400. The template's "*" disables it; production should list its real host names.

solid answer

~40 s

The default host builder that `WebApplication.CreateBuilder` uses adds a startup filter that puts `UseHostFiltering()` at the very start of the pipeline, and fills `HostFilteringOptions.AllowedHosts` by splitting the `AllowedHosts` configuration string on `;`. The templates write `"AllowedHosts": "*"`, and `*` (like `0.0.0.0` or `[::]`) turns filtering off. With real names, for example `"refills.pharmacy.example;*.pharmacy.example"`, a request whose `Host` header (port ignored) matches nothing gets `400` with the body "HTTP Error 400. The request hostname is invalid." and an Information log. Kestrel itself accepts any `Host`, so filtering matters wherever code builds absolute URLs from `Request.Host`, such as refill-reminder links. `AllowEmptyHosts` defaults to true, and the list reloads when configuration changes. `AddHostFiltering` and `UseHostFiltering` are for custom setups.

code

json · 3 lines
json
{
  "AllowedHosts": "refills.pharmacy.example;www.pharmacy.example;*.internal.pharmacy.example"
}

go deeper

for a junior

Know that AllowedHosts lists the host names the app answers to, that the template's * turns the check off, and that a mismatch returns 400.

for a middle

Explain how the default builder wires host filtering from configuration, the semicolon format, wildcard subdomains, ignored ports and AllowEmptyHosts.

for a senior

Configure real host names per environment, remember probes and internal names, and connect host filtering to code that builds absolute URLs from Request.Host.

for a principal

Decide whether host validation belongs at the edge, in every app, or both, and how host lists stay in sync with DNS and certificates.

## Why the setting exists Kestrel and HTTP.sys accept a request whatever its `Host` header says. Any code that turns `HttpContext.Request.Host` into an absolute URL, such as a password-reset link, a refill-reminder email, a redirect or a canonical link, then trusts a value the client chose. **Host filtering** rejects requests whose `Host` is not one of the app's real names before any of that code runs. ## How a `WebApplication` wires it up You write no code for the default behaviour: 1. `WebApplication.CreateBuilder` applies the web host defaults, which register a `HostFilteringStartupFilter`. Startup filters wrap the pipeline, so `UseHostFiltering()` runs **before your own middleware**. 2. A post-configure step fills `HostFilteringOptions.AllowedHosts` from the **`AllowedHosts`** configuration value, split on `;`. If the value is missing or empty it falls back to `"*"`. 3. A change-token source makes the middleware pick up edits to `AllowedHosts` when configuration reloads, without a restart. The templates' `appsettings.json` contains `"AllowedHosts": "*"`, so out of the box **nothing is filtered**. ## Matching rules | Entry | Matches | |---|---| | `refills.pharmacy.example` | that host, any letter case | | `*.pharmacy.example` | any subdomain of `pharmacy.example`, not the bare domain | | `*`, `0.0.0.0` or `[::]` | everything: filtering is disabled | - The **port is ignored**: `refills.pharmacy.example:8443` matches `refills.pharmacy.example`. - Unicode host names are compared in their punycode form. - `AllowEmptyHosts` (default `true`) lets through requests with no `Host` header, which HTTP/1.0 clients may send; set it to `false` to reject them too. ## What a rejected request looks like - Status **`400 Bad Request`**. - With `IncludeFailureMessage` (default `true`), a small HTML body containing "HTTP Error 400. The request hostname is invalid." - An Information-level log, "The host '...' does not match an allowed host." Because the middleware runs first, no endpoint, authentication or logging middleware of yours sees the request. ## Configuring the refill site - Put the real names in `appsettings.Production.json`: `"AllowedHosts": "refills.pharmacy.example;www.pharmacy.example"`. - Write the value as **one semicolon-separated string**. The default wiring reads only the string at the `AllowedHosts` key; a JSON array leaves that key without a value, so the fallback `"*"` applies and filtering is silently off. - Keep `"*"` in `appsettings.Development.json` if developers use varied local names. - Health probes that call the container by IP address or an internal name must be listed too, or they start failing with `400`. ## When to call `AddHostFiltering` and `UseHostFiltering` yourself - `builder.Services.AddHostFiltering(options => ...)` sets `AllowedHosts`, `AllowEmptyHosts` or `IncludeFailureMessage` in code; the configuration fallback still runs only when the list is empty. - `app.UseHostFiltering()` is needed only for a pipeline that does not use the web host defaults. Calling it again in a `WebApplication` adds a second, redundant check. - Behind a reverse proxy, the `Host` the app sees may be the proxy's internal name unless forwarded headers are processed; how that works is part of the reverse-proxy configuration. ## Not to be confused with | Setting | Checks | On mismatch | |---|---|---| | `AllowedHosts` / `HostFilteringOptions` | the request's `Host` header, for the whole app | `400` before any middleware of yours | | `RequireHost("...")` on an endpoint | the `Host` header, for that endpoint's route match | the endpoint does not match, usually `404` | | CORS origins (`WithOrigins`) | the browser's `Origin` header | CORS response headers are omitted | | `HstsOptions.ExcludedHosts` | the host, to decide whether to send HSTS | no `Strict-Transport-Security` header |

  • Why does an AllowedHosts JSON array in an ASP.NET Core appsettings.json leave every host allowed?
    The default builder reads `Configuration["AllowedHosts"]` as a single string and splits it on semicolons. An array is stored as child keys (`AllowedHosts:0`, `AllowedHosts:1`), so the parent key has no value, the list stays empty, and the fallback `"*"` disables filtering. Write the hosts as one semicolon-separated string.
  • Do you need app.UseHostFiltering() in an ASP.NET Core app built with WebApplication.CreateBuilder?
    No. The web host defaults register a startup filter that adds host filtering ahead of your middleware and bind it to `AllowedHosts`. Call `UseHostFiltering()` only in a pipeline built without those defaults; in a `WebApplication` it just adds a second check.

  • AllowedHosts decides which origins may call the API from a browser.
  • Host filtering compares the port as well as the host name.
  • A WebApplication needs app.UseHostFiltering() before AllowedHosts takes effect.
  • Kestrel rejects unknown Host headers on its own.
  • AllowedHosts must be written as a JSON array of host names.