U - [HTTP] Docs requirements for SameSite=Lax by default

[chrisdavidmills]

User story

As a web developer, I want to reads docs about the new default SameSite setting, so I can find out how this affects my work.

This contributes to MDN's completeness, and the KR "Increase traffic 5% y/y". MDN users need this information to be able to do their jobs effectively going forward.

Background

Same site cookies were shipped a few versions ago. Browser are now agreeing on a proposed change to treat all new cookies as SameSite=lax by default

This is interesting for 2 reasons:

1. We need to do this to avoid compat issues if other browsers all do it
2. It is an opportunity to work with other vendors to eliminate entire class of security vulnerabilities (CSFR)

We are trying to line up changes to coincide with other browser vendors, and this includes documentation. Chrome are aiming for about Chrome 78, available behind pref since 76. We are not yet 100% sure what Firefox version it will be enabled in, but it'll probably be Fx 71, or maybe even 70.

Docs updates needed on

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies (SameSite section)
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie (mention update to default behavior)

New page needed

• SameSite cookies page; will explain the change in detail, explain the errors you'll see in the console, and give developers advice about what they should do going forward. This will satisfy the need talked about at https://bugzilla.mozilla.org/show_bug.cgi?id=1620334.

We may also do with a hacks post to explain the story (how we fixed CSRF forever! google drove it, we thought of it) and what difference this wil make for web devs. This would also coincide with a more technical write up on the Moz sec blog. If these happen, the engineers will write them and we can help edit them.

Mark Goodwin was the engineering contact for this, now it's being implemented by Andrea Marchesini (baku). Ask him for help if needed.

Acceptance criteria

1. • [x] Prototype SameSite=Lax by default (see also the intent to implement) (Fx 69, behind a pref at this point)
2. • [ ] Enable sameSite=lax by default on Nightly
3. • [ ] Implement sameSite lax-by-default 2 minutes tolerance for unsafe methods
4. • [ ] Need MDN landing page that SameSite console warnings can reference
5. • [ ] MDN docs written as described above.
6. • [ ] hacks and sec blog content reviewed/edited (not sure if this is still needed, will ask)

Enable sameSite=lax by default tracks the release of these changes in final release Fx. Bear in mind that we want to get this done by Fx 76 beta, so we will need to delay communicating that this is enabled in release till a later sprint).

[chrisdavidmills]

I'm clearing the milestone and attachment to Fx71 for now; I was told this would be a big thing to do probably around Fx71, but then heard nothing else about it.

[chrisdavidmills]

More information from chatting to Mike Conca:

• Platform team wants this by the time Fx 76 goes to beta, which will be April 7th, so it needs to go into the Charlie-Delta sprint.
• On the new page talked about in the description, we need information along the lines of https://web.dev/samesite-cookies-explained/#changes-to-the-default-behavior-without-samesite

[Elchi3]

I've started a page here in case folks need a URL for the console message now https://wiki.developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite

Will add some more examples and describe the planned change some more.

Also this hasn't landed in Firefox yet, so I haven't updated the BCD for it yet.

[Elchi3]

So, I think this is done for the moment. mconca seems to be happy with the page (see https://bugzilla.mozilla.org/show_bug.cgi?id=1620334#c4) and we will need to continue this work when it actually lands (probably next sprint with Firefox 76).

[Elchi3]

Given https://blog.chromium.org/2020/04/temporarily-rolling-back-samesite.html, I think this might not be shipped in Firefox either. So, maybe this should be parked instead of scheduled for the next sprint.

[chrisdavidmills]

@Elchi3 thanks for the heads up.

[chrisdavidmills]

I'll put it in 76 for now, and we can remove it when the official line comes in.

[chrisdavidmills]

Confirmation that this is being pushed out to a future version. We'll park it for now.

[hamishwillee]

Review Status - good but a few minor errors and some layout stuff.

• According to Chromium SameSite updates this was enabled by default on all versions after 80 (stable) - i.e retrospectively enabled on a bunch of versions once v84 came out). Generally the version it is said to have appeared in though is v84 (ie in samesite cookies explained).
• BCD for Chromium appears to be up to date with this the former point - listing support from version 80. It is also up to date for Firefox - indicating the value is behind a preference. - Upshot do nothing here for now.
• This appears to not be mentioned in the experimental features
  • Propose not to update this on assumption was removed for a reason.
• There is a slight mix of assuming new behaviour and old behaviour in the docs. In particular Headers > Set-Cookie> SameSite feels to be mostly about the new behaviour while its parent feels to be more "old" behaviour.
  • Generally will move to document the new behaviour "first". Will note that this changed recently though and that they can check BCD for versions.

Actions:

• Doc: Headers > Set-Cookie> SameSite.

  • [x] Add note up top explaining that things have changed, what those changes are, and that this is written assuming the "new way". We can then write the doc as we want to to be and forward reference to the browser compatibility to find out the old way.
  • [x] Add a link to https://web.dev/samesite-cookies-explained/ - it is a good explanation.
  • [x] Verify warnings. Change to using syntax boxes (much easier to read)
  • [x] Add links to what a "first-party context" vs "third party context" means - perhaps here, but check glossary too.
  • [x] Lax
  • [x] Replace with better explanation (top level navigation not clear, and it is incorrect that 3rd party cookies are not sent). E.g.

    Cookies are not sent on normal cross-site subrequests (for example to load images or frames into a third party site), but are sent when a user is navigating to the origin site (i.e. when following a link).

    This is the default cookie value if SameSite has not been explicitly specified in recent browser versions (see the "SameSite: Defaults to Lax" feature in the Browser Compatibility).

• Doc: Headers > Set-Cookie.

  • -[x] Syntax - add Secure to the SameSite=None option.

    Set-Cookie: <cookie-name>=<cookie-value>; SameSite=None

  • -[x] Attributes
    • Add note to SameSite attribute explaining changes. This links to the SameSite Cookies Doc and explains that
    • you need to check compatibility table rows for info
    • That this docs the new behaviour.
    • Then lax and non sections include the new requirements.
  • [x] Update Secure section to note that it must be set if SameSite is None - Decided this is NOT needed.

• Doc: HTTP > Using HTTP cookies. https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies)

  • -[x] SameSite attribute - update to reflect current behaviour and add note explaining that things have changed.
  • -[x] Third party cookies -add note that cookies sending can also be set by the server using SameSite. Not completely relevant to the "thrust" of the section, so done as a note.
    • -[x] See also - add link to same-site doc.

[hamishwillee]

@chrisdavidmills I have updated this as above. Specifically this now updates the three main docs that mention SameSite to reflect the new behaviour, and point people to the BCD at end of pages to check specific versions. Details above.

The impact of this change is that the docs will not go out of date with new releases. So when FF accepts the bug the BCD and release note will update, but the docs will be correct.

I think this can probably be closed with a new doc opened when this feature is actually in the live version.

[chrisdavidmills]

@hamishwillee this is looking great, thanks! Yup, I'll close this. The bug referenced above already has dev-doc-needed set, so we'll pick it up again when the bug is resolved.