Chapter 28: Adding HTTPS to an application

Introduction

This chapter introduces HTTPS as an essential protection for client-app traffic and previews local certificates, production Kestrel configuration, and application-wide HTTPS enforcement.

• HTTPS traffic protection: Explain why encrypting traffic between a client and an application with HTTPS is a basic security measure for production apps. State that unencrypted requests and responses can be spied on or modified by third parties while traveling over the internet.
  Why it matters: HTTPS protects the confidentiality and integrity of data moving between users and your application.
• Certificate environment roles: Describe the chapter's distinction between the ASP.NET Core HTTPS development certificate for local work and a real production certificate for deployed applications. State that the development certificate can be trusted locally, whereas Kestrel must be configured to use an acquired custom certificate in production.
  Why it matters: Using the appropriate certificate for each environment lets you develop securely locally and serve HTTPS in production.
• Application-wide HTTPS enforcement: Describe why an application commonly exposes both HTTP and HTTPS ports even though HTTPS is preferred, and identify the chapter's goal of pushing clients toward the HTTPS endpoint. Name the enforcement approaches previewed: HSTS headers, HTTP-to-HTTPS redirection middleware, and rejecting HTTP requests for API applications.
  Why it matters: Enforcement mechanisms reduce the chance that clients continue using insecure HTTP when HTTPS is available.

Key terms: HTTPS, encryption, requests, responses, ASP.NET Core HTTPS development certificate, development certificate, production certificate, Kestrel, custom certificate, HTTP Strict Transport Security

28.1 Why do I need HTTPS?

This section explains why production applications need HTTPS and compares direct HTTPS handling in Kestrel with TLS offloading at a reverse proxy.

• HTTP transport risks: Explain that ordinary HTTP requests and responses are unencrypted plain text, so an attacker on the network can read them and potentially alter them while they are in transit.
  Why it matters: Understanding the risks of HTTP makes clear why transport security is necessary for a production app.
• HTTPS security and adoption: Describe how HTTPS uses a TLS certificate to encrypt HTTP requests and responses so attackers cannot read or modify their contents, and explain why production sites should use it.
  Why it matters: HTTPS protects user data and avoids the security warnings and loss of trust associated with insecure sites.
• HTTPS-dependent capabilities: State that browsers increasingly mark HTTP sites as insecure and that some browser APIs and server-related capabilities, including location, microphone, storage APIs, Brotli compression, and HTTP/2 support, require HTTPS.
  Why it matters: HTTPS affects not only confidentiality but also user trust and access to modern web-platform features.
• TLS termination architectures: Distinguish direct HTTPS support in Kestrel from SSL/TLS offloading at a reverse proxy: with offloading, the proxy encrypts and decrypts browser traffic while the application can receive HTTP.
  Why it matters: The hosting architecture determines whether your application must manage TLS certificates itself.
• Direct Kestrel HTTPS conditions: Describe situations that require or favor configuring a TLS certificate in Kestrel: exposing Kestrel directly to the internet, requiring HTTPS between proxy and application, or using technology such as gRPC and HTTP/2 that generally needs end-to-end HTTPS.
  Why it matters: Recognizing these cases tells you when reverse-proxy termination alone is insufficient.

Key terms: HTTP, unencrypted, plain text, requests, responses, HTTPS, TLS, SSL, TLS certificate, Secure Sockets Layer

28.2 Using the ASP.NET Core HTTPS development certificates

This section explains how ASP.NET Core’s local HTTPS development certificates work, why browsers may reject them, and how to trust or troubleshoot them during development.

• Development certificate defaults: Describe when the .NET SDK installs the ASP.NET Core HTTPS development certificate and how default ASP.NET Core applications use it for local HTTPS when no certificate is explicitly configured.
  Why it matters: Knowing the default certificate behavior helps you understand why a new local app can serve HTTPS without manual certificate setup.
• Certificate trust chain: Explain why a browser does not trust a self-signed or ASP.NET Core development certificate by default, including the role of certificate authorities, trusted root certificates, and the certificate chain.
  Why it matters: This explains why HTTPS can be encrypted yet still produce a browser security warning.
• Local certificate trust procedure: Describe how to trust the HTTPS development certificate on Windows or macOS by running dotnet dev-certs https --trust, and how to recover from persistent warnings by closing browsers and, if needed, cleaning and trusting the certificate again.
  Why it matters: Trusting the local certificate removes development-time browser warnings so you can test HTTPS normally.
