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 compatibilityEdit

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 warningsEdit

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 MediaWikiEdit

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 reportsEdit

See alsoEdit


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