Manual:SameSite cookies

From mediawiki.org
Jump to navigation Jump to search

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[edit]

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[edit]

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.

Using SameSite cookies in MediaWiki[edit]

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().

Debugging and bug reports[edit]

See also[edit]

Notes[edit]

  1. Chrome applies some legacy exceptions. See "Lax + POST mitigation" in their FAQ.