How does ASP.NET Core's UseHttpsRedirection choose the redirect status and the HTTPS port, and why might it not redirect at all?
answer
- a port it cannot find
- RedirectStatusCode: 307, or 308 if set
- HttpsPort, then HTTPS_PORT configuration
- then the server's https address
- warning: Failed to determine the https port
basics
~10 sThe status comes from HttpsRedirectionOptions.RedirectStatusCode, 307 unless you set 308. The port comes from HttpsPort, then HTTPS_PORT configuration, then the server's https address; with none, it logs a warning and does not redirect.
solid answer
~40 s`HttpsRedirectionOptions.RedirectStatusCode` defaults to `307`; set `Status308PermanentRedirect` for a permanent, method-preserving redirect, usually only outside Development because browsers cache it. The port is resolved once, lazily: `HttpsRedirectionOptions.HttpsPort` if set; otherwise the `HTTPS_PORT` configuration key (the `https_port` host setting, `ASPNETCORE_HTTPS_PORT`, or a top-level `https_port` in appsettings), or `ANCM_HTTPS_PORT` under IIS; otherwise the single `https` address in `IServerAddressesFeature`, throwing if it finds two different ones. If all fail, it logs the warning "Failed to determine the https port for redirect." and passes the request on unredirected. That is the usual cause in a container listening only on HTTP port 8080. Don't confuse `HTTPS_PORT` with `HTTPS_PORTS`, which tells Kestrel which ports to listen on.
code
json · 4 lines{
"https_port": 443,
"AllowedHosts": "refills.pharmacy.example"
}go deeper
Know that UseHttpsRedirection needs to know an HTTPS port, and that it defaults to 307 rather than a permanent redirect.
Explain the port resolution order, the HTTPS_PORT versus HTTPS_PORTS distinction, why 443 is left out of the URL, and what the warning means when no port is found.
Diagnose missing or looping redirects in containers and behind proxies, choose 307 or 308 per environment, and decide whether the app or the edge should redirect at all.
Set one rule for where HTTP-to-HTTPS redirection happens across services and environments, so that apps, proxies and load balancers do not fight over it.
## The status code: `307` or `308` `HttpsRedirectionOptions.RedirectStatusCode` is an `int` defaulting to `StatusCodes.Status307TemporaryRedirect`. | Code | Permanent? | Method and body kept? | Cached by browsers? | |---|---|---|---| | `307 Temporary Redirect` (default) | no | yes | no | | `308 Permanent Redirect` | yes | yes | yes | | `301 Moved Permanently` | yes | clients may switch POST to GET | yes | The docs recommend the temporary code in general, because cached permanent redirects make environments behave unpredictably during development. A production site that is HTTPS-only for good can switch to `308` in non-Development environments; HSTS then takes over for returning browsers anyway. ## How the port is found The middleware resolves the port through a `Lazy<int>`, so it is computed on the first insecure request and then **fixed for the app's lifetime**: 1. **`HttpsRedirectionOptions.HttpsPort`**, if set through `AddHttpsRedirection`. 2. The configuration key **`HTTPS_PORT`**, which the `ASPNETCORE_HTTPS_PORT` environment variable, the `https_port` host setting or a top-level `"https_port"` entry in `appsettings.json` all supply (configuration keys are case-insensitive), then `ANCM_HTTPS_PORT`, which the IIS module provides. 3. The **`IServerAddressesFeature`** addresses: the port of the `https` binding. If two `https` bindings have different ports it throws `InvalidOperationException` asking you to set `HttpsPort` explicitly. 4. Otherwise **no port**: the warning "Failed to determine the https port for redirect." is logged and the request continues unredirected. When the port is 443 it is left out of the `Location` URL; any other port is included. ## Why it sometimes does not redirect - **Container images** set `ASPNETCORE_HTTP_PORTS=8080` and listen on HTTP only, so the server has no `https` address and nothing configures `HTTPS_PORT`. The app logs the warning and serves HTTP. Usually TLS is terminated in front of the container, and redirection belongs there. - **Behind a reverse proxy** the server addresses describe the internal binding, not the public port, and `Request.IsHttps` reflects the proxy-to-app hop. Making the app see the original scheme is the forwarded-headers configuration's job; until then the middleware may redirect requests that the user already sent over HTTPS. - **`HTTPS_PORTS` versus `HTTPS_PORT`**: the plural key sets Kestrel's listening ports; the singular key sets the redirect target. Kestrel listening on HTTPS lets the middleware discover the port indirectly, but the keys are not interchangeable. ## Configuring it for the pharmacy refill site ```csharp if (!builder.Environment.IsDevelopment()) { builder.Services.AddHttpsRedirection(options => { options.RedirectStatusCode = StatusCodes.Status308PermanentRedirect; options.HttpsPort = 443; }); } ``` In Development the launch profile's `https://localhost:<port>` binding is discovered from the server addresses, so the default `307` and discovery are enough. ## Checklist when a redirect is missing or wrong 1. Look for the Warning-level "Failed to determine the https port for redirect." in the `Microsoft.AspNetCore.HttpsPolicy` logs; the template's log levels show it. 2. Check whether `HttpsPort`, `HTTPS_PORT` or an `https` server address exists in that environment. 3. If the redirect points at an internal port, set `HttpsPort` (or `HTTPS_PORT`) to the public one. 4. If HTTPS requests are being redirected again, fix how the app learns the original scheme behind the proxy rather than removing the middleware.
- Why can switching ASP.NET Core's HTTPS redirect to 308 be hard to undo?`308 Permanent Redirect` is cacheable, so browsers remember that the `http://` URL moved and skip asking the server next time. If you later need plain HTTP on that host, for example during a certificate problem, returning visitors keep going to HTTPS until their cache entry expires. That is why the default is `307` and the docs suggest `308` only once HTTPS is permanent.
- An ASP.NET Core app has two HTTPS bindings on different ports and no HttpsPort set. What does UseHttpsRedirection do?On the first insecure request it reads `IServerAddressesFeature`, finds two `https` addresses with different ports, and throws `InvalidOperationException`: it cannot determine the https port, multiple values were found, set `HttpsRedirectionOptions.HttpsPort` explicitly. Setting `HttpsPort` or `HTTPS_PORT` removes the ambiguity.
- If no HTTPS port is found, UseHttpsRedirection redirects to 443 anyway.
- HTTPS_PORTS and HTTPS_PORT mean the same thing.
- A 308 redirect turns a POST into a GET.
- UseHttpsRedirection looks the HTTPS port up again on every request.
- Behind a TLS-terminating proxy, Request.IsHttps is true without any extra configuration.