• Development environment exceptions: Distinguish the development situations where certificate trust may already be handled from those where extra, scenario-specific setup is required, especially Visual Studio with IIS Express versus Linux, Firefox, WSL, Docker, and Linux API-to-API communication.
  Why it matters: Certificate trust is not uniform across hosts and browsers, so recognizing exceptions prevents misleading local HTTPS failures.
• Production certificate requirements: Explain why development and self-signed certificates are unsuitable for production public sites and state that production certificates should be signed by a trusted CA, such as certificates obtained through Let’s Encrypt or a cloud provider.
  Why it matters: Public users cannot be expected to manually trust your certificate, so production HTTPS needs browser-recognized trust.

Key terms: HTTPS development certificate, .NET SDK, ASP.NET Core default templates, TLS certificate, public key, private key, certificate authority, CA, root certificate, dotnet dev-certs https --trust

28.3 Configuring Kestrel with a production HTTPS certificate

This section explains how to obtain and securely configure a production TLS certificate as Kestrel’s default HTTPS certificate, so an app can serve encrypted traffic outside development.

• Production certificate trust: Explain why obtaining a production TLS certificate normally involves proving domain ownership to a third-party certificate authority, and how that process helps prevent attackers from impersonating a server.
  Why it matters: A browser can safely trust your HTTPS server only when its certificate establishes that the server is entitled to use the domain.
• Kestrel production certificate configuration: Describe how to configure Kestrel’s default certificate for HTTPS in production by supplying certificate settings through configuration, such as a .pfx file path and its password. State that Kestrel otherwise uses the development certificate when an HTTPS URL is configured without certificate settings.
  Why it matters: Kestrel needs an explicit production certificate configuration to present the appropriate certificate to real users.
• Certificate secret handling: Justify keeping production certificate passwords out of appsettings.json and source-controlled files. Describe safer alternatives from this section: load the value from a configuration store such as user-secrets, or load the certificate from the local OS certificate store.
  Why it matters: Hardcoding or committing a certificate password can expose the private credential that protects your HTTPS identity.

Key terms: TLS certificate, certificate authority, CA, domain ownership, trust process, Kestrel, development certificate, default certificate, Kestrel:Certificates:Default, .pfx

28.4 Enforcing HTTPS for your whole app

This section introduces why and how an ASP.NET Core application should enforce HTTPS, including browser behavior, reverse-proxy considerations, and the three approaches covered next.

• HTTPS enforcement rationale: Explain why enforcing HTTPS across a website is practically required: browsers label HTTP pages as insecure, TLS protects sensitive data in transit, and HTTPS enables modern browser use of HTTP/2, which can improve performance.
  Why it matters: HTTPS protects users' transmitted data and avoids browsers treating your application as insecure.
• HTTPS enforcement approaches: Describe the three HTTPS-enforcement approaches previewed in this section: HSTS headers, redirecting HTTP requests to HTTPS, and rejecting HTTP requests for API applications.
  Why it matters: Choosing the appropriate enforcement behavior lets an application move clients away from insecure HTTP connections.
• Reverse-proxy TLS offloading: Describe how a reverse proxy that performs SSL/TLS offloading may already handle HTTPS enforcement, so some in-application steps in this section may not be necessary.
  Why it matters: Knowing where TLS is terminated prevents duplicating HTTPS responsibilities or configuring unnecessary application behavior.

Key terms: HTTPS, TLS, HTTP/2, HTTP/3, HTTP Strict Transport Security, HSTS, HTTPS redirection middleware, HTTP security headers, reverse proxy, SSL/TLS offloading

28.4.1 Enforcing HTTPS with HTTP Strict Transport Security headers

This section explains how HSTS headers make browsers prefer HTTPS after a secure visit, how to configure them safely in ASP.NET Core, and how HSTS preload removes the first-request gap.

• HSTS browser behavior: Explain that the Strict-Transport-Security HSTS header tells a browser to use HTTPS for subsequent requests to an application, including when a user enters an HTTP URL or follows an HTTP link.
  Why it matters: HSTS prevents a browser that has visited your site securely from later falling back to insecure HTTP.
• HSTS scope and first request: Distinguish HSTS's browser-only scope from server-to-server and mobile-app traffic, and explain why it cannot protect a browser's first HTTP request.
  Why it matters: Knowing HSTS's first-request limitation explains why an application needs additional HTTPS enforcement measures.
