Support SameSite Cookie Attribute

In  undertow

Overview

When it comes to SameSite cookie attributes, currently Undertow conforms to the "Cookies: HTTP State Management Mechanism" draft proposed in draft-ietf-httpbis-rfc6265bis-02, at August 2017.

Since early 2019, three more drafts were submitted and changes in the attribute were made. The current version can be viewed in draft 5, valid until August 2020. The main change is that "None" was added as a SameSite option, and set by default if SameSite attribute contained any value other than "Strict" and "Lax".

We also have new changes proposed in Incrementally Better Cookies. Mainly, make any cookie that does not have a SameSite attribute to be treated as it had a SameSite=Lax attribute. This forces developers that do not want to have same site cookies to add a SameSite=None attribute, currently not supported by Undertow. Plus, according to the document, any SameSite=None cookie must have the Secure attribute as well, which is another rule that developers must comply with.

Even though "Incrementally Better Cookies" is a draft, browsers are adhering to those changes, with highlight for Google Chrome latest changes.

Undertow needs to be updated accordingly to become compatible with those changes, and to make it easy for the developer to add a SameSite cookie attribute to their cookies without changing application code.

Issue Metadata

Issue

Dev Contacts

QE Contacts

Testing By

[X] Engineering

[ ] QE

Affected Projects or Components

  • WildFly

  • Undertow

Other Interested Projects

Requirements

Support the SameSite value "None", that currently is not supported by Undertow.

Also, given that now cookies that lack the SameSite attribute are treated as SameSite="Lax" by default, a predicate handler that adds a SameSite attribute to cookies is needed so that users can easily conform to the new changes without having to edit their application code.

Hard Requirements

We have three hard requirements for this:

  • CookieImpl.setSameSiteMode() must be able to parse and accept "None" as a parameter

  • implement a predicate handler io.undertow.server.handlers.SameSiteCookieHandler, named samesite-cookie that has the parameters:

    • mode: the SameSite Cookie mode (should be one of Strict, Lax or None)

    • cookie-pattern: optional parameter that accepts a pattern for the cookie name

    • case-sensitive: optional parameter that indicates if the pattern is case-sensitive. Defaults to true. This predicate handler adds the SameSite=mode attribute to the cookies that match cookie-pattern (or to all cookies if cookie-pattern is not specified). Notice that the matching will conform to the value of case-sensitive, i.e., will be case sensitive only is case-sensitive is either true or left unspecified.

Also, because Cookies with SameSite=None that are not Secure are rejected in the new draft, add Secure by default when None is used. This could be disabled via another optional parameter in the handler:

  • add-secure-for-none: defaults to true. Adds Secure attribute to the cookie when mode is None.

Nice-to-Have Requirements

We can add a check that verifies if the browser is compatible with the new "None" value of SameSite attribute. If the browser is not, it will mistakenly interpret the default value in a different way causing applications to malfunction.

The check will be enabled by default, but can be disabled via an optional parameter in the handler:

  • enable-client-checker: enable the client checker that prevents samesite-cookie handler from setting the SameSite="None" attribute when dealing with incompatible agents. This parameter is optional and is set to true by default.

Test Plan

Community Documentation

Currently, handlers are not listed in the WildFly documentation. We will update the Undertow community documentation with that feature.

Release Note Content

Added support for SameSite="None" cookie attributes and support for a new handler that sets SameSite attributes on cookies specified by a cookie name pattern. With this handler, web developers can remain compliant with latest changes in some browsers without editing the application code.