liveBook · Manning

Preload directive

As explained in ASP.NET Core in Action, 3e

HSTS preload is a browser-supported technique that embeds a site's HTTPS-only policy in browser preload data before the site receives an initial request.

HSTS preload makes a browser treat a site as HTTPS-only before sending its first request. It removes the initial HTTP-request gap that ordinary HSTS cannot prevent, but it commits the site to HTTPS for the long term. section 28.4.1

Prepare an ASP.NET Core application for preload by:

  • Setting the HSTS MaxAge to at least one year; two years are recommended. section 28.4.1
  • Enabling IncludeSubDomains and Preload in the HSTS configuration. section 28.4.1
  • Deploying with a TLS certificate, then submitting the domain at hstspreload.org for inclusion in browsers’ built-in HTTPS-only list. section 28.5

Configure preload in ASP.NET Core

builder.Services.AddHsts(options => { options.Preload = true; options.IncludeSubDomains = true; options.MaxAge = TimeSpan.FromDays(365); options.ExcludedHosts.Add("never-https.com"); }); Use an excluded host for testing when necessary, and do not enable HSTS casually in local environments. Once browsers preload the domain, disabling HTTPS can make the application inaccessible until the policy expires, if it can be removed at all. section 28.4.1

Listing 28.3 Configuring the application HSTS header for preload
builder.Services.AddHsts(options =>
{
    options.Preload = true;                         #1
    options.IncludeSubDomains = true;               #2
    options.MaxAge = TimeSpan.FromDays(365);        #3
    options.ExcludedHosts.Add("never-https.com");   #4
});

Shows the four HSTS settings required for preload in an ASP.NET Core configuration. section 28.4.1

HSTS preload primarily protects browser clients. APIs should generally listen only on HTTPS because mobile applications and backend services do not necessarily apply browser HSTS protections; configure an HTTPS-only URL such as ASPNETCORE_URLS=https://*:5001. section 28.4.3

How ASP.NET Core in Action, 3e covers it

How deep it goes
Explains the first-request limitation, required directives, registration, and HTTPS commitment, but does not detail preload-list removal.
Examples
Uses ASP.NET Core HSTS settings, an excluded test host, preload registration, and an HTTPS-only ASPNETCORE_URLS configuration.
What it assumes
Assumes an HTTPS deployment with a TLS certificate and teaches the browser first-request problem and required HSTS directives.
What you can do after
Configure an ASP.NET Core application for HSTS preload and submit its HTTPS-enabled domain for browser preload-list inclusion.
How it connects
Connects HSTS preload with HTTPS, TLS certificates, HSTS middleware, HTTPS redirection middleware, and HTTPS-only API hosting.
Cover of ASP.NET Core in Action, 3e
liveBookmanning.com
Read ASP.NET Core in Action, 3e on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of ASP.NET Core in Action, 3e. The section links point to the parts of the book it draws on.