Document HSTS (HTTP Strict Transport Security) configuration and best practices

[Adam-D-Lewis]

Overview

Nebari now supports HSTS (HTTP Strict Transport Security) configuration. We need to add documentation to help users understand what HSTS is, how it's configured in Nebari, and best practices for using it safely.

What is HSTS?

HSTS (HTTP Strict Transport Security) is a security feature that forces browsers to only connect to a website over HTTPS, never HTTP. Once a browser receives the HSTS header, it will automatically upgrade all HTTP requests to HTTPS for the specified duration (max-age), protecting against downgrade attacks and cookie hijacking.

Important: HSTS can lock users out of their site if misconfigured, so proper testing is critical.

Documentation Tasks

1. Add HSTS Configuusersration Section

Create a new section (or subsection under security/ingress) that explains:

• What HSTS is: Brief explanation of the security feature and why it matters
• How HSTS works: Browser caching behavior, max-age concept
• When HSTS is enabled by default in Nebari:
  • Automatically enabled for lets-encrypt and existing certificate types
  • Disabled for selfsigned certificates (default)
  • Users can override via ingress.hsts configuration

2. Update Deployment Guides

For each deployment guide (AWS, GCP, Azure, local), add guidance on HSTS:

Initial Deployment

When users run nebari init, they will see this configuration in their nebari-config.yaml:

ingress:
  hsts:
    enabled: true  # or false, depending on certificate type
    max_age: 31536000
    include_subdomains: true
    preload: false

3. Configuration Reference

Document all HSTS options:

• enabled (bool): Enable/disable HSTS headers
• max_age (int): Duration in seconds browsers should remember HSTS policy
• include_subdomains (bool): Apply HSTS to all subdomains
• preload (bool): Adds the preload directive to the HSTS header
  • Setting this to true includes the preload directive in the header
  • To actually get on the HSTS preload list, you must also manually submit your domain at https://hstspreload.org/
  • Warning: Once on the preload list, removal is difficult and slow. Only enable if you're committed to HTTPS forever.

4. Troubleshooting Section

Add common issues and solutions:

Problem: "I can't access my site and get HTTPS errors"

• Cause: HSTS is enabled but certificate is invalid/expired
• Solution:
  • If max_age is high, need to clear HSTS in browser settings, set max_age to 0 and redeploy. This tells browsers to immediately forget the HSTS policy.

5. Security Best Practices

• Only enable preload if you plan to submit to the HSTS preload list AND are committed to HTTPS forever
• Test certificate renewals before they expire

Related Files in nebari Repository

• src/_nebari/stages/kubernetes_ingress/__init__.py
• src/_nebari/initialize.py
• src/_nebari/stages/kubernetes_ingress/template/modules/kubernetes/ingress/hsts-middleware.tf

References

• MDN: Strict-Transport-Security
• OWASP HSTS Cheat Sheet
• HSTS Preload List Submission