Manual:SameSite cookies
SameSite is a recent addition to the syntax of HTTP cookies.
If a cookie is marked as SameSite=Lax or SameSite=Strict, the browser will not send it with cross-domain requests.
(The difference between the two is in the interpretation of "cross-domain": for Lax, it only covers "hidden" requests such as AJAX or iframes, while for Strict, top-level user navigation such as clicking on a link going to another domain is also included.) Browsers are planning to default cookies with no SameSite specification to Lax; as of 2020 autumn, Chrome is the only one actually doing it.[1] Sites running over multiple domains that are not prepared for this change might experience various issues, such as authentication failures.
(Sites running on a single domain will not be affected.)
As of 1.34, MediaWiki supports setting the SameSite flag on cookies.
The default for authentication-related cookies is determined by the $wgCookieSameSite setting.
Setting this to None (and enabling $wgForceHTTPS, as use of secure HTTPS cookies is required by browsers for SameSite=None) can fix issues such as MediaWiki seeing the user as not logged in when using cross-domain features.
Setting the flag on non-authentication cookies is the responsibility of the code handling the cookie; this can only be decided individually, and in most cases it is not needed.
Browser compatibility
An older version of the standard defined SameSite as a boolean flag; older versions of browsers which implement this interpret SameSite=<anything> as SameSite=Strict.
To work around this, MediaWiki can set a second, fallback cookie which is compatible with old browsers but not new ones.
This behavior is enabled by setting $wgUseSameSiteLegacyCookies to true.
Browser warnings
Browsers can show various warnings on cookies which do not have the SameSite flag, e.g. Firefox tends to show errors like this in the developer console: Cookie “<name>” will be soon rejected because it has the “sameSite” attribute set to “none” or an invalid value, without the “secure” attribute. This is a confusing and poorly worded message; what it is supposed to mean is that the cookie will soon be treated as SameSite=Lax and thus not sent with cross-domain AJAX requests.
For most non-authentication cookies this is not a problem and the warning can be ignored.
It might be worth to explicitly set SameSite=Lax to get rid of the warning, though.
Using SameSite cookies in MediaWiki
In PHP, to set the SameSite flag on a cookie, use WebResponse::setCookie() with $options['sameSite'] = 'lax' or similar.
To take $wgUseSameSiteLegacyCookies compatibility cookie into account when reading cookies, use WebRequest::getCrossSiteCookie() instead of WebRequest::getCookie().
In Javascript, use the sameSite property of the options object passed to $.cookie to set the SameSite flag on a cookie.
Debugging and bug reports
- https://samesite-sandbox.glitch.me/ can be used to check a browser's standard compliance. With the new default-to-Lax SameSite behavior, it should be all green.
- Set specific SameSite handling behavior for testing:
- Chrome:
same-site-by-default-cookiesandcookies-without-same-site-must-be-secureflags (see also their debugging tutorial) - Firefox:
network.cookie.sameSite.laxByDefaultandnetwork.cookie.sameSite.noneRequiresSecureconfiguration keys
- Chrome:
See also
- Documentation on MDN
- caniuse browser stats and docs
- The draft standards for SameSite and for defaulting to Lax.
- Manual:HTTPS
- Main task for SameSite issues: T255366
