updates‎ > ‎SameSite Updates‎ > ‎

Tips for testing and debugging SameSite-by-default and “SameSite=None; Secure” cookies

What: An overview of steps you can take to test your site against Chrome’s new SameSite-by-default cookie behavior, and tips for debugging cookie issues that may be related.

Who: You should read this if your site provides or depends upon cross-site cookies. Some of these tips will probably be of limited use unless you feel comfortable using Chrome DevTools, and understand what an HTTP request is and how cookies are used in HTTP requests and responses.

How: Please use Chrome 80 or newer (Beta included). (Older versions of Chrome may implement subtly different SameSite behavior, particularly for Chrome extensions, and may not include the debugging tools mentioned below.) You can check your version number by going to chrome://version.

Testing tips

Enable the new SameSite behavior

To ensure that you are testing against the correct browser behavior, you must first enable the SameSite features directly. Please note that if you do not explicitly enable the new SameSite behavior, your browser may or may not use the new behavior (depending on whether your specific browser instance is in the control group or experimental group of the ongoing SameSite fieldtrial).

  1. Go to chrome://flags and enable both #same-site-by-default-cookies and #cookies-without-same-site-must-be-secure. You must set them to “Enabled” rather than “Default”.

  2. Restart Chrome for the changes to take effect.

  3. Verify that your browser is applying the correct SameSite behavior by visiting this test site and checking that all rows are green.

Testing your site

Thoroughly test site functionality, with a focus on anything involving federated login flows, multiple domains, or cross-site embedded content (images, videos, etc.).

For any flows involving POST requests (such as some login flows), we recommend that you test with and without a long (> 2 minute) delay, due to the 2 minute threshold for Lax+POST behavior (see below for more Lax+POST tips).

You will know if cookies used on your site will be affected by the new SameSite behavior if you see messages in the DevTools console about SameSite cookies while testing your site. Note that the presence of a message does not necessarily indicate that something is broken -- you must test thoroughly and determine that for yourself. Some of those blocked cookies may not affect any site functionality.

Testing under Lax+POST

If your site does not use POST requests, you can ignore this section.

Firstly, if you are relying on top-level, cross-site POST requests with cookies then the correct configuration is to apply SameSite=None; Secure. Under the new SameSite behavior, any cookie that was not set with a specified SameSite attribute value will be treated as SameSite=Lax by default, which will exclude cookies from these requests. However there is the “Lax+POST” special exception that Chrome makes for such cookies for the first 2 minutes after they are created, which allows them to be sent on top-level cross-site POST requests (which normal Lax cookies are excluded from). This special exception will be phased out in future Chrome releases.

When testing, you should pay special attention to any requests that require cross-site POST requests (such as some login flows). If a cookie was granted Lax+POST due to its age (< 2 minutes), but would otherwise be blocked under Lax rules, you will most likely see a message in the DevTools console about a cookie being allowed on a non-idempotent top-level cross-site request (but in some cases you may not -- check the NetLog (see below) for the definitive answer). We recommend that you test with both a short (< 2 min) and long (> 2 min) delay between setting the cookie and making the POST request.

We also recommend testing with the eventual SameSite behavior (after Lax+POST is phased out). To do this, run Chrome from the command line with the additional flag --enable-features=SameSiteDefaultChecksMethodRigorously to disable the Lax+POST exception.

For automated testing, it may be impractical to wait for 2 minutes to test the long-delay behavior. For this purpose, you can use the command line flag --enable-features=ShortLaxAllowUnsafeThreshold to lower the 2 minute threshold to 10 seconds.

Testing Chrome extensions

