Introducing State Partitioning

State Partitioning is the technical term for a new privacy feature in Firefox called Total Cookie Protection, which will be available in ETP Strict Mode in Firefox 86. This article shows how State Partitioning works inside of Firefox and explains what developers of third-party integrations can do to stay compatible with the latest changes.

Web sites utilize a variety of different APIs to store data in the browser. Most famous are cookies, which are commonly used to build login sessions and provide a customized user experience. We call these stateful APIs, because they are able to establish state that will persist through reloads, navigations and browser restarts. While these APIs allow developers to enrich a user’s web experience, they also enable nefarious web tracking which jeopardizes user privacy. To fight abuse of these APIs Mozilla is introducing State Partitioning in Firefox 86.

Stateful Web APIs in Firefox are:

  • Storage: Cookies, Local Storage, Session Storage, Cache Storage, and IndexedDB
  • Workers: SharedWorkers and ServiceWorkers
  • Communication channel: Broadcast channel

To fight against web tracking, Firefox currently relies on Enhanced Tracking Protection (ETP) which blocks cookies and other shared state from known trackers, based on the Disconnect list. This form of cookie blocking is an effective approach to stop tracking, but it has its limitations. ETP protects users from the 3000 most common and pervasive identified trackers, but its protection relies on the fact that the list is complete and always up-to-date. Ensuring completeness is difficult, and trackers can try to circumvent the list by registering new domain names. Additionally, identifying trackers is a time-consuming task and commonly adds a delay on a scale of months before a new tracking domain is added to the list.

To address the limitations of ETP and provide comprehensive protection against trackers, we introduce a technique called State Partitioning, which will prevent cookie-based tracking universally, without the need for a list.

State Partitioning is complemented by our efforts to eliminate the usage of non-traditional storage mechanisms (“supercookies”) as a tracking vector, for example through the partitioning of network state, which was recently rolled out in Firefox 85.

State Partitioning – How it works in Firefox

To explain State Partitioning, we should first take a look at how stateful Web APIs enable tracking on the Web.  While these APIs were not designed for tracking, their state is shared with a website regardless of whether it is loaded as a first-party or embedded as a third-party, for example in an iframe or as a simple image (“tracking pixel”). This shared state allows trackers embedded in other websites to track you across the Web, most commonly by setting cookies.

For example, a cookie of will be shared on and if they both embed as a third-party. So, can connect your activities on both sites by using the cookie as an identifier.

ETP will prevent this by simply blocking access to shared state for embedded instances of Without the ability to set cookies, the tracker can not easily re-identify you.

Cookie-based tracking without protections, both instances of share the same cookie.


In comparison, State Partitioning will also prevent shared third-party state, but it does so without blocking cookie access entirely. With State Partitioning, shared state such as cookies, localStorage, etc. will be partitioned (isolated) by the top-level website you’re visiting. In other words, every first party and its embedded third-party contexts will be put into a self-contained bucket.

Firefox is using double-keying to implement State Partitioning, which will add an additional key to the origin of the website that is accessing these states. We use the scheme and registrable domain (also known as eTLD+1) of the top-level site as the additional key. Following the above example, cookies for will be keyed differently under and Instead of looking up the cookie jar for, Storage partitioning will use^ and^ respectively.

Cookie-based tracking prevented by State Partitioning, by double-keying both instances of


Thus, there will be two distinct cookie jars for under these two top-level websites.

This takes away the tracker’s ability to use cookies and other previously shared state to identify individuals across sites. Now the state is separate (“partitioned”) instead of shared across different first-party domains.

It is important to understand that State Partitioning will apply to every embedded third-party resource, regardless of whether it is a tracker or not.

This brings great benefits for privacy allowing us to extend protections beyond the Disconnect list and it allows embedded websites to continue to use their cookies and storage as they normally would, as long as they don’t need cross-site access. In the next section we will examine what embedded websites can do if they have a legitimate need for cross-site shared state.

State Partitioning – Web Compatibility

Given that State Partitioning brings a fundamental change to Firefox, ensuring web compatibility and an unbroken user and developer experience is a top concern. Inevitably, State Partitioning will break websites by preventing legitimate uses of third-party state. For example, Single Sign-On (SSO) services rely on third-party cookies to sign in users across multiple websites. State Partitioning will break SSO because the SSO provider will not be able to access its first-party state when embedded in another top-level website so that it is unable to recognize a logged-in user.