• HSTS middleware configuration: Describe configuring ASP.NET Core's HstsMiddleware to send HSTS headers, including using MaxAge cautiously at first and increasing it only after HTTPS is known to work reliably.
  Why it matters: A long HSTS lifetime creates a real commitment: clients can be unable to reach an app that later stops serving HTTPS.
• HSTS preload commitment: Explain that HSTS preload places a site's HTTPS requirement into modern browsers to avoid the first-request problem, but commits the site to HTTPS for the long term and requires specific header directives before submission.
  Why it matters: Preload can prevent even an initial HTTP request, but its difficult reversal makes it appropriate only after HTTPS is a permanent, reliable choice.

Key terms: HTTP Strict Transport Security, HSTS, Strict-Transport-Security header, HTTPS, HstsMiddleware, MaxAge, HSTS header, Program.cs, HSTS preload, preload directive

28.4.2 Redirecting from HTTP to HTTPS with HTTPS redirection middleware

This section explains how HTTPS redirection middleware redirects insecure requests, how to configure it correctly behind a reverse proxy, and why it is paired with HSTS.

• HTTPS redirection behavior: Describe how HttpsRedirectionMiddleware enforces HTTPS by short-circuiting an HTTP request with a redirect so the browser repeats the request over HTTPS. State that it normally redirects to the first configured HTTPS endpoint using HTTP 307 Temporary Redirect.
  Why it matters: This middleware prevents HTTP requests that reach your application from continuing through the normal request pipeline.
• Redirection middleware configuration: Explain where to add UseHttpsRedirection in the Program.cs middleware pipeline and how its HTTPS target is determined or overridden. Describe that it is typically placed after error handling and HstsMiddleware, and that ASPNETCORE_HTTPS_PORT can specify a different redirect port when necessary.
  Why it matters: Correct placement and port configuration let redirection work predictably in the application's deployment environment.
• Forwarded protocol handling: Explain why an application behind a TLS-terminating reverse proxy needs ForwardedHeadersMiddleware to process X-Forwarded-Proto. Describe that the middleware marks a request originally received as HTTPS as secure, and that it must run before UseHsts or UseHttpsRedirection when configured manually.
  Why it matters: Without forwarded protocol handling, an app behind a reverse proxy can mistake secure client requests for HTTP and apply HTTPS middleware incorrectly.
• Whole-application HTTPS enforcement: Justify applying HSTS together with HTTPS redirection across a browser-facing server-side application rather than redirecting only selected pages. State the remaining first-request weakness: browsers initially request HTTP by default unless HSTS preload tells them to use HTTPS from the start.
  Why it matters: Consistent, application-wide HTTPS enforcement reduces the chance that an unprotected route becomes a security hole.

Key terms: HttpsRedirectionMiddleware, HTTPS redirection, HTTP 307 Temporary Redirect, short-circuits, HTTPS endpoint, UseHttpsRedirection, Program.cs, HstsMiddleware, ASPNETCORE_HTTPS_PORT, Kestrel

28.4.3 Rejecting HTTP requests in API applications

This section explains why API applications should disable HTTP entirely and serve only HTTPS requests.

• HTTPS-only API rationale: Explain why API applications should generally listen only for HTTPS rather than relying on browser protections or HTTP-to-HTTPS redirection.
  Why it matters: API clients can include mobile apps and backend services that do not receive the HTTPS protections built into web browsers.
• HTTPS-only URL configuration: Describe how to disable HTTP handling by configuring the application's URLs to include only https:// addresses, such as through ASPNETCORE_URLS.
  Why it matters: When the app does not listen for HTTP connections, clients cannot accidentally send insecure HTTP requests to it.
• Redirection middleware elimination: Explain why an HTTPS-only API listener can simplify the application by removing the need for HTTP redirection middleware.
  Why it matters: Rejecting HTTP at the listener provides the security boundary directly instead of maintaining a redirect path.

Key terms: API application, HTTPS, HTTP, HSTS, HSTS preload, ASPNETCORE_URLS, https://, HTTP connections, port 5001, HTTPS redirection middleware

28.5 Summary

This summary recaps why production ASP.NET Core apps need HTTPS, how certificates can be provided in development and production, and how to enforce HTTPS-only access.