Chrome extensions must also abide by the new SameSite cookie behavior. Extension pages, which have a chrome-extension:// scheme URL, are generally considered cross-site to any web page (https:// or http://). There are certain scenarios where an exception is made (this is accurate as of Chrome 80, but behavior may change in the future):

  • If an extension page initiates a request to a web URL, the request is considered same-site if the extension has host permission for the requested URL in the extension’s manifest. This could happen, for example, if an extension page has an iframe embedding a site that the extension has host permission for.

  • If the top level frame (i.e. the site shown in the URL bar) is an extension page, and the extension has host permission for the requested URL, and the requested URL and the initiator of the request are same-site to each other, and the extension has host permission for the initiator origin, then the request is considered same-site. For example, this could happen if an extension has host permission for “*://*.site.example/”, and an extension page loads a.site.example in an iframe, which then navigates to b.site.example.

The chrome.cookies API is able to read and set any kind of cookie, including SameSite cookies. However, a web page embedded in an extension page is considered to be in a third party context for the purposes of document.cookie (JavaScript) accesses. For content scripts, the behavior of SameSite cookies is exactly the same as if the request were initiated from the page on which the content script is running.

If your extension embeds a web page on an extension page, we recommend testing that the necessary cookies are sent on the web request. Blocked cookies should emit warning messages in the DevTools console for the extension page. If the special exceptions above apply, no message will appear.

Something is broken! -- Debugging tips

The basics

You should suspect SameSite as the underlying problem if your site makes requests to other domains in embedded contexts (such as embedded images/videos/social posts, widgets from other sites, etc.), makes POST requests cross-site (such as in some login and payment flows), fetches cross-site resources via JavaScript, or otherwise accesses cookies across sites. If the issue is primarily a browser or tab crashing or hanging, it is less likely to be caused by the new SameSite cookie behavior.

First, check if the problem persists after setting the SameSite flags above to “Disabled” (note: setting them to “Default” may or may not disable the features). Remember to restart your browser for the changes to take effect. If the problem persists, you should suspect a root cause other than the new SameSite cookie behavior.

