SEC-3038: Warn of default HSTS header impact in migration docs

[spring-projects-issues]

Thomas Timbul (Migrated from SEC-3038) said:

The enabling of HSTS by default can have a huge impact on sites that have never used HSTS before and may be unaware that this can (and likely will) break a site with mixed content.

Although the documentation mentions that HSTS is now enabled by default, there should be a large and explicit warning that it should either be disabled explicitly (though perhaps not recommended), or ALL content must be switched to using https.
It should be clearly highlighted that in simple terms the effect of HSTS is for the browser to permanently (for a year) remember your site as using https only, so that having both http content and HSTS will cause infinite redirects in browsers that support HSTS (i.e. all modern ones).

The steps to remedy should then be explained in case this issue had been encountered (for example configure HSTS with max-age=0).

[spring-projects-issues]

Thomas Timbul said:

Rob, I appreciate your comments on https://jira.spring.io/browse/SEC-2678. Is there a way I can preview the fixed version of the documentation? I'd like to see what's been done already before I just copy and paste (and maybe you've already addressed it very well in the latest).

[spring-projects-issues]

Rob Winch said:

Thanks for the feedback. You can find the latest migration guide at http://docs.spring.io/spring-security/site/docs/current-SNAPSHOT/reference/htmlsingle/#m3to4

NOTE: Since the reference links to the latest version of the migration guide, it should always be up to date.

[spring-projects-issues]

Thomas Timbul said:

Thanks, while reviewing the latest documentation and migration guide, I would like to propose the following further improvements to avoid people falling into the same trap as I did:

Migration is shown as being from 3.x to 4.x. We should therefore take account of the fact that 3.x includes 3.0 and 3.1, neither of which had HSTS enabled by default. (Note that I myself upgraded from 3.1 and didn't stand a chance)

Documentation:
2.3 Migrating from 3.x to 4.x:
Allude to the fact that those migrating from pre-3.2 need to pay close attention to security headers configuration, HSTS in particular, as it could break their current site.

Migration guide:
1. Introduction

• The non-passive changes link should include non-passive changes introduced since version 3.1 inclusive
• Make explicit mention of the fact that users upgrading from pre-3.2 will need to pay close attention to security headers configuration, HSTS in particular, as it could break their current site.
• Link the above into section 6.6

6.6. Migrating

• Use a warning triangle to highlight the section about HSTS, instead of the current information icon
• Try using normal font on coloured background, not pale font on white - or anything else that will draw more attention to the warning
• emphasise "infinite redirects" in that paragraph by using bold and/or darker text (whatever draws the most attention)
• Use "Strict Transport Security (HSTS)" as the link text for http://docs.spring.io/spring-security/site/docs/current/reference/html/headers.html#headers-hsts in that paragraph
• Mention that sites using require-channel="http" are affected, and that users should consider other applications deployed on the same host.
• Explicitly state that if you rely on mixed content anywhere on the same domain (especially forced http content outside own control) you must either upgrade all content to also using https (recommended if possible), or disable HSTS. Explain that HSTS sets a long-lifetime cookie which causes browsers to always want to use https. This should be followed by advice on how to avoid explicit http redirects in both Spring Security and the application as a whole (for upgrading), then by how to correctly disable HSTS in the alternative.
• Explain how to get out of the hole if user has already sent the headers
• "Developers are encouraged to read Security HTTP Response Headers for details on using this feature." - The link in this sentence does not link to anywhere else. Unfortunately I don't know where it was meant to link to.

Back in the documentation:
http://docs.spring.io/spring-security/site/docs/current/reference/html/headers.html#headers-hsts

Apply the same principles in this section and issue the same warnings as in the migration guide (using HSTS with mixed content is a no-no, it all has to be https on the entire domain, infinite redirects otherwise, etc, etc)
Tell users how to disable, and how to get out of the rut if they weren't careful or want to just undo it.

I realise it's almost babysitting, but because it's such a big impact change, it absolutely needs to be done. By putting more meat into the explanation (and connecting to the bank website example), things will become clearer to anyone upgrading from when it was modern to use https only for checkout and secure account pages (that includes myself).

[spring-projects-issues]

Thomas Timbul said:

I realise that since the docs are generated, style based suggestions may not be as simple as 'hacking the stylesheet' to alter appearance from the standard.
I'd also like to add that perhaps it's not necessary to duplicate everything, but it should at a minimum be in the main documentation and prominently linked to from the migration guide (which is what existing users will read, but new users won't). The goal must be to draw more attention to the implications of HSTS for the entire site, starting in the Introduction and even mentioning in "what's new".