HSTS – HTTP Strict Transport Security for Java APIs

Direct Answer

HSTS is the Strict-Transport-Security response header that tells supporting browsers to use HTTPS for a host for a stated max-age. After the browser receives the policy over a valid HTTPS connection, it upgrades later HTTP navigations and refuses click-through on certificate errors. It does not protect the first visit unless the site is preloaded, and most non-browser API clients do not use browser HSTS state. includeSubDomains and preload should be enabled only after every affected host is ready for permanent HTTPS.

Code Example

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.headers(headers -> headers
        .httpStrictTransportSecurity(hsts -> hsts
            .includeSubDomains(true)
            .preload(true)
            .maxAgeInSeconds(31536000)));   // 1 year
    return http.build();
}
// Response header sent over HTTPS:
//   Strict-Transport-Security: max-age=31536000; includeSubDomains; preload

Spring Security adds HSTS by default on HTTPS responses; this customizes the directives. Browsers ignore HSTS sent over plain HTTP.

Common Mistakes & Pitfalls

• Confusing HSTS with the certificate: HSTS is a policy header; the certificate is the identity proof. Different things.
• Enabling preload too early: getting onto the preload list is hard to undo — only do it when HTTPS works everywhere.
• Huge max-age before you're ready: if HTTPS breaks, users are locked out for that whole duration.
• Sending HSTS over HTTP: browsers ignore it on plaintext; it only takes effect over HTTPS.
• Forgetting subdomains: without includeSubDomains, an http://api. request can still be stripped.