Transition from unpartitioned to partitioned cookies

When transitioning your site to partitioned cookies, you might encounter unexpected behavior if both a partitioned and unpartitioned cookie with the same names are present for any given client.

Setting a partitioned cookie won't override or replace an existing unpartitioned cookie with the same name. Both will exist, as long as third-party cookies are enabled, but in separate cookie jars. When third-party cookies are disabled, only the partitioned one will be accepted. If both cookies are present, it's not possible programmatically to tell which one is partitioned and which one is not, and this can lead to unexpected behavior.

There are two possible options to address this: 1. Expire the cookie you're replacing 2. Rename your cookies

Key considerations

As you transition to partitioned cookies, keep the following in mind:

  1. There is no way to programmatically determine if a cookie sent in an HTTP request is partitioned or unpartitioned. You can, however, determine a cookie's partitioned state in Chrome DevTools. You can distinguish between partitioned and unpartitioned cookies that don't have the HttpOnly attribute by using the CookieStore API.
  2. Partitioned cookies don't overwrite unpartitioned cookies—two cookies that are exactly the same (that is, have the same attributes such as name, domain, or path) will be treated as separate cookies if only one has the Partitioned attribute.
  3. It's best to avoid a situation where you'd have both a partitioned cookie and an unpartitioned cookie by the same name being returned in the same network call.

Expire the cookies you're replacing

If your site or service cannot accommodate a change in name, you can create a new partitioned cookie while expiring the existing unpartitioned cookie. While there's no way to determine whether or not a cookie is partitioned, Set-Cookie headers with a Partitioned attribute won't affect cookies that are not partitioned.

The following example shows how to expire the unpartitioned cookie called example and leave any partitioned cookies unimpacted, even if they have the same name. A new partitioned cookie called cookieName will be added or updated if it already exists.

Set-Cookie: example=-1;HttpOnly;SameSite=None;Secure;Max-Age:0
Set-Cookie: cookieName=value;Secure;SameSite=None;MaxAge=34560000;Partitioned

Rename your cookies

The most robust way to ensure that there is a seamless transition is to use different names for your partitioned and unpartitioned cookies. For example, if you have an unpartitioned cookie named "example," you can migrate it to a partitioned cookie.

Set-Cookie: example-partitioned=value;Secure;SameSite=None;MaxAge=34560000;Partitioned

Since the expiration of the cookie is not exposed programmatically, there is no way to set the new cookie's expiration to coincide with the unpartitioned cookie's expiration. It may be pragmatic to refresh the value of the cookie during this process.

Maintain both partitioned and unpartitioned cookies

During the transition period, consider maintaining two separate synced cookies: one that is partitioned and one that is not. For example, you may have both auth and auth-partitioned cookies, where the latter was set with the Partitioned attribute.

Every time that the value is updated, you should attempt to set both cookies.

  • On clients that block third-party cookies but don't support CHIPS yet: neither cookie will be accepted.
  • On clients that block third-party cookies and support CHIPS: the auth cookie will be rejected, but the auth-partitioned cookie will be accepted.
  • On clients that don't block third-party cookies, regardless of whether they support CHIPS: both auth and auth-partitioned are accepted.

When your application needs to read the authentication cookie, you should look for auth-partitioned first; but if you have to temporarily roll back the change, you can fall back to looking for the auth cookie.

Once you have established that the majority of users have had their cookies refreshed, the auth-partitioned cookie could be retired and the Partitioned attribute could be added to the regular auth cookie.