If you have turned on third-party cookie blocking (see chrome://settings/content/cookies), try turning it off. This is particularly relevant for Android WebViews, which block third-party cookies by default, even if they have SameSite=None and Secure.

Try clearing your cache and cookies or testing in Incognito Mode to see if the problem still reproduces.

Check the DevTools console for warning messages about SameSite cookies. Unfortunately, Chrome can only tell you when there are cookies that will behave differently under the new SameSite behavior, but it can’t tell you which cookies might be responsible for site breakage. However, if there are no messages about SameSite cookies on any important domains, there may be a different root cause to the problem.

Using the DevTools Network panel

Open the Network panel in DevTools and capture the network activity that occurs when reproducing the problem. Find the request or requests that are not working properly. This may be a request that returns an error code like 403, it may be highlighted in red, etc. It may be helpful to filter by the cookie domains indicated in the SameSite warning messages, as those requests will have been affected by the new SameSite changes. Another helpful way to filter requests is to click on the "Has blocked cookies" checkbox at the rightmost side of the toolbar with the filter box. (In Chrome 80, this option is called "Only show requests with SameSite issues". See more info about upcoming DevTools features that may be helpful.)

Click on the problematic request and go to the Cookies tab (right under the timeline, next to Headers, Preview, Response, Timing, etc.). Click on “show filtered out request cookies”. All the rows highlighted in yellow are cookies that were excluded from the request or rejected from the response for one reason or another. If you hover over these blocked cookies, a tooltip will explain why that cookie was excluded. There may be multiple reasons why a cookie was excluded.

Look for cookies that were excluded solely for SameSite reasons. If any of these cookies are important to site functionality, their absence is likely the cause of the problem and they will need to be updated to comply with the new SameSite behavior.

Using Chrome histograms

Chrome records metrics ("histograms") about internal activity as you browse the web. These can help diagnose cookie problems.

Go to chrome://histograms and look for the following entries:

  • Cookie.SameSiteUnspecifiedEffective: This histogram logs the "effective" SameSite mode of every cookie that did not specify a SameSite attribute, i.e. what SameSite rules the browser actually applied to it. The "0" bucket corresponds to None, the "1" bucket corresponds to Lax, and the "3" bucket corresponds to Lax and eligible for Lax+POST.
  • Cookie.SameSiteNoneIsSecure: This histogram logs whether a SameSite=None cookie was Secure. The "0" bucket means not Secure, and the "1" bucket means Secure.
  • Cookie.LaxAllowUnsafeCookieIncludedAge: This histogram logs the age (in milliseconds) of a cookie that is included with a POST request due to Lax+POST.
  • Cookie.SameSiteUnspecifiedTooOldToAllowUnsafe: This histogram logs the age (in milliseconds) of a cookie that could have been included with a POST request, under Lax+POST, but is instead too old to include.
To debug your own site, you can hit "Refresh" at the top of the page to clear the previous histogram entries, then check the histogram entries again after reproducing the problem.

For the full descriptions of every histogram, see histograms.xml and enums.xml in the Chromium source tree.

Using a NetLog dump

For this section, we recommend using Chrome 82, which logs more information than previous versions and may make it easier to identify problematic cookies.

Capture a NetLog dump (a record of all network activity) by following these instructions. Make sure to select “Include cookies and credentials” when you capture the log. (Since such a log may contain sensitive information, such as cookies with login information, use your judgement when sharing it with others.) Use the NetLog viewer to open the captured log.

Click on Events in the sidebar and enter “type:url_request” in the search bar to view all the HTTP(S) requests captured in the log. You can additionally filter by requests with cookies blocked due to SameSite by adding “exclude_samesite” to the search bar.

If you click on each request, you can look for the following things:

  • Any COOKIE_INCLUSION_STATUS entry with status "EXCLUDE_SAMESITE_UNSPECIFIED_TREATED_AS_LAX, WARN_SAMESITE_UNSPECIFIED_CROSS_SITE_CONTEXT" and no other exclusion reasons. This will indicate that the cookie was blocked because of the SameSite-Lax-by-default rules, but would not have been blocked otherwise.

  • Statuses with "WARN_SAMESITE_UNSPECIFIED_LAX_ALLOW_UNSAFE". This would indicate that the cookie would be expected to be blocked under Lax-by-default, but is instead allowed due to the 2 minute Lax+POST intervention. Such a cookie may not be causing problems now, but will in the future when Lax+POST is deprecated.

  • Statuses with "EXCLUDE_SAMESITE_NONE_INSECURE, WARN_SAMESITE_NONE_INSECURE" and no other exclusion reasons. This would indicate that the cookie was blocked because of Cookies-without-SameSite-must-be-Secure, but would not have been blocked otherwise.

Both request and response cookies are shown here. If you suspect that your server’s Set-Cookie response header is incorrect, you can search for “type:cookie_store” and look for a COOKIE_STORE_COOKIE_ADDED entry, which will list the properties of the cookie, as interpreted by Chrome.

To check whether Chrome considers a request cross-site, you can compare the site_for_cookies property of the request (this represents the top-frame origin) with the URL of the request. If these have the same registrable domain or eTLD+1 (the effective Top Level Domain -- something like .com or .net or .co.uk -- as well as the label immediately to its left) then the request is most likely considered at least Laxly same-site (except in some cases with POST requests) and should attach Lax cookies. If they have different registrable domains, or if the site_for_cookies has an empty registrable domain, the request is always considered cross-site. The if the initiator property of the request is either "not an origin" or also shares the same registrable domain as the site_for_cookies and the request URL, then the request should additionally attach Strict cookies.

The NetLog only covers cookies accessed over the network via HTTP(S) and does not include other methods of cookie access such as document.cookie (JavaScript) or chrome.cookies (extensions). For far more information about debugging using NetLogs, refer to this document.

I found the problematic cookie(s). Now what?

  • If the cookie is on a domain you control: You will need to update that cookie by setting SameSite=None; Secure on it. See resources here and here.

  • If the cookie is on a third-party domain: You should reach out to the owner of the domain setting that cookie and ask them to update it with SameSite=None; Secure.

Still stuck? Post a question with the “samesite” tag on Stack Overflow, or file a Chrome bug using this template.