Third-party SSO cookies partitioned by State Partitioning, the SSO iframe cannot get the first-party cookie access.


In order to resolve these compatibility issues of State Partitioning, we allow the state to be unpartitioned in certain cases. When unpartitioning is taking effect, we will stop using double-keying and revert the ordinary (first-party) key.

Given the above example, after unpartitioning, the top-level SSO site and the embedded SSO service’s iframe will start to use the same storage key, meaning that they will both access the same cookie jar. So, the iframe can get the login credentials via a third-party cookie.

The SSO site has been unpartitioned, the SSO iframe gets the first-party cookie access.


State Partitioning – Getting Cross-Site Cookie Access

There are two scenarios in which Firefox might unpartition states for websites to allow for access to first-party (cross-site) cookies and other state:

  1. When an embedded iframe calls the Storage Access API.
  2. Based on a set of automated heuristics.

Storage Access API

The Storage Access API is a newly proposed JavaScript API to handle legitimate exceptions from privacy protections in modern browsers, such as ETP in Firefox or Intelligent Tracking Prevention in Safari. It allows the restricted third-party context to request first-party storage access (access to cookies and other shared state) for itself. In some cases, browsers will show a permission prompt to decide whether they trust the third party enough to allow this access.

The Firefox user prompt of the Storage Access API.


A partitioned third-party context can use the Storage Access API to gain a storage permission which grants unpartitioned access to its first-party state.

This functionality is expressed through the document.requestStorageAccess method. Another method, document.hasStorageAccess, can be used to find out whether your current browsing context has access to its first party storage. As outlined on MDN, document.requestStorage is subject to a number of restrictions, standardized as well as browser-specific, that protect users from abuse. Developers should make note of these and adjust their site’s user experience accordingly.

As an example, Zendesk will show a message with a call-to-action element to handle the standard requirement of transient user activation (e.g. a button click). In Safari, it will also spawn a popup that the user has to activate to ensure that the browser-specific requirements of Webkit are satisfied.

Zendesk notification to allow the user to trigger the request for storage access.


After the user has granted access, Firefox will remember the storage permission for 30 days.

Note that the third-party context will only be unpartitioned under the top-level domain for which the storage access has been requested. For other top-level domains, the third-party context will still be partitioned. Let’s say there is a cross-origin iframe which is embedded in And uses the Storage Access API to request first-party access on and the user allows it. In this case, will have unpartitioned access to its own first-party cookies on Later, the user loads another page which also embeds But, this time, the will remain partitioned under because there is no storage permission here.

document.hasStorageAccess().then(hasAccess => {
if (!hasAccess) {
return document.requestStorageAccess();
}).then(_ => {
// Now we have unpartitioned storage access for the next 30 days!
// …
}).catch(_ => {
// error obtaining storage access.

Javascript example of using the Storage Access API to get the storage access from users.

Currently, the Storage Access API is supported by Safari, Edge, Firefox. It is behind a feature flag in Chrome.

Automatic unpartitioning through heuristics

In the Firefox storage access policy, we have defined several heuristics to address Web compatibility issues. The heuristics are designed to catch the most common scenarios of using third-party storage on the web (outside of tracking) and allow storage access in order to make websites continue normally. For example, in Single-Sign-On flows it is common to open a popup that allows the user to sign in, and transmit that sign-in information back to the website that opened the popup. Firefox will detect this case and automatically grant storage access.

Note that these heuristics are not designed for the long term. Using the Storage Access API is the recommended solution for websites that need unpartitioned access. We will continually evaluate the necessity of the restrictions and remove them as appropriate. Therefore, developers should not rely on them now or in the future.

State Partitioning – User controls for Cross-Site Cookie Access

We have introduced a new UI for State Partitioning which allows users to be aware of which third parties have acquired unpartitioned storage and provides fine-grain control of storage access. Firefox will show the unpartitioned domains in the permission section of the site identity panel. The “Cross-site Cookies” permission indicates the unpartitioned domain, and users can delete the permission from the UI directly by clicking the cancel button alongside the permission entries.

About Johann Hofmann

Firefox Security & Privacy Engineer

More articles by Johann Hofmann…

About Tim Huang

Firefox Privacy Engineer

More articles by Tim Huang…


  1. Fazal Majid

    What about other forms of state, like caches (fonts and favicons), HSTS, Etags and other stateful mechanisms that can be abused for tracking?

    February 23rd, 2021 at 07:18

  2. Graham Perrin

    Consistency: leads to ‘Dynamic Partitioning’.

    Should it not lead to ‘Dynamic State Partitioning’?

    February 23rd, 2021 at 11:58

  3. voracity

    This looks quite good, but doesn’t a 30 day expiry make SSO in practice unworkable? Or perhaps there is some way around this that I’ve missed, like unpartitioned data being copied to both partitions on expiry (seems unlikely), or an ability to specify whether a cookie/state goes into the unpartitioned or partitioned space when granted unpartitioned access, so that the key cookies are unaffected when The Great Partitioning occurs?

    February 24th, 2021 at 04:21

  4. Bill Wadley

    As always, Firefox is ahead of the curve in keeping the Net safe.

    Thank you!

    February 24th, 2021 at 10:26

  5. Ronald Scott

    Will this break sending cookies on cross-domain form POST actions, thereby breaking every federated SAML implementation in the entire world?

    February 24th, 2021 at 10:49

  6. gwarser

    Any way to disable “Web Compatibility Heuristics” right now?

    February 25th, 2021 at 14:31

  7. antistress

    Hi, Thanks for the article. Could you please explain the difference between latest Total Cookie Protection and former First-Party Isolation ?

    February 25th, 2021 at 15:01

    1. antistress

      Answer to myself
      Total Cookie Protection = state partitioning = dynamic first-party isolation

      “The most important difference between DFPI and FPI is that DFPI will adhere to exceptions granted through the storage access API and thus ensure better Web compatibility”

      February 26th, 2021 at 06:25

  8. Helle Vaanzinn

    Thank you both for explaining this new privacy feature. Not being an expert in these matters, merely an interested Firefox user, I came across For the non-tech-savvy user this is all rather confusing, so it would be very enlightening if someone could elaborate. Does ‘state partitioning’ offer any protection against these CNAME-based tracking attempts?

    By abusings DNS records to erase the distinction between first-party and third-party contexts the author seems to suggest that third-party cookie blocking is rendered ineffective. That much I (think) I understand. Quoting the author:

    “As of today, from the major web browser vendors only Firefox offers technical capabilities enabling defenses by extensions, Safari has partial mitigations (cookie leaks still exist), and Brave browser offers defences based on blocking of CNAME leaks. Since uBlock version 1.25 under Firefox, the extension dynamically resolves hosts and sanitises such requests if a match is found.”

    That being very good news for Firefox users, it still assumes being knowledgeable enough to install uBlock Origin, which seems far from ideal. Are there any plans to incorporate the technique(s) used by this very fine addon into the web browser itself?


    February 25th, 2021 at 23:36

  9. Thanks!

    In Strict Mode “privacy.annotate_channels.strict_list.enabled” is set to “true”. This setting is not changed when switching to the custom mode. This is independent of the settings one chooses in custom mode. Therefore, it is not possible to know the state of “privacy.annotate_channels.strict_list.enabled” by checking the custom mode settings.

    February 26th, 2021 at 00:43

  10. Thanks!

    Fantastic that Mozilla has introduced State Partitioning in Firefox! Many thanks! Let’s hope that it will not foster browser fingerprinting!
    Selecting “ETP Strict Mode” sets five preferences in prefs.js: browser.contentblocking.category = strict, network.cookie.cookieBehavior = 5, privacy.annotate_channels.strict_list.enabled = true, privacy.trackingprotection.enabled = true, privacy.trackingprotection.socialtracking.enabled = true.
    Is it enough to set “network.cookie.cookieBehavior = 5” to only activate State Partitioning (without enabling tracking protection based on the Disconnect blocking list) ?

    February 26th, 2021 at 00:46

  11. Mark de Roussier

    I don’t use SSO if I can possibly avoid it. But now, I’m constantly going to websites and being forced to manually turn off the permissions that Firefox automatically grants, against my will, to SSO providers. I have no choice about this, there’s no option I can set to turn off this behaviour, and it’s extremely annoying. Why should I have to tolerate these cookies being allowed unless I want them ? Isn’t that the point of having site specific control under the ‘strict’ option ? Now Firefox seems to have taken that control away and to be overriding the user’s desires. This feature is touted as some sort of great advance, but in practice it’s a PITA if you really *don’t* want third party cookies unless you explicitly permit them. When I revoke permissions that Firefox has granted without my permission, Firefox should at least remember the fact that I don’t want this domain permitted.

    March 20th, 2021 at 19:11

Comments are closed for this article.