What does the AllowedHosts setting in an ASP.NET Core appsettings.json do, and how should a production app configure host filtering?
answer
- Kestrel answers any Host header
- template default "*" means off
- semicolon-separated, *.domain wildcards
- 400: The request hostname is invalid
- added for you by WebApplication
basics
~10 sAllowedHosts 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 sThe 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{
"AllowedHosts": "refills.pharmacy.example;www.pharmacy.example;*.internal.pharmacy.example"
}go deeper
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.
Explain how the default builder wires host filtering from configuration, the semicolon format, wildcard subdomains, ignored ports and AllowEmptyHosts.
Configure real host names per environment, remember probes and internal names, and connect host filtering to code that builds absolute URLs from Request.Host.
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.