First-Party Sets testing instructions

The latest iteration of First-Party Sets is ready for developer feature-flag testing from Chrome 108.

Ecosystem feedback has highlighted cross-site use cases that will be impacted when third-party cookies are no longer supported in Chrome. The First-Party Sets proposal examines and addresses a class of cross-site use cases in which the interdependent sites share a relationship that can be expressed to the browser such that the browser can take the appropriate action on behalf of the user and/or effectively present that information to the user.

The updated proposal uses two APIs (the Storage Access API and a new API tentatively named requestStorageAccessForOrigin) to provide sites with an active method of requesting cross-site access for their cookies within a First-Party Set. The instructions below should allow you to test and validate what sets you may want to create for your sites and the right points to call the two different APIs.

# First-Party Sets overview

First-Party Sets (FPS) is a web platform mechanism for developers to declare relationships among sites, so that browsers can use this information to enable limited cross-site cookie access for specific, user-facing purposes. Chrome will use these declared relationships to decide when to allow or deny a site access to their cookies when in a third-party context.

At a high level, a First-Party Set is a collection of domains, for which there is a single «set primary» and potentially multiple «set members». Only site authors are able to submit their domains to a set, and they will be required to declare the relationship between each «set member» to its «set primary». Set members can include a range of different domain types with subsets based on use cases.

To facilitate the browser’s handling of each subset according to the privacy implications of each subset, we are proposing leveraging the Storage Access API (SAA) and requestStorageAccessForOrigin to enable cookie access within a FPS.

With the SAA, sites may actively request cross-site cookie access. Chrome will automatically grant the request if the requesting site and the top-level website are in the same FPS. Please see Storage Access API (SAA) documentation for information on how calls to SAA are processed by other browsers.

SAA currently requires that the document obtains user activation before calling the API’s methods.

This can make adopting FPS challenging for top-level sites that use cross-site images or script tags requiring cookies. To address some of these challenges we’ve proposed a new API, requestStorageAccessForOrigin, to make it easier for developers to adopt this change. This API is also available for testing.

# Set submission

The canonical FPS list will be a publicly viewable list in a JSON file format housed in a new FPS GitHub repository, which will serve as the source-of-truth for all sets. Chrome will consume this file to apply to its behavior.

To learn more about the proposed process and requirements for submitting sets, check out the submission guidelines. You can also try submitting a set to test the various technical checks that will validate the submissions. Note that all submissions will be cleared before FPS is available in stable versions of Chrome.

As the set submission process is still under active development, for local testing, you can only create sets on the command line and pass them directly to the browser. For local testing, it is not required to submit a set to the GitHub repo in order to test with feature flags.

# How to test locally

# Prerequisites

To test FPS locally, use Chrome 108 or higher launched from the command line.

To preview upcoming Chrome features before they’re released, download the Beta or Canary version of Chrome.

# Example

google-chrome 
--enable-features="FirstPartySets:FirstPartySetsClearSiteDataOnChangedSets/1,StorageAccessAPI,StorageAccessAPIForOriginExtension,PageInfoCookiesSubpage,PrivacySandboxFirstPartySetsUI" 
--use-first-party-set="{"primary": "https://first-party-sets.glitch.me", "associatedSites": }" 

Learn more about how to run Chromium with flags.

# Steps

To enable FPS locally, you need to use Chrome’s --enable-features option with a comma-separated list of flags that are explained in this section and declare a set of related sites as a JSON object to pass to --use-first-party-set.

# Enable FPS

FirstPartySets enables FPS in Chrome.

FirstPartySets:FirstPartySetsClearSiteDataOnChangedSets/1

Starting in Chrome M109, the additional parameter FirstPartySetsClearSiteDataOnChangedSets/1 will enable clearing site data in case members of a set change. This prevents linking a user’s identity across all the sets a site has historically been in. This behavior will be the default in Chrome.

# Enable Storage Access API

StorageAccessAPI

Enables Storage Access API (SAA) in Chrome which allows embedded iframes to use requestStorageAccess() to request access to cookies in a cross-site context, even when third-party cookies are blocked by the browser.

Note that when called, requestStorageAccess() requires a user gesture in order to resolve. Future versions of Chrome may impose different sets of requirements, as the SAA specification is still evolving. Refer here for a list of planned improvements to Chrome’s implementation of the SAA.

StorageAccessAPIForOriginExtension

Enables top-level sites to use requestStorageAccessForOrigin() to request storage access on behalf of specific origins. This is useful for top-level sites that use cross-site images or script tags requiring cookies and addresses some of the challenges in adopting SAA.

# Declare a set locally

A First-Party Set is a collection of domains, for which there is a single «set primary» and potentially multiple «set members». Set members can include a range of different domain types with subsets based on use cases.

Create a JSON object that contains URLs that are members of a set and pass it to --use-first-party-set.

In the example below, primary lists the primary domain, and associatedSites lists domains that meet the requirements of the associated subset.

{
"primary": "https://primary.com",
"associatedSites": 
}

Example:

--use-first-party-set="{"primary": "https://first-party-sets.glitch.me", "associatedSites": }"

For local testing, you can only create sets on the command line and pass them directly to the browser. For local testing purposes there will be no set validation, but when FPS ships in stable versions, all sets will need to be submitted to the FPS GitHub repo and be subject to validation criteria.

# Enable FPS UI

PageInfoCookiesSubpage

Enables showing FPS in the PageInfo section accessible from the URL bar.

PrivacySandboxFirstPartySetsUI

Enables FPS UI «Allow related sites to see your activity in the group» option in Chrome settings, under Privacy and Security → Cookies and other site data (chrome://settings/cookies).

# Verify that third party cookies are blocked

1. In Chrome settings, go to Privacy and Security → Cookies and other site data or chrome://settings/cookies.
2. Under General settings ensure that «Block third-party cookies» is enabled.
3. Check that the sub-option «Allow related sites to see your activity in the group» is also enabled.

# Security considerations

Since Storage Access API allows websites to regain access to third-party cookies in select cases, it may leave web applications susceptible to cross-site attacks and information leaks. Sites that rely on cookies in cross-site contexts should be aware of the risks of CSRF and other attacks.

# Planned improvements

To improve this, future Chrome releases will require additional security controls, with the goal of ensuring explicit embeddee opt-in. The proposed improvements would: only grant access on a per-frame basis, require CORS on credentialed requests, and keep the scope of access to the origin only. You can read more in the recent security analysis.

Check out the list of planned improvements to Chrome’s implementation of the SAA.

Note that Chrome only sends cookies marked SameSite=None in cross-site embedded contexts, which is where the Storage Access API is relevant. Until all browsers have deprecated default access to those cookies, however, no assumptions can be made about where the cookie could be used. It is not safe to assume that access would only be allowed within an FPS, and sites should continue using standard security best practices.

# Engage and share feedback

Local testing is an opportunity to try out the Storage Access API mechanism for enabling FPS and share feedback or any issues you run into. Additionally, testing out the set submission process on GitHub is an opportunity to share your experience with the process and validation steps. To engage and share feedback about the updated proposal:

• Raise issues and follow the discussion on GitHub.
• Ask questions and join discussions on the Privacy Sandbox Developer Support repo.
• Explore different avenues for giving feedback on Privacy Sandbox